Git flow

Branching model is inspired by Git branching model by Vincent Driessen, but a simplified version.

Vincent recommends having two branches develop and master, we don’t use develop, we use only master.

List of flow steps:

  1. Create a feature branch from master.

  2. Merge feature branches to master.

  3. Create a release branch, for example 0.2.

  4. Release a release candidate version, for example 0.2rc1.

  5. Release a new release candidate version if previous version had bugs, for example 0.2.rc2.

  6. Release a new version, from latest release candidate, for example 0.2.

  7. Create a bug fix branch from a release branch, for example 42-fix-bug.

  8. Merge a bug fix branch back to release and master branches.

  9. Release an new bug fix version, for example 0.2.1.

List of version numbers:

  • {major} - only used for major, possibly backwards incompatible changes.

  • {major}.{minor} - used for minor, mostly backwards compatible changes.

  • {major}.{minor}rc{number} - used as a pre-release, before releasing {major}.{minor} version.

  • {major}.{minor}.{patch} - a bug fix release, no new features, only bug fixes.

Long lived branches:

  • master - main development branch, with all the newest code.

  • {major}.{minor} - release branches use for bug fixes.

Long lived tags:

  • {major}.{minor}rc{number} - release candidates.

  • {major}.{minor}.{patch} - bug fix releases.

Short lived branches:

  • {number}-{slug} - feature branches, starting with issue number and a slug that is machine and human readable title of what this branch is about, usually this matches issue title, for example 634-mermaid-diagrams, 652-add-geometry-type. Use only ascii letters, separate words with hyphens.

Feature branches

May branch off from:
master
Must merge back into:
master
Branch naming convention:
{number}-{slug}

Feature branches must be associated with an issue and must start with an issue number. One issue, might have multiple feature branches.

For each feature branch a GitHub Pull request must be created and linked to issue.

Feature branches must be deleted after merge.

Creating a feature branch

You can create feature branch using GitHub Web UI, or command line:

git checkout -b {number}-{slug} master

Merging a feature branch

You can merge feature branch using GitHub Web UI, or command line:

git checkout master
git merge --no-ff {number}-{slug}
git branch -d {number}-{slug}
git push origin master

This will merge feature branch to master, deletes feature branch and pushes changes to GitHub.

Release branches

May branch off from:
master
Must merge back into:
master
Branch naming convention:
{major}.{minor}

Release branches are used for adding bug fixes to specific version, also for release candidates for new release preparations.

At some point in time a new release branch might be created from master, to freeze development and prepare new version for release.

Release branches can only be used for fixing bugs, new features must be added to master.

Creating a release branch

New releases must always be release as release candidates using {major}.{minor}rc{number} version number. But in CHANGES.rst we do not show pre-release versions.

You can create release branch using GitHub Web UI, or command line:

git checkout -b {major}-{minor} master

After that you need to prepare Spinta for a release candidate:

ed pyproject.toml <<EOF
/^version = /c
version = "{major}.{minor}rc{number}"
.
wq
EOF
ed CHANGES.rst <<EOF
/^###/a

{major}.{minor} (unreleased)
===================

.
wq
EOF
head CHANGES.rst
git diff
git commit -a -m "Prepare for the next {major}.{minor} release"
git push origin {major}-{minor}
git log -n3

You can release multiple release candidates until enough testing is done, and new version is considered stable and ready for publishing.

Release branches are never deleted.

Releasing a new version

Follow notes/spinta/release.sh notes for releasing new versions.

When a new version is released it must be tagged with version number, in order to mark a point in code history, that was released under a version number.

Tags are not branches, and the are used as markers, they can’t receive new commits as branches do.

You can tag new versions using command line:

git checkout {major}.{minor}
git tag -a {major}.{minor}.{patch} -m "Releasing version {major}.{minor}.{patch}"
git push origin {major}.{minor}

After version is tagged, create a GitHub release.

Creating bug fix branches

May branch off from:
{major}.{minor}
Must merge back into:
{major}.{minor} and master
Branch naming convention:
{number}-{slug}

Bug fix branches are similar to feature branches, only they are branched off from a release branch.

Multiple bug fixes can be added to a release branch and released under a single release candidate or patch version.

Creating a feature branch

You can create feature branch using GitHub Web UI, or command line:

git checkout -b {number}-{slug} {major}.{minor}

Merging a feature branch

You can merge a bug fix branch using GitHub Web UI, or command line:

git checkout {major}.{minor}
git merge --no-ff {number}-{slug}
git branch -d {number}-{slug}
git push origin {major}.{minor}

Also you need to add changes back to master:

git checkout master
git merge --no-ff {major}.{minor}
git push origin master

This will merge bug fix branch to release and master branches, deletes bug fix branch and pushes changes to GitHub.