/ 
parrot-0.9.1
/ project::branching_guide

Branching Instructions

To minimize the disruption of feature development on language and tool developers, all major changes to Parrot core take place in a branch. Ideally, branches are short-lived, and contain the smallest set of changes possible. With good maintenance, though, even long-lived branches can be merged smoothly.

The instructions in this guide are written for Subversion. Please contribute patches for other revision control systems.

Creating a Branch

SVN

To create a branch, use the svn copy command.

$ svn copy https://svn.perl.org/parrot/trunk \
       https://svn.perl.org/parrot/branches/<yourbranchname> \
       -m "Created branch for <purpose of branch>."

Record the revision number of the branch (in a text file or otherwise), you will need it later for branch synchronization and for merging your branch back into trunk:

initial revision: r30235

Check out your branch for working:

$ svn co https://svn.perl.org/parrot/branches/<yourbranchname>

Maintaining a Branch

SVN

On a regular basis (at least weekly, more often for heavy changes), synchronize your branch with the changes in trunk. For this you will need the revision number of your most recent synchronization (or the revision number of the initial branch creation if this is the first synchronization), and the current highest revision in trunk (you can get this by running svn update).

Make sure you don't have any outstanding changes in your working copy (use svn status).

Use the svn merge command from the root directory of your branch checkout to add all changes from trunk to your working copy of the branch. In the -r option, pass it the revision number of the last synchronization, and then HEAD (a short-cut for the current highest revision), which tells it to grab all changes committed between those two revision numbers.

$ svn merge -r30235:HEAD https://svn.perl.org/parrot/trunk/

Check for conflicts in the merged code:

$ svn status -q | grep "^C" | less

Manually edit any conflicting files to remove the conflict markers. It may be helpful to look at the svn log for a particular file in branch and trunk to decide which code to keep, or how to integrate the changes from branch and trunk. When you've resolved all conflicts, mark the file as resolved with:

$ svn resolved <filename>

(In the case of a completely disastrous merge, you can svn revert your whole checkout using the --recursive option and start over.)

Commit the merged code.

$ svn commit

Use a meaningful commit message, something like:

[<yourbranchname>] Brought the <yourbranchname> branch up-to-date
with trunk r30371.

Record the revision number of the trunk version you synchronized to, for later synchronization:

new revision: r30371

Preparing to Merge a Branch

Post to parrot-dev@lists.parrot.org letting people know that you're about to merge a branch.

  1. Ask people to submit test results for their language, tool, or platform. If you don't hear back from people, it doesn't mean they ran the tests and found no problems, it means they didn't bother testing the branch. If you need feedback on a particular language or platform, follow up with the person responsible until you hear an explicit "Yes, it's working" answer.

  2. Let people know what tests you ran, so they can determine if you didn't run the tests for their language or tool (or, didn't run all the tests for their language or tool if they have some unusual testing configuration).

  3. Mention any significant feature changes in the branch that you particularly want tested.

Merging a Branch

SVN

When you're ready to merge your changes back into trunk, use the svn merge command again. This time run it in the root directory of a checkout of trunk. (Make sure you don't have any outstanding trunk changes in your working copy.) In the -r option pass the revision number where the branch was created, and HEAD to tell it to grab all changes committed in the branch from the time you created the branch to the most recent change.

svn merge -r30235:HEAD https://svn.perl.org/parrot/branches/<yourbranchname>/

(If you didn't keep the revision number when you created the branch, you can find it by clever detective work in svn log. It's easier just to keep it in a text file.)

Check for conflicts as in branch synchronization, then commit your changes with svn commit. Use a meaningful commit message something like:

[<yourbranchname>] Merged the <yourbranchname> branch into trunk for
r30235 to r31667.

Delete your branch from the repository:

svn delete https://svn.perl.org/parrot/branches/<yourbranchname> \
        -m "Removed <describe branch> from the repository."

Announcing a Merge

Send a message to parrot-dev@lists.parrot.org letting people know that your branch has been merged. Include a detailed list of changes made in the branch (you may want to keep this list as you work). Particularly note any added, removed, or changed opcodes, changes to PIR syntax or conventions, and changes in the C interface.

If there was a specific language, tool, or platform that you wanted tested before merging but couldn't get any response from the responsible person, you may want to include some warning in the annoucement that you weren't able to test that piece fully.