Backporting

In the GRASS GIS project, we provide the latest stable release branch with bugfixes from trunk (development branch) as much as possible.

Procedure

Two little helper scripts to make merging between branches easier:

• grass-addons/tools/svn64merge​ (kept for rare backports to GRASS GIS 6)
• grass-addons/tools/svn-merge.sh​ (recommended for any GRASS GIS 7 release branch)

To use them, first make sure all branches are up to date (svn up) and clean (svn diff), then cd into the top of the source tree you want to pull in to. If you try to run it from the module's own subdir it will fail. Then run the script named for the branch you want to pull from, followed by the revision number of the change you wish to merge (no leading "r" or [square brackets] around the rev number please). Mind that you might want to run 'svn propdel svn:mergeinfo .' before doing an untargeted 'svn commit'.

Example:

 # make the original edit in trunk
 cd trunk
 svn diff lib/gis/parser.c
 svn up lib/gis/parser.c
 vim lib/gis/parser.c
 svn diff lib/gis/parser.c
 # .. run make; test the change ..
 svn commit -m"libgis: fix of XYZW in parser" lib/gis/parser.c
 # --> note the rev number of this commit for an immediate or future backport


 # backport fix to the appropriate release branch (e.g. GRASS GIS 7.2.x)
 cd /path/to/grass72_release/
 svn diff lib/gis/parser.c
 svn up lib/gis/parser.c
 /path/to/grass-addons/tools/svn-merge.sh 12345   # using the rev number from above
 svn diff lib/gis/parser.c
 # .. run make; test the change ..
 svn commit -m"libgis: fix of XYZW in parser (trunk, r12345)" lib/gis/parser.c

Comparing branches

A diff tool like Kompare, Kdiff3, or Meld can help. These run the standard UNIX "diff -u" utility and show the results in an easy to navigate GUI.

You'll want to tell them to ignore the build files, svn paperwork files, compiled binaries, and "Last changed" timestamps on the help pages. This is typically done by going into the options and telling it to ignore a list of wildcard'ed path names, and regex filter for the document content.

For example, to compare trunk and relbr70 using kdiff3: (I used the QT version of Kdiff3, the other tools are similar)

  cd grass/svn/
  svn checkout https://svn.osgeo.org/grass/grass/branches/releasebranch_7_0 relbr70
  svn checkout https://svn.osgeo.org/grass/grass/trunk trunk

  kdiff3 relbr70/ trunk/

• This will take a little while to scan the two directory trees
• Once loaded, go to Settings -> Configure KDiff3...
• Go into the Directory tab
  • To "File-anti-pattern(s):" add ";*.tmp.html"
  • To "Dir-anti-pattern(s):" add ";OBJ.x86*;dist.x86*;bin.x86*" (".svn" was already there)
    • (if not working with translations today you might add ";locale" to that too)
  • In "File Comparison Mode" select "Full analysis"
• Go to the Diff tab
  • In the "Line-matching preprocessor command:" line add:

    grep -v "Last changed: $Date: 2"
    

    • (this will ignore the $Date:$ svn keywords at the end of the help pages)
• Click "Ok" to go back to the main GUI window, and press Shift-F5 to rescan with the new filters.

You can now double click on a filename to review changes.

Policies

Q: Should developers do it themselves? Or ask another dev to do it to keep some review sanity?

A: It depends: preferably a developer should be able to backport him/herself but

• do not break the release branch :o)
  • i.e. don't leave it in a broken state for days while you are working on something, we must be ready for an emergency release at any time.
• make your commits to the dev branch first
  • do testing and bug fixes in a safe place, then backport finished code in an "atomic commit" to the release branch. Others may do the backport, and they'll assume that the dev branch is the most recent version to use.
• make tests
• only fix bugs, do not introduce new features
• only do refactoring in trunk
  • large and complicated changes can introduce new hard to spot bugs, the idea of the stable branch is to asymptote to zero bugs.

If the above is unclear, it should be discussed on the developers list. If in doubt, ask! In this case, a path/diff is appreciated.

For general advice, see ​http://svnbook.red-bean.com/en/1.4/svn.branchmerge.copychanges.html