Revision 39629 (by hrs, 2012/10/01 09:04:52) - Add branch policy document.
- Open doc/{user,projects,translations}.

Approved by: doceng (implicitly)
$FreeBSD: doc-branch-policy.txt 39629 2012-10-01 09:04:52Z hrs $

Guidelines for doc/user, doc/projects, and doc/translations

* Overview

The doc/user, doc/projects, and doc/translations directories are
workplaces for FreeBSD documentation set.

- doc/user should be used for private projects which are interest to
  somebody else and/or ones such that the results will be merged back
  into doc/head.

  Create doc/user/<loginname> by using svn mkdir and then put your
  contents there.  Please keep in mind this is one of project's
  resources.  Although anything useful for the project is always
  welcome, you might want to consider carefully if it is really worth
  being added or not.

  If you plan to merge the results to doc/head, create a branch of
  doc/head under the directory by using svn cp.

- doc/projects should be used for projects such as the results will
  eventually be merged back into doc/head.  Each project has a
  directory doc/projects/<projname>.  Create a branch of doc/head by
  using svn cp with the directory name directly.

  If the project does not need the whole part of doc/head, you can
  also create a branch of a set of directories under doc/head.  Please
  note that svn merge must be done at the level of doc/head/foo
  directories as explained later.  Do not create a branch of
  directories other than doc/head or doc/head/foo.

  Before adding a new project under this directory, please consult
  doceng@ and get approval.

- doc/translations is for the same as doc/projects but the purpose is
  limited to translation work.  Under this directory, only branches of
  each language-dependent directories of doc/head are allowed.  Each
  translation team can create a branch doc/translations/<lang> from
  doc/head/<lang> and commit work-in-progress results into the branch
  and then merge them to doc/head.  Contents in these branches will
  not be used for normal doc build.  Note that some kind of original
  revision tracking for translated files in this branch will be
  provided as an optional infrastructure in the future.

  Before adding a new language-dependent branch under this directory,
  please consult doceng@ first to avoid possible conflicts with other
  people who are already working on the translation.

If you have a question about how to use these directories and/or have
a trouble with them, please contact doceng@.

* Merge instruction

Merge should be done carefully because Subversion records the merged
revisions in a property svn:mergeinfo and this property will be
propagated.  More specifically, the merge target has to be chosen in
the following rules to prevent the mergeinfo from being bloated and
scattered all over the repository.

The basic rule for the merge target is "it must always be set as the
third level directories or doc/head/<foo>.  The <foo> is a
language-dependent directory in most cases.  Specific examples are as
follow.  All of the command line examples assume DOCBASE="/tmp/doc" and
this directory contains a checked out copy by "svn co

 1. In the case that your results are in branches under
    doc/projects/foo and want to merge them into doc/head, it should
    be done in the following way:

    cd ${DOCBASE}/head/en_US.ISO8859-1 && \
        svn merge -c <revnum> ../../projects/foo/en_US.ISO8859-1/
    cd ${DOCBASE}/head/de_DE.ISO8859-1 && \
        svn merge -c <revnum> ../../projects/foo/de_DE.ISO8859-1/

    Note that --reintegrate option for svn merge can also be used.

    If you have multiple directories to be merged, please do "svn merge"
    multiple times for all of them and then do a single "svn commit".

 2. In the case that merging from doc/head to doc/translations/foo
    or vice versa:

    2-a) Merge the translation results from
         translations/de_DE.ISO8859-1 branch to doc/head:

        cd ${DOCBASE}/translations/de_DE.ISO8859-1 && \
            svn merge -c <revnum> ../../head/de_DE.ISO8859-1/

    2-b) Merge the changes in doc/head to translations/de_DE.ISO8859-1

        cd ${DOCBASE}/head/de_DE.ISO8859-1 && \
            svn merge -c <revnum> ../../translations/de_DE.ISO8859-1/

 3. In the case that merging from doc/head to doc/projects/foo
    or vice versa:

    3-a) Merge the project results from the projects/foo branch to
         doc/head (this case is the same as 1.):

        cd ${DOCBASE}/head/en_US.ISO8859-1 && \
            svn merge -c <revnum> ../../projects/foo/en_US.ISO8859-1/
        cd ${DOCBASE}/head/de_DE.ISO8859-1 && \
            svn merge -c <revnum> ../../projects/foo/de_DE.ISO8859-1/

        In this case, always use doc/head/<lang>, not doc/head, as the
        merge target.

    3-b) Merge the changes in doc/head to the projects/foo branch:

        cd ${DOCBASE}/projects/foo/en_US.ISO8859-1 && \
            svn merge -c <revnum> ../../head/en_US.ISO8859-1/
        cd ${DOCBASE}/projects/foo/de_DE.ISO8859-1 && \
            svn merge -c <revnum> ../../head/de_DE.ISO8859-1/

        In this case, you can also use doc/head as the merge source to
	merge the multiple directories:

        cd ${DOCBASE}/projects/foo && \
            svn merge -c <revnum> ../../head/

        However, please do not use both of these merge targets for a
        project at the same time.  This means once the project used
        doc/projects/foo/en_US.ISO8859-1 as the target,
        do not use doc/projects/foo.