svn commit: r235275 - projects user

Fri May 11 16:08:52 UTC 2012

Author: uqs
Date: Fri May 11 16:08:51 2012
New Revision: 235275
URL: http://svn.freebsd.org/changeset/base/235275

Log:
  Update guidelines on user/ and projects/
  
  The goal is to make it clearer where future branches should be created. A
  consistent layout under projects/ would also help with conversions to other
  VCSes that do not follow the everything-is-a-subdir dogma.
  
  TL;DR
  - If it's a branch of head that you want to merge back -> projects/
  - If it's something else -> user/your-login/ (e.g. portmaster, stress2, etc.)
  
  Discussed on:	developers
  Silence by:	peter

Modified:
  user/GUIDELINES.txt

Changes in other areas also in this revision:
Modified:
  projects/GUIDELINES.txt

Modified: user/GUIDELINES.txt
==============================================================================

--- user/GUIDELINES.txt	Fri May 11 16:04:55 2012	(r235274)
+++ user/GUIDELINES.txt	Fri May 11 16:08:51 2012	(r235275)
@@ -1,16 +1,9 @@
 $FreeBSD$
 
-Golden rules:
-Rule #1:  TAKE IT EASY! DON'T RUSH AND MAKE A MESS!  ASK IF NEEDED!
-Rule #2:  See rule #1, repeat as needed
+Guidelines for what can go in /user
+-----------------------------------
 
-Peril sensitive sunglasses advisory:
-This is in flux.  Expect refinement.  Expect typos.
-
-Guidelines for what can go in /user and /projects
--------------------------------------------------
-
-First of all, eveyrbody needs to keep in mind that this repository is
+First of all, everybody needs to keep in mind that this repository is
 replicated as a unit.  Anything that goes into the repository uses project
 and volunteer resources.  Once something goes in, it essentially never comes
 out.  Therefore, these are not dumping grounds to put random junk in the
@@ -19,82 +12,39 @@ tree that we have to mirror forever.
 General guidelines:
 
 * Should be relevant to FreeBSD.
-* Should be at least concievably of interest to somebody else.
-* Should be in a format that is suitable to merge into the base tree.
+* Should be at least conceivably of interest to somebody else.
 * Should be something that is worth people's time to read commit mail for.
 * Write decent commit messages!
 
+The difference between /projects and /user wasn't very clear in the past.
+Going forward /projects is reserved for branches of FreeBSD itself for possible
+re-integration into /head. Branches shall not be nested into e.g.
+/projects/foo/stable8, instead /projects/foo_stable8 shall be used.
 
-The difference between /projects and /user is mostly one of intentions.
-
-If some WIP is intended to be committed to the main src tree, then it
-should go in /projects/$name/*.  We encourage people to subscribe to projects
-commit messages.  The reason is that WIP in projects can be expected to hit
-the base tree at some point.
-
-If some WIP is more of an experiment or speculative, that might not ever be
-merged, then it goes in /user/$username/$name/*.  We don't encourage
-people to subscribe to user commit messages.
-
-If it is something unrelated to the src tree, it should probably go elsewhere.
-There will be a separate repostory made available for such things, whether it
-be a special version of mysql or xorg or gcc or whatever.
-
+/user can be used for tools and software tightly related to FreeBSD, but which
+is not a copy/branch of FreeBSD itself.
 
 Layout:
-Since this is for WIP that can concievably be merged, there is an argument
-that can be made that teaching the pre-commit scripts to sanity check WIP
-as it goes, rather than having a mammoth fixup being needed prior to merging.
-
-For that to work, the layout has to be predictable.  eg: a branch of
-"head/sys/*" for a project called "ia65" should be  /projects/ia65/sys/*.
-An experimental X11-aware verison of bin/ls/* in a user directory for jdoe
-would be /user/jdoe/x11-ls/bin/ls/*.
-
 
-Creation and merging:
-
-Merging is in flux.  The procedure as understood right now:
-
-Assume projects/ia65/sys.   $BASE="svn+ssh://svn.freebsd.org/base"
+Since this is for auxiliary/experimental projects that might not be branched
+from head, an argument can be made that we teach the pre-commit scripts to
+sanity check WIP as it goes in.
 
 Initial creation:
-  $ svn cp --parents $BASE/head/sys $BASE/projects/ia65/sys
+  Assume user/pho/stress2.   BASE="svn+ssh://svn.freebsd.org/base"
 
-Then check it out:
-  $ svn co $BASE/projects/ia65
+  $ svn mkdir $BASE/user/pho/stress2
 
-To integrate changes from head into your branch:
-  $ cd ia65/sys ; svn update; svn status | read output!  Should preferably be clean.
-  (you may prefer to do merges in a second, clean checkout. It will be easier!)
-  $ svn merge $BASE/head/sys
-  (this merges head/sys/* into ., which is projects/ia65/sys)
+Then check it out:
+  $ svn co $BASE/user/pho/stress2
+  $ hack, hack, hack
+  $ svn add .
+  (should schedule all files/dirs for addition)
+  $ svn status
+  (verify all files you want added, and only those are scheduled)
   $ svn commit
 
-To merge your changes into head/sys.
-  $ mail -s 'Is it ok to merge projects/ia65 to head?' peter at freebsd.org
-  $ wait_for_reply (the point is to have somebody on hand for the first
-    timeto help rescue you if things go horribly wrong.)
-  (set up a clean checkout of head/sys and projects/ia65/sys.  MUST BE CLEAN!!)
-  $ cd work
-  $ svn co $BASE/head/sys
-  $ svn co $BASE/projects/ia65/sys
-  (If you've already got clean checkouts handy, replace with appropriate
-   svn update commands)
-  $ svn info head  - NOTE CHANGE NUMBER!!!  assume 12345 for this example.
-  (now, bring projects/ia65 up to date with head, AS YOU JUST CHECKED IT OUT)
-  $ svn merge $BASE/head/sys at 12345 projects/ia65/sys
-  (resolve conflicts)
-  $ svn commit projects/ia65/sys
-  (now, projects/ia65 is in sync with @12345, as is your head checkout)
-  (reverse merge to base tree!)
-  $ svn merge $BASE/projects/ia65/sys head/sys
-  (resolve conflicts)
-  $ svn commit head/sys
-  $ profit!
-  (regular svn users might wonder about merge --reintegrate.  Our tree breaks
-   it, sorry.  We can't use it.)
-
-Tags:
-  Place tags in your /user area if possible, even if the origin is a project.
-  Tag by using svn cp $BASE/projects/xxx $BASE/user/jdoe/yyy.
+Other:
+
+If it is not covered here, and there's no established practice of doing what
+you're trying to achieve, always ask your peers first!
