Difference between revisions of "Git Branch Management"

Revision as of 21:26, 17 June 2011

Net-SNMP has a number of scripts or shell functions which help manage a git-repo. Specifically, we have a bunch of tools that help test patches, apply patches and perform upward merges based on our Git Workflow.

Getting Started

The bash aliases require that you source the local/gittools/shell-functions in order to get started:

 # . ./local/gittools/shell-functions

Once this is done, the rest of the commands on this page will work.

Patch Management

Our Git Workflow states that patches should be applied to the lowest branch possible. IE, if you have a bug fix for nearly every version it should be applied to the lowest current supported version branch. EG, V5-4-patches. But which branch will it apply against cleanly?? How do I do this quickly? We have an answer for you:

Note: all these routines require a clean source tree to start, and will warn you if you have modified files in the tree

nspatchtry

The nspatchtest command can be used to apply a patch to each (currently supported) branch in the tree to see which it will successfully apply to. This is much faster than figuring this out by hand. It takes patch arguments to apply the patch with. The -i switch is required to specify where the patch file is located.

 # nspatchtry -p 1 -i /tmp/thepatch
 ::: Net-SNMP: checking out and applying patch in V5-4-patches
 Switched to branch 'V5-4-patches'
 Your branch is ahead of 'origin/V5-4-patches' by 5 commits.
 ::: Net-SNMP: Appling patch
 patching file net-snmp/README.snmpv3
 ::: Net-SNMP: Patch succeeded on V5-4-patches
 ::: Net-SNMP: cleaning source tree
 ::: Net-SNMP: checking out and applying patch in V5-5-patches
 Switched to branch 'V5-5-patches'
 Your branch is ahead of 'origin/V5-5-patches' by 12824 commits.
 ::: Net-SNMP: Appling patch
 patching file net-snmp/README.snmpv3
 ::: Net-SNMP: Patch succeeded on V5-5-patches
 ::: Net-SNMP: cleaning source tree
 ::: Net-SNMP: checking out and applying patch in V5-6-patches
 Switched to branch 'V5-6-patches'
 Your branch is ahead of 'origin/V5-6-patches' by 25983 commits.
 ::: Net-SNMP: Appling patch
 patching file net-snmp/README.snmpv3
 ::: Net-SNMP: Patch succeeded on V5-6-patches
 ::: Net-SNMP: cleaning source tree
 ::: Net-SNMP: checking out and applying patch in master
 Switched to branch 'master'
 Your branch is ahead of 'origin/master' by 14786 commits.
 ::: Net-SNMP: Appling patch
 patching file net-snmp/README.snmpv3
 ::: Net-SNMP: Patch succeeded on master
 ::: Net-SNMP: cleaning source tree
 
 Patch application results:
   Success:  V5-4-patches V5-5-patches V5-6-patches master
      Fail: 

Note the important ending: my patch succeeded against all those branches.

nspatchapply

Now that we know where the patch should be applied, actually applying it is very simple. Simply call the nspatchapply script, which:

1. checks out the earliest branch that worked with nspatchtry
2. applies the patch
3. runs git diff so you can make sure it looks ok
4. asks you if it looks ok and if so:
5. runs git commit on the results, with any arguments you pass it, to commit the results.

 # nspatchapply -m "applying the wonderful patch.  Isn't it pretty?"
 ::: Net-SNMP: Checking out V5-4-patches
 Switched to branch 'V5-4-patches'
 Your branch is ahead of 'origin/V5-4-patches' by 5 commits.
 ::: Net-SNMP: applying the patch -p 1 -i /tmp/thepatch
 patching file net-snmp/README.snmpv3
 diff --git a/net-snmp/README.snmpv3 b/net-snmp/README.snmpv3
 index 263c955..8294035 100644
 --- a/net-snmp/README.snmpv3
 +++ b/net-snmp/README.snmpv3
 @@ -1,4 +1,4 @@
 -README.snmpv3
 +README.snmpv3foo
  -------------
  How to setup SNMPv3, a very brief document for Dave to elaborate and
  do a better job on since I suck at writing documentation and he
 
 commit the results to V5-4-patches? [y/n] y
 [V5-4-patches 102bde5] applying the wonderful patch.  Isn't it pretty?
  1 files changed, 1 insertions(+), 1 deletions(-)

Done! Wasn't that easy?

Git Repository Management

Once you have bug-fix patches sprinkled about the various trees, how in the world do you get them all up into the trunk where you want to do your new spiffy feature development in a bug-free environment?

nsrollup

The nsrollup bash function performs the following tasks on a clean tree:

1. performs a git pull --all to ensure your branches are up to date
2. checks out each branch
3. merges the direct previous version into it (eg, it'll roll V5-4-patches into V5-5-patches)
4. lets you know about conflicts that you need to resolve

Stopping Merging During Release-Candidates

Our development policy says that during the release candidate series, all patches must be voted on in the -coders list. Thus, it's not appropriate for these to be automatically rolled upward, as that's the job of the release engineer for that release to do. Thus, if a dist/release file exists and it contains a branch name followed by a magical 'rc' keyword, this branch will be excluded from the merging. EG:

 V5-6-patches rc

Will cause it to be ignored for merging. Changes in V5-6-patches will still be rolled into V5-7-patches, though (which will often include changes to the dist/release file itself; but that's ok. It can list multiple releases if need be).

Building and Testing