$FreeBSD$

Guidelines for what can go in /projects
---------------------------------------

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
tree that we have to mirror forever.

General guidelines:

* Should be relevant to FreeBSD.
* Should be at least conceivably 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 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.

/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 conceivably be merged, an argument can be made
that we teach the pre-commit scripts to sanity check WIP as it goes in, rather
than having a mammoth fixup being needed prior to merging.

For that to work, the layout has to be predictable, e.g. a branch of
"head/*" for a project called "ia65" should be  /projects/ia65/*.
An experimental X11-aware version of bin/ls/* would be
/projects/x11-ls/bin/ls/*.


Creation and merging:

Merging is in flux.  The procedure as understood right now:

Initial creation:
  Assume projects/ia65.   BASE="svn+ssh://svn.freebsd.org/base"

  $ svn cp --parents $BASE/head $BASE/projects/ia65

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
  (this merges head/* into ., which is projects/ia65)
  $ svn commit

To merge your changes into head.
  $ mail -s 'Is it ok to merge projects/ia65 to head?' peter@freebsd.org
  $ wait_for_reply (the point is to have somebody on hand for the first
    time to help rescue you if things go horribly wrong.)
  (set up a clean checkout of head and projects/ia65.  MUST BE CLEAN!!)
  $ cd work
  $ svn co $BASE/head
  $ svn co $BASE/projects/ia65
  (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@12345 projects/ia65
  (resolve conflicts)
  $ svn commit projects/ia65
  (now, projects/ia65 is in sync with @12345, as is your head checkout)
  (reverse merge to base tree!)
  $ svn merge $BASE/projects/ia65 head
  (resolve conflicts)
  $ svn commit head
  (regular svn users might wonder about merge --reintegrate.  Our tree breaks
   it, sorry.  We can't use it.)

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!