unstick r39629

Revision 39629

Date:
2012/10/01 09:04:52
Author:
hrs
Revision Log:
- Add branch policy document.
- Open doc/{user,projects,translations}.

Approved by: doceng (implicitly)
Files:

Legend:

 
Added
 
Removed
 
Modified
  • doc-branch-policy.txt

     
    1 $FreeBSD$
    2
    3 Guidelines for doc/user, doc/projects, and doc/translations
    4 ===========================================================
    5
    6 * Overview
    7 ----------
    8
    9 The doc/user, doc/projects, and doc/translations directories are
    10 workplaces for FreeBSD documentation set.
    11
    12 - doc/user should be used for private projects which are interest to
    13 somebody else and/or ones such that the results will be merged back
    14 into doc/head.
    15
    16 Create doc/user/<loginname> by using svn mkdir and then put your
    17 contents there. Please keep in mind this is one of project's
    18 resources. Although anything useful for the project is always
    19 welcome, you might want to consider carefully if it is really worth
    20 being added or not.
    21
    22 If you plan to merge the results to doc/head, create a branch of
    23 doc/head under the directory by using svn cp.
    24
    25 - doc/projects should be used for projects such as the results will
    26 eventually be merged back into doc/head. Each project has a
    27 directory doc/projects/<projname>. Create a branch of doc/head by
    28 using svn cp with the directory name directly.
    29
    30 If the project does not need the whole part of doc/head, you can
    31 also create a branch of a set of directories under doc/head. Please
    32 note that svn merge must be done at the level of doc/head/foo
    33 directories as explained later. Do not create a branch of
    34 directories other than doc/head or doc/head/foo.
    35
    36 Before adding a new project under this directory, please consult
    37 doceng@ and get approval.
    38
    39 - doc/translations is for the same as doc/projects but the purpose is
    40 limited to translation work. Under this directory, only branches of
    41 each language-dependent directories of doc/head are allowed. Each
    42 translation team can create a branch doc/translations/<lang> from
    43 doc/head/<lang> and commit work-in-progress results into the branch
    44 and then merge them to doc/head. Contents in these branches will
    45 not be used for normal doc build. Note that some kind of original
    46 revision tracking for translated files in this branch will be
    47 provided as an optional infrastructure in the future.
    48
    49 Before adding a new language-dependent branch under this directory,
    50 please consult doceng@ first to avoid possible conflicts with other
    51 people who are already working on the translation.
    52
    53 If you have a question about how to use these directories and/or have
    54 a trouble with them, please contact doceng@.
    55
    56 * Merge instruction
    57 -------------------
    58
    59 Merge should be done carefully because Subversion records the merged
    60 revisions in a property svn:mergeinfo and this property will be
    61 propagated. More specifically, the merge target has to be chosen in
    62 the following rules to prevent the mergeinfo from being bloated and
    63 scattered all over the repository.
    64
    65 The basic rule for the merge target is "it must always be set as the
    66 third level directories or doc/head/<foo>. The <foo> is a
    67 language-dependent directory in most cases. Specific examples are as
    68 follow. All of the command line examples assume DOCBASE="/tmp/doc" and
    69 this directory contains a checked out copy by "svn co
    70 svn+ssh://svn.freebsd.org/doc".
    71
    72 1. In the case that your results are in branches under
    73 doc/projects/foo and want to merge them into doc/head, it should
    74 be done in the following way:
    75
    76 cd ${DOCBASE}/head/en_US.ISO8859-1 && \
    77 svn merge -c <revnum> ../../projects/foo/en_US.ISO8859-1/
    78 cd ${DOCBASE}/head/de_DE.ISO8859-1 && \
    79 svn merge -c <revnum> ../../projects/foo/de_DE.ISO8859-1/
    80 :
    81 :
    82
    83 Note that --reintegrate option for svn merge can also be used.
    84
    85 If you have multiple directories to be merged, please do "svn merge"
    86 multiple times for all of them and then do a single "svn commit".
    87
    88 2. In the case that merging from doc/head to doc/translations/foo
    89 or vice versa:
    90
    91 2-a) Merge the translation results from
    92 translations/de_DE.ISO8859-1 branch to doc/head:
    93
    94 cd ${DOCBASE}/translations/de_DE.ISO8859-1 && \
    95 svn merge -c <revnum> ../../head/de_DE.ISO8859-1/
    96
    97 2-b) Merge the changes in doc/head to translations/de_DE.ISO8859-1
    98 branch:
    99
    100 cd ${DOCBASE}/head/de_DE.ISO8859-1 && \
    101 svn merge -c <revnum> ../../translations/de_DE.ISO8859-1/
    102
    103 3. In the case that merging from doc/head to doc/projects/foo
    104 or vice versa:
    105
    106 3-a) Merge the project results from the projects/foo branch to
    107 doc/head (this case is the same as 1.):
    108
    109 cd ${DOCBASE}/head/en_US.ISO8859-1 && \
    110 svn merge -c <revnum> ../../projects/foo/en_US.ISO8859-1/
    111 cd ${DOCBASE}/head/de_DE.ISO8859-1 && \
    112 svn merge -c <revnum> ../../projects/foo/de_DE.ISO8859-1/
    113 :
    114 :
    115
    116 In this case, always use doc/head/<lang>, not doc/head, as the
    117 merge target.
    118
    119 3-b) Merge the changes in doc/head to the projects/foo branch:
    120
    121 cd ${DOCBASE}/projects/foo/en_US.ISO8859-1 && \
    122 svn merge -c <revnum> ../../head/en_US.ISO8859-1/
    123 cd ${DOCBASE}/projects/foo/de_DE.ISO8859-1 && \
    124 svn merge -c <revnum> ../../head/de_DE.ISO8859-1/
    125 :
    126 :
    127
    128 In this case, you can also use doc/head as the merge source to
    129 merge the multiple directories:
    130
    131 cd ${DOCBASE}/projects/foo && \
    132 svn merge -c <revnum> ../../head/
    133
    134 However, please do not use both of these merge targets for a
    135 project at the same time. This means once the project used
    136 doc/projects/foo/en_US.ISO8859-1 as the target,
    137 do not use doc/projects/foo.
    138
    139 [EOF]
  • svnadmin/conf/approvers

     
    17 17 # $FreeBSD$
    18 18 #
    19 19 #^head/ doceng
    20 ^projects/ doceng
    21 ^user/ doceng
    22 ^translations/ doceng
    20 #^projects/ doceng
    21 #^user/ doceng
    22 #^translations/ doceng
    23 23 ^release/ doceng
    24 24 ^svnadmin/ doceng
    25 25 ^svnadmin/conf/approvers doceng