# Copyright (C) 2008-2009, Parrot Foundation.
# $Id: branching_guide.pod 42784 2009-11-22 04:26:22Z jkeenan $

=head1 NAME

docs/project/branching_guide.pod - Branching Instructions

=head1 DESCRIPTION

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.

=head2 Creating a Branch

=head3 SVN

To create a branch, use the C<svn copy> command.

  $ svn copy https://svn.parrot.org/parrot/trunk \
         https://svn.parrot.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.parrot.org/parrot/branches/<yourbranchname>

=head2 Maintaining a Branch

=head3 SVN

If your branch touches many source code files or is expected to be long-lived,
you may wish to consider synchronizing your branch with changes in trunk on a
regular basis (at least weekly, more often for heavy changes). 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 C<svn update>).

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

Use the C<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 C<-r>
option, pass it the revision number of the last synchronization, and then
C<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.parrot.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 C<svn revert> your
whole checkout using the C<--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

=head2 Preparing to Merge a Branch

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

=over

=item 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.

=item 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 I<all> the tests for their
language or tool if they have some unusual testing configuration).

=item 3

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

=back


=head2 Merging a Branch

=head3 SVN

When you're ready to merge your changes back into trunk, use the C<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 C<-r> option pass the revision number where the branch was created, and
C<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.parrot.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 C<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
C<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.parrot.org/parrot/branches/<yourbranchname> \
          -m "Removed <describe branch> from the repository."

=head2 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 announcement that you weren't able to
test that piece fully.

=cut

__END__
Local Variables:
  fill-column:78
End:
