Latest revision as of 15:38, 30 January 2019

Branches

StarlingX branching policy is largely derived from OpenStack policy with some changes to accommodate different development cycle and release priorities.

Stable/Release Branches

Feature Branches

Feature branches are used to develop and coordinate large numbers of changes. They should be used with care as they can also be a source of long-term debt and divergence.

Feature branches are named with the prefix 'f/' followed by a descriptive name.

Branch Updates

Feature branches should regularly be re-sync'ed with the master branch rather than wait until the feature work is done. Resolution of conflicts occurs on the feature branch side and generally falls to the developers working on the feature branch.

Merging new updates from master into the feature branch can only be performed by members of the starlingx-release group in Gerrit. The process follows the OpenStack Driver's Guide.

First look at how the two branches have diverged to get an idea of the differences and look for potential conflicts:

feature_branch=<branch-name>
git remote update
git checkout master
git pull --ff-only origin master
git checkout $feature_branch
git pull --ff-only origin $feature_branch
git log --oneline --no-merges --cherry-mark --left-right --graph master...HEAD

Merge master into feature branch:

git remote update
git checkout master
git pull --ff-only origin master
git checkout $feature_branch
git pull --ff-only origin $feature_branch
git merge origin/master
# Resolve merge conflicts (git add ...; git commit)

# Avoid changing to these files
git checkout origin/master -- .gitreview

# Amend the merge commit to automatically add a Change-ID to the commit message
GIT_EDITOR=true git commit --amend
git review -R $feature_branch

The resulting review will contain the resolution of any merge conflicts that are resolved in this process, meaning that the review will only be a merge commit without any files listed if there are no conflicts.

Tools

branch-stx.sh

This shell script is found in stx-tools/release/branch-stx.sh and performs the grunt work of branching the set of StarlingX repositories both in Gerrit and the staging repos in Github. It can pull the repo list from a manifest file or accept repo URLs on the command line. It is used for creating milestone, release and feature branches.

• The default action is to create a milestone branch with prefix 'm/'.
• To create a release branch set BRANCH directly using a 'r/' prefix.

 BRANCH=r/2018.05 branch-stx.sh <repo-url>

• To create a feature branch set BRANCH directly using a 'f/' prefix and set TAG="" to skip tagging the branch point:

 BRANCH=f/centos75 TAG="" branch-stx.sh <repo-url>

 branch-stx.sh [--dry-run|-n] [-l] [-m <manifest>] [<repo-url> ...]
 
 --dry-run|-n      Do all work except pushing back to the remote repo.
                   Useful to validate everything locally before pushing.
 
 -l                List the repo URLS that would be processed and exit
 
 -m <manifest>     Extract the repo list from <manifest> for starlingx
                   and stx-staging remotes
 
 <repo-url>        Specify one or more direct repo URLs to branch (ie git remote)
                   These are appended to the list of repos extracted from the
                   manifest if one is specified.

For each repo:

• create a new branch $BRANCH
• tag the new branch with an initial release identifier if $TAG is set
• update the .gitreview file to default to the new branch (Gerrit repos only)

Environment variables are available for modifying this script's behaviour:

SERIES is the base of the branch and tag names, similar to how it is used in OpenStack branch names. StarlingX formats SERIES based on year and month as YYYY.MM although that is only a convention, no tooling assumes that format.

BRANCH is the actual branch name, derived by adding 'm/' (for milestones) or 'r/' (for periodic releases) to SERIES.

TAG is the release tag that represents the actual release. If TAG is unset no tag is created.

References

OpenStack Documentation

• Feature Branches