How to release libStorage
This project has three parallels stages of release:
||The tip or HEAD of the
||A commit tagged with the suffix
||A commit tagged with a version sans
There are no steps necessary to create an
unstable release as that happens
automatically whenever an untagged commit is pushed to
master. However, the
following workflow should be used when tagging a
staged release candidate
- Review outstanding issues & pull requests
- Prepare release notes
- Update the version file
- Commit & pull request
- Tag the release
Review Issues & Pull Requests¶
If there are outstanding issues requiring changes or pending pull requests to be merged, handle those prior to tagging any commit as a release candidate or release.
It is highly recommended that pull requests be merged synchronously after
rebasing each subsequent one off of the new tip of
master. Remember, while
GitHub will update a pull request as in conflict if a change to
results in a merge conflict with the pull request, GitHub will not force a
new build to spawn unless the pull request is actually updated.
At the very minimum a pull request's build should be re-executed prior to the
pull request being merged if
master has changed since the pull request was
Prepare Release Notes¶
Update the release notes at
.docs/about/release-notes.md. This file is
project's authoritative changelog and should reflect new features, fixes, and
any significant changes.
The most recent,
stable version of the release notes are always available
libStorage's documentation site.
Update Version File¶
VERSION file exists at the root of the project and should be updated to
reflect the value of the intended release.
For example, if creating the first release candidate for version 0.1.0, the
contents of the
VERSION file should be a single line
0.1.0-rc1 followed by
a newline character:
$ cat VERSION 0.1.0-rc1
If releasing version 0.1.0 proper then the contents of the
0.1.0 followed by a newline character:
$ cat VERSION 0.1.0
Commit & Pull Request¶
Once all outstanding issues and pull requests are handled, the release notes and version are updated, it's time to create a commit.
Please make sure that the changes to the release notes and version files are a part of the same commit. This makes identifying the aspects of a release, staged or otherwise, far easier for future developers.
A release's commit message can either be a reflection of the release notes or something simple. Either way the commit message should have the following subject format and first line in its body:
Release Candidate 0.1.0-rc1 This patch marks release candidate 0.1.0-rc1.
If the commit message is longer it should simply reflect the same information from the release notes.
Once committed push the change to a fork and open a pull request. Even though this commit marks a staged or official release, the pull request system is still used to assure that the build completes successfully and there are no unforeseen errors.
Tag the Release¶
Once the pull request marking the
stable release has been merged
master it's time to tag the release.
The release tag should follow a prescribed format depending upon the release type:
|Release Type||Tag Format||Example|
There are two ways to tag a release:
- GitHub Releases
- Command Line
If tagging a release via the command line be sure to fetch the latest changes
master and either merge them into your local copy of
master or reset the local copy to reflect
upstream prior to creating
The following combination of commands can be used to create a tag for 0.1.0 Release Candidate 1:
git fetch upstream && \ git checkout master && \ git reset --hard upstream/master && \ git tag -a -m v0.1.0-rc1 v0.1.0-rc1
The above example combines a few operations:
- The first command fetches the
- The local
masterbranch is checked out
- The local
masterbranch is hard reset to
- An annotated tag is created on
v0.1.0-rc1, or 0.1.0 Release Candidate 1, with a tag message of
Please note that the third step will erase any changes that exist only in the
master branch that do not also exist in the remote, upstream copy.
However, if the two branches are not equal this method should not be used to
create a tag anyway.
The above steps do not actually push the tag upstream. This is to allow for one
final review of all the changes before doing so since the appearance of a new,
annotated tag in the repository will cause the project's build system to
automatically kick off a build that will result in the release of a
stable release. For
stable releases the project's documentation will also be
Once positive everything looks good simply execute the following command to
push the tag to the
git push upstream v0.1.0-rc1