Definitions

• trunk branch should always be buildable, but may not always be runnable

• branches/ do not need to always be buildable

• tags/ are production worthy releases

• tags/latest is a pointer to the most recent production worthy release

Creating a Branch

• Branches should always be placed under the /branches/ folder in the repository

• Use Subversion's branch feature to create your branch from trunk. Be certain to read the naming conventions below.

• See subversion book

When to Create a Branch

• Any clearly defined project that might touch many aspects of the codebase or make the code non-buildable for any period of time

• Generally, projects that take more than a day or two to complete should be considered for branching

Branch Naming Convention

• Branches should be named for the feature or component, not according to the developer or timeline

• Use lowercase with hyphen ( - ) for spaces, limit to alphanumeric characters (no special characters)

Updating your Branch (Merging from trunk)

Updating Your Branch The First Time

1. Bring your local copy up to date — Ideally, make sure your local copy of the branch is updated and changes committed to the branch before proceeding. You can merge trunk without committing all of your current changes to your branch, but it can be messy and error-prone, especially if you have a lot of uncommitted changes to your branch.

2. Merge from trunk to your branch — Use Subversion's merge feature to merge trunk to your branch within your working copy. The starting revision number is the revision immediately following the point at which your began your branch.

   • I think you're supposed to use the revision of your branch as "from". -DJ

3. Commit the merged changes back to your branch — VERY IMPORTANT: commit the change <u>with the comment</u> "Merging trunk into branch x rev:123 - rev:456" where "x" is the name of your branch and "123" and "456" refer to the starting and ending revision numbers that were merged.

Updating Your Branch More Than Once

Similar to the initial merging of trunk into your branch with one important exception.

1. Update your working copy of the branch — update and, if possible, commit any changes to the branch in your working copy.

2. Merge trunk starting where the last merge left off — Use Subversion's merge feature to merge trunk to your branch within your working copy from the revision of your last merge of trunk

   • The "From" and "To" url should be /trunk

   • The "To" revision should be "Head"

3. Commit the merged changes back to your branch — VERY IMPORTANT: commit the change <u>with the comment</u> "Merging trunk into branch x rev:123 - rev:456" where "x" is the name of your branch and "123" and "456" refer to the starting and ending revision numbers that were merged from trunk.

Handling Branch Conflicts

See subversion book

Closing a Branch

1. Make sure all changes are committed to your branch

2. Merge/commit all recent changes on trunk to your branch

3. Create a new working copy of trunk (/trunk) HEAD (latest version of trunk)

4. Use Subversion's Merge feature to merge changes from your branch to trunk

5. Start with the revision at which you first created the branch (or last merged the branch*to trunk – very rare)

   • End with the HEAD of your branch

   • All changes within your branch should now be merged into your working copy of trunk

6. Automatic Conflict resolution tip: (only if you've merged latest trunk to your branch) At command line: "svn resolve -R --accept theirs-full *"

7. Commit all changes in your working copy of trunk back to the trunk branch with a comment like "Merging branch x into trunk"

8. Delete your branch directory

   • This can be done using the SVN Repository Exploring perspective of Subclipse within Eclipse or the Repo-browser of TortoiseSVN (in Windows) — i.e., browse to your branch and press the delete key (or right-click and select Delete...) to delete the branch.

Merging Using Subclipse (within Eclipse)

1. Find the revision number of the last merge

2. Check out a copy of the trunk as, say, openmrs-trunk:

   1. Right click on openmrs-trunk and select "Team"-->"Merge"

   2. From:

   3. URL: http://svn.openmrs.org/openmrs/trunk

   4. Revision: Find the last merge revision number by clicking on "Show Logs". Use this number.

   5. To:

   6. Check Use "From:" URL

   7. Check Head Revision
      #...examine the diffs, compile, test, etc...

3. Find conflicts (marked in red in merge log with "C .."

4. Right click "Team"-->"Edit Conflicts"

5. Click "Two Way compare"

6. Click "Copy all Non-conflicting changes from left to right"

7. Save file

8. Right click "Team"-->"Mark Resolved"

9. Commit the merged/fixed code with a descriptive description like "Merged xxx branch changes 671:722 into the trunk."

Merging Using the SVN Command line

1. Find the revision number of the last merge:

   svn log --verbose --stop-on-copy http://svn.openmrs.org/openmrs/trunk

2. Done from the trunk directory

3. Merge trunk & branch xxx from that merge to the latest revision:

   svn merge -r 341:HEAD http://svn.openmrs.org/openmrs/branches/xxx

4. ...examine the diffs, compile, test, etc...

5. Use a descriptive commit description for future ease:

   svn commit -m "Merged branch xxx changes rev:671 - rev:722 into the trunk."