Managing Branches in GitHub

NOTE: This page is an early draft. Pay it no attention until this notice is removed.

Introduction

Following the release of perfSONAR 4.1, the development team adopted a more-formal scheme for version control during development. There are central tenets:

• Any change is to be developed along a branch named after the release for which it is intended.
• Once the code on the branch is ready to be released, the branch is closed and the release is done.
• Changes made in the branch are merged into branches for later releases.

Repository Preparation

After a repository has been cloned, the standard perfSONAR Git hooks can be used to do client-side enforcement of branch closures. Installing the hooks is optional but strongly recommended.

Making a Change

1. Select the release for which the change is targeted. This will depend on the nature of the change. For example, a new major feature not present in version 9.0 would be targeted for 9.1.

2. Open an issue to cover the change and set the release to correspond with the one selected above. Note the number of the new issue. 9999 will be used as an example.

3. Check out the 9.1 branch.

4. Create a new branch from 9.1 called issue-9999.

5. Check out the issue-9999 branch.

6. Develop, commit and push changes.

7. Submit a pull request to merge issue-9999 into 9.1. Once the change is pulled, the issue-9999 branch will be deleted.

Release Procedures

Lock the Release Branch

Once a branch is considered ready for release, it is closed to further changes. Enforcement of this closure happens at two levels: in the local repository using a hook within the Git repository (which can be bypassed) and administratively within GitHub (which cannot).

Closing the Branch in Git

(Note that this process will, at some point, be automated.)

1. Make sure the repository has been prepared as described above.
2. Change into the root directory of the repository.
3. touch BRANCH-CLOSED
4. git add BRANCH-CLOSED
5. git commit -a -m "Closing branch for release."
6. git push

Closing the Branch in GitHub

1. Log into GitHub using an administrator account.
2. Go to the repository that is to be closed.
3. Select the Settings tab.
4. Select Branches in the left-side pane.
5. Click Add Rule.
6. Apply the rule to the name of the branch being closed (e.g., 9.1). Note that wildcards are possible, so the number of rules can be kept down by using them. (E.g., if all of the 9.x releases are closed, a single 9* rule would cover all of them.)
7. Select Include administrators.
8. Select Restrict who can push to matching branches. Put only the release administrator, arlake228 on the list.
9. Click Add. Note that the change may take a few minutes to take effect.

Create Branches for Future Development

TODO: Flesh this out.

• 9.0 (Paradigm Shift release)

  • Close the 9.0 branch (see above)
  • Create 9.0.0.1 (Fast-Track Patch)
  • Create 9.0.1 (Bug Fix / Minor Enhancement)
  • Create 9.1 (Major Feature)
  • Create 10 (Paradigm Shift)
  • Pull 9.0 into master and tag it release-9.0

• 9.0.0.1 (Fast-Track Patch)

  • Lock the 9.0.0.1 branch (see above)
  • Create 9.0.0.2 (Fast-Track Patch)
  • Pull 9.0.0.1 into master and tag it release-9.0.0.1

• 9.0.1 (Bug Fix / Minor Enhancement)

  • Create 9.0.1.1 (Fast-Track Patch)
  • Pull 9.0.1 into master and tag it release-9.0.1