Release Command

The cirrus release command contains several commands related to triggering, building and merging releases following a git flow style workflow using release branches. While the release process can be run locally, it also can be automated with a CI platform such as Jenkins to allow hands off triggering of releases, builds and distribution vi a pypi.

New Release

The git cirrus release new command handles bootstrapping a new release branch by incrementing the package version, generating release notes from the git commit history as well as optionally bumping dependency versions in requirements.txt to automate build chains where a downstream package is updated.

Cirrus uses semantic versioning, so the new release is created with a flag indicating which version number (major, minor, micro) to increment. To bump dependencies, you can specify the --bump option multiple times, it expects two arguments each time, one for package and one for the version to use.

usage: release [command] new [-h] [--micro] [--minor] [--major]
                             [--bump BUMP BUMP] [--no-remote]

optional arguments:
  -h, --help        show this help message and exit
  --micro
  --minor
  --major
  --bump BUMP BUMP  package versions to update in requirements.txt, eg --bump
                    argparse 1.2.1 --bump womp 9.9.9
  --no-remote       dont push release branch to remote

Examples:

Create a new micro release

git cirrus release new --micro

Create a new micro release and set the requests dependency version to 2.3.0

git cirrus release new --micro --bump requests 2.3.0 

Build Release

The git cirrus release build command is a simple wrapper around the setuptools sdist command. It creates the uploadable artifact for pypi or pip installation using the MANIFEST.in file to add extra data files to the package. The artifact will have the same version as the current cirrus version

git cirrus release build

Upload Release

The git cirrus release upload command is a pluggable wrapper for pushing your release artifact to a pypi server. The default mode of operation uses the setuptools sdist & upload stanza, but there is also support for an scp to a remote server. Note that uploading will use settings from any .pypirc file found in your home directory, if in doubt use the --pypi-url option to set which server to upload to if you are using private servers instead of the default python.org pypi server.

usage: release [command] upload [-h] [--test] [--plugin PLUGIN]
                                [--pypi-url PYPI_URL] [--pypi-sudo]
                                [--no-pypi-sudo]

optional arguments:
  -h, --help            show this help message and exit
  --test                test only, do not actually push or upload
  --plugin PLUGIN       Uploader plugin to use
  --pypi-url PYPI_URL, -r PYPI_URL
                        upload to specified pypi url
  --pypi-sudo           use sudo to upload build artifact to pypi
  --no-pypi-sudo        do not use sudo to upload build artifact to pypi

Release Merge

The git cirrus release merge command handles the merging, tagging and closeout of the git flow workflow for a release, merging the release into develop and master branches and creating a tag with the current cirrus package version. There are several helpers to work with slow moving CI processes and status checks that may block the branch merges with github based CI workflows.

usage: release [command] merge [-h] [--wait-on-ci]
                               [--context-string GITHUB_CONTEXT_STRING]
                               [--develop-context-string GITHUB_DEVELOP_CONTEXT_STRING]
                               [--master-context-string GITHUB_MASTER_CONTEXT_STRING]
                               [--cleanup] [--skip-master] [--skip-develop]
                               [--log-status] [--no-remote]

optional arguments:
  -h, --help            show this help message and exit
  --wait-on-ci          Wait for GH CI status to be success before uploading
  --context-string GITHUB_CONTEXT_STRING
                        Update the github context string provided when pushed
  --develop-context-string GITHUB_DEVELOP_CONTEXT_STRING
                        Update the github context string for develop branch
                        provided when pushed
  --master-context-string GITHUB_MASTER_CONTEXT_STRING
                        Update the github context string for master branch
                        provided when pushed
  --cleanup             Clean up release branch after merging
  --skip-master         Skip the master merge and push
  --skip-develop        Skip the develop merge and push
  --log-status          log all status values for branches during command
  --no-remote           Do not remove remote branch if set

Examples:

Merge a release, tag master and clean up the release branch

git cirrus release merge --cleanup