Branch Manager Guidelines

Getting started

Ensure you have a clean 2.5.x source code checkout with no local modifications.

svn co https://source.sakaiproject.org/svn/sakai/branches/sakai_2-5-x/ 2.5.x

Review the 2.5.x Fixes to merge filters in JIRA (http://jira.sakaiproject.org/jira) (there are both verified and unverified filters). Verified should be ok to merge but check the comments for evidence that there actually was testing and for and any possible issues/dependencies. Unverified will need some more testing before they are considered safe to merge.

When you have a fix you want to merge

It is recommended that you test the broken behaviour on an UNPATCHED version of 2.5.x, ie without the fixes in place so you can first see what is considered 'broken', then go ahead and patch the local copy and rebuild to see if the fix can be verified.

Using Patch Files

If a patch has been attached for the fix then download that and patch your local 2.5.x. you'll need to take a look in the patch file to find the 'root' directory for that file: the directory (relative to the source directories) in which the patch was made. A typical locations would be inside a 'project' or 'module', one directory deeper than the main source code directory (e.g., SAKAI-SRC/project rather than SAKAI_SRC/project/some/other/directory). There are many examples of some pretty horrible patches, including those generated from odd locations including user's local home directories. The patch will not work correctly of the files to be patched cannot be found. The lines in the batch file that begin with 'Index: ' end with the relative paths to the files that the patch program will expect to find.

To patch a directory tree from a local patch file:

patch -p0 --dry-run -i /path/to/patch/file

Or, (one way of) using file redirecting to the 'patch' stdin:

patch -p0 --dry-run < /path/to/patch/file

The --dry-run flag will just test the process without making changes. If you get lots of HUNK failed errors, you'll need to manually resolve them. If there are too many or it all fails, you should contact the project developers for assistance.

After any conflicts are resolved, patch without the --dry-run flag to apply the changes from the patch ito your svn sandbox.

Then build and deploy and test.

Using the 'svn merge' command

Using the 'svn merge' command is very similar to using 'patch' above. You will need to know the commit revisions associated with the fix. The best way to find them is to look in JIRA (http://jira.sakaiproject.org/jira). If the developer correctly references the JIRA Key (like SAK-2332) in the commit comments, then the commit comments and affected files will show up in jira under the 'subversion commits' tab.

You'll need to identify all revision numbers for the relevant commits against trunk and also verify that there are later comments indicating that there has been related testing completed with positive results.

It is good to verify the svn logs for the commits from the command line or other svn tool since JIRA only re-indexes svn comments (logs) after the server restarts and the svn:log revision property may have been updated.

Example: merge commit 23423 for portal (fictitious)

cd $SAKAI_SRC_ROOT
cd portal
svn update
svn merge -c --dry-run 23423 https://source.sakairoject.org/svn/ucd-sakai/portal/trunk .

Note the period ('.') at the end of the merge command, and the use of the '--dry-run' directive similar to the 'patch' command.

If there are not conflicts (lines that begin with the letter 'C', the analogue to the 'patch' command 'HUNK failures'), then you can apply the merge by omitting the '--dry-run' directive, compile, deploy and test.

Comitting

If its all fixed and no other bugs are introduced that are immediately apparent, you can commit the changes in your local sandbox to the branch.

If you added new file(s), you'll need to add them to version control:

svn add /path/to/the/new/file

If you are all set, commit it with a message that includes the JIRA ticket ID:

svn commit -m "SAK-12345 fix for internationalisation in project X properties"

This will output something like:

Sending        tool/src/java/org/sakaiproject/people/tool/pages/Faces.html
Sending        tool/src/java/org/sakaiproject/people/tool/pages/Faces.java
Transmitting file data ..
Committed revision 53998.

You then need to post a comment into the JIRA with the revision number (thats the 53998 in the example above) that you committed it as.

Your first commit

If it's your first time committing you may need the username attribute and you'll be prompted for your password which Chris Maurer/another svn-admin might have given you. Just append --username your_username_here and you'll be prompted for your password. You should only need to do this once, it should remember your password. This can be changed in your svn config if you want though.

If you entered the wrong commit message

If you entered the wrong commit message, you can alter it by editing the property called 'svn:log' by doing this:

svn propedit svn:log --revprop -r12345

where 12345 is the revision number that you get back from the commit. This will launch a text editor where you can enter your new message. On saving/exiting its sent. The actual text editor that's launched is defined in the environment variable $EDITOR. You can override this variable in your profile
if you want to use a different editor.

Of course you could also use an SVN GUI client if you wish which hides all of this commandline stuff! I prefer the commandline so I have a bit more control over it all.

No patch supplied? Roll your own!

If there is no patch attached to the JIRA issue you'll need to check the SVN commits. Sometimes there are lots of commits to different places which is a real pain. In these cases I ask the person who fixed it to generate a patch for me because we are branch managers not maintainers. If there are just one or so you can generate your own patch by doing this:

svn diff -r REV0:REV1 https://source.sakaiproject.org/svn/project/trunk/some/other/directory

This is equivalent to

svn diff -c REV1 https://source.sakaiproject.org/svn/project/trunk/some/other/directory

where REV0 is the revision number PRIOR to the fixes being made in trunk and REV1 is the revision of the fix:
e.g.

svn diff -r 49150:49151 https://source.sakaiproject.org/svn/blog/trunk/

You can also output that by appending > ~/path/to/output/file after the above command which will make a patch file for you.
e.g.

svn diff -r 49150:49151 https://source.sakaiproject.org/svn/blog/trunk/ > ~/path/to/output/file

Here's that last example using the shorthand '-c' method:

svn diff -c 49151 https://source.sakaiproject.org/svn/blog/trunk/ > ~/path/to/output/file

Then you can apply the patch in the same manner above.

If in doubt

Since there are a number of people that can edit issues in Jira, occasionally issues creep into the filters that are new features or change the Sakai API or do other things that are not appropriate to be merged to a branch. Only bugfixes should be merged back into the branch. If in doubt just post a message to the 2.5.x@collab.sakaiproject.org list and we'll check it out and see if it should be merged.