Branchname policy (preliminary)

(Please note that this policy is new so many branches that currently exist don't adhere to this policy)

Where to branch from

• Private branches should be cut from the trunk where the ongoing development takes place. Branching from other branches, especially the RELEASE branches, is not advised.

How branch names should look like

• Private branch names should be lower case. Use '_' to replace a '.' in version numbers, otherwise use '-' as separator. If you have to create a branch from anything besides HEAD, prepend the name of that branch. Upper case branch names are reserved for official branches and are usually only created by release managers.

What should be done when creating a new branch

• Before creating a branch you should create a base tag with the tag name <your_branch_name>-base on the branch you want create a new branch on. If you don't have this branch checked out already:

        cvs -d:ext:freedesktop.org:/cvs/xorg checkout -r <base_branch> xc

• Note: If base_branch is HEAD, you may omit the -r <base_branch>. Then do:

        cd xc
        cvs tag <your_branch_name>-base

• Then create your branch:

        cvs tag -b <your_branch_name>

• Don't forget to update to your newly created branch.

        cvs update -r <your_branch_name>

Merging in new versions from the mother branch

• When you want to merge in changes from the base branch you need to create a temporary merge tag on the base branch:

        cvs tag -r <base_branch> <your_branch_name>-merge-1

• then do the merge:

        cvs update -j <prev_merge> -j <your_branch_name>-merge-1

• <prev_merge> is the tag from your previous merge (see below). If you haven't merged yet it would be: <your_branch_name>-base, otherwise it would be <your_branch_name>-merge. Now you have to delete your old merge tag, if it exists:

        cvs tag -d <your_branch_name>-merge

• move it to the new merge point:

        cvs tag -r <your_branch_name>-merge-1 <your_branch_name>-merge

• and delete the temporary tag:

        cvs tag -d <your_branch_name>-merge

Merging things back

• Before merging a branch back into HEAD you must merge HEAD into your branch and test it. Please perform the steps described under 4. Once you are ready, do:

        cvs checkout -j <your_branch_name>-merge -j <your_branch_name>

• or

        cvs checkout -A -j <your_branch_name>-merge -j <your_branch_name>

• This will only work if your branch has been created from HEAD. After committing your changes you need to move the merge tag on the HEAD branch to the committed version:

        cvs rtag -d <your_branch_name>-merge
        cvs tag <your_branch_name>-merge

• Please note: Access to HEAD is restricted. If you have not been given access to HEAD please check back before merging code back into HEAD.

Closing a branch

• When you have merged changes from you branch to another branch you may want to close your branch. To do so please add a 'close' tag to the final version:

        cvs tag <your_branch_name>-close

• If you want to continue working on your branch you should tag the version you have just merged. Append the name of the branch you have merged to to the name of your branch:

        cvs tag <your_branch_name>-HEAD

Branch list

• After creating a new branch you should add an entry to the branch list on the Wiki. It should contain:

  • Branch Name:
  • Purpose: Briefly describe the purpose of your branch. If you have a description of your project elsewhere please also add a link.
  • Owner: Your name and possibly others.
  • Status: Open, Closed
  • Base: Base branch (should be head).
  • Tags: List of tags on the branch with description

-- Main.EgbertEich - 15 Apr 2004