svn commit: r183719 - user

[Peter Wemm]

Author: peter
Date: Thu Oct  9 10:01:09 2008
New Revision: 183719
URL: http://svn.freebsd.org/changeset/base/183719

Log:
  Add a quick braindump about the state of /user and /projects

Added:
  user/GUIDELINES.txt   (contents, props changed)

Added: user/GUIDELINES.txt
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ user/GUIDELINES.txt	Thu Oct  9 10:01:09 2008	(r183719)
@@ -0,0 +1,95 @@
+$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
+
+Peril sensitive sunglasses advisory:
+This is in flux.  Expect refinement.
+
+Guidelines for what can go in /user and /projects
+-------------------------------------------------
+
+First of all, eveyrbody 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
+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 something that is worth people's time to read commit mail for.
+* Write decent commit messages!
+
+
+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.
+
+
+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:
+
+Assue projects/ia65/sys.   $BASE="svn+ssh://svn.freebsd.org/base"
+
+Initial creation:
+  $ svn cp --parents $BASE/head/sys $BASE/projects/ia65/sys
+
+Then check it out:
+  $ svn co $BASE/projects/ia65
+
+To integrate changes from head into your branch:
+  $ cd ia65 ; 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)
+  $ 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
+  (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
+  $ 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!
+
+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.