StarlingX/Branches

= Branches =

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

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 |Project 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= 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
 * 1) Resolve merge conflicts (git add ...; git commit)

git checkout origin/master -- .gitreview
 * 1) Avoid changing to these files

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

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.

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.

BRANCH=r/2018.05 branch-stx.sh  BRANCH=f/centos75 TAG="" branch-stx.sh 
 * The default action is to create a milestone branch with prefix 'm/'.
 * To create a release branch set BRANCH directly using a 'r/' prefix.
 * To create a feature branch set BRANCH directly using a 'f/' prefix and set TAG="" to skip tagging the branch point:

branch-stx.sh [--dry-run|-n] [-l] [-m ] [ ...] --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    Extract the repo list from for starlingx and stx-staging remotes        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:

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.

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

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