This document outlines the resources, processes, and procedures for the launch and ongoing operation of the “wpantund” open-source project.
“wpantund” will use Travis for continuous integration testing. All pull requests MUST pass the travis build test before being considered for merging into the master branch.
“wpantund” follows the Semantic Versioning guidelines, with one exception: the minor and patch versions use a minimum of two digits to facilitate better sorting.
In short, the version format is of the form M.mm.pp
, where M
is the major version, mm
is the minor version, and pp
is the patch level. Additional suffixes can be appended according to the release type, as described in the following section.
A “release” denotes a specific state of the code base that has been officially designated a unique identifier called the version (Depending on context, it is sometimes called the release tag). Note that this section refers to a several git branches which are defined in later sections.
Broadly, there are three types of releases:
Primary Releases — Any release in which the release tag takes the form of M.mm.pp
, without any additional annotations. These are the canonical releases. There are generally two categories of primary releases:
00
. Used as feature milestones and are planned well in advance.Pre-Releases — Any release leading up to a primary release. There are three different types of pre-releases:
a#
, e.g.: 1.02.03a4
b#
, e.g.: 1.02.03b4
rc#
, e.g.: 1.02.03rc4
Special Releases — Any release that is intended for a special purpose or task. Denoted by the suffix -*
, e.g. 1.02.03-special
or 4.56.78a9-foobar
.
“Cutting a release” involves the creation and updating of tarballs, branches, and tags. The following git tags are created or updated:
<VERSION>
— The identifying tag of the release, pointing to the commit that is being released. The contents of this tag contain the information contained in the CHANGELOG which has been added since the previous release this release was based on. This tag is cryptographically signed with the OpenPGP signature of a project maintainer. Ex: 1.02.03a4
full/<VERSION>
- A merge commit between the release tag and the corresponding commit from autoconf/master
(See the git repository plan later in this document). In other words, this tag points to the actual files that are released in the official tarballs. Created for each of the two above tags (contains autoconf files). This tag is cryptographically signed with the OpenPGP signature of a project maintainer. Ex: full/1.02.03a4
latest-unstable
— Updated to point to the release tag ONLY if the version of this release is larger than the previous version this tag points to. This is a pointer-only tag.latest-release
— Updated to point to the release tag ONLY if this release is a primary release and ONLY if version of this release is larger than the previous version this tag points to. This is a pointer-only tag, and MUST NOT contain a message.full/latest-unstable
/ full/latest-release
— Created for each of the two above tags (contains autoconf files).Tarballs are created by checking out the full/<VERSION>
tag (created above) and performing a ./configure && make distcheck
. The resulting files are the official tarballs. All released tarballs are cryptographically signed with the OpenPGP signature of a maintainer.
The following is the checklist followed by a project maintainer to cut an official release from the top of the master branch:
git checkout master
. If this fails, STOP.git show
. Verify that Travis has passed the given commit. If this commit has not passed, STOP..default-version
is set to the version that is about to be released. This should already be the case, but if it isn’t go ahead and update .default-version
to the version of the release.Updated CHANGELOG for release <VERSION>
or Updated CHANGELOG and configure.ac for release <VERSION>
.<VERSION>
, making sure pasting in the contents we copied to the clipboard as the tag message. This is performed with the command git tag -s <VERSION>
. If this command fails, STOP.origin/scripts
branch: git checkout origin/scripts
. If this command fails, STOP../primary-release-from-master-helper
; or if this is a prerelease execute the command ./pre-release-from-master-helper
. These commands update autoconf/master
, full/<VERSION>
, latest-unstable
, full/latest-unstable
and (if this is a primary release) latest-release
, full/latest-release
. If the command fails, STOP. Note that the tag full/<VERSION>
will be signed by this process, so you may be asked for your GPG keychain credentials or your token PIN.full/<VERSION>
branch: git checkout full/<VERSION>
. If this command fails, STOP../configure && make distcheck
. If this command fails, STOP.git show master
. Review the commit to make sure it looks sane. If you notice anything wrong, STOP.git show <VERSION>
. Review the tag notes make they look properly formatted. If you notice anything wrong, STOP.git push origin master autoconf/master <VERSION> full/<VERSION>
. If this command fails, STOP.latest-*
tags on the origin server: git push origin latest-release latest-unstable full/latest-release full/latest-unstable
Note that the above checklist is only appropriate for cutting releases from the master branch! Cutting releases from non-master branches would follow a similar (but different) process that is not yet defined.
master
— Main development branch. Acceptable commits are generally limited to those intended for the next major/minor release. Does not contain any autoconf-generated files!autoconf/master
— All of (and only!) the autoconf-generated files associated with master. Automatically maintained by a script that checks if a commit to master has invalidated any of these files and commits updates.scripts
— A collection of repository maintenance scripts.gh-pages
— Will eventually contain the content of http://wpantund.org/.feature/*
— Feature-specific branches that are currently under development but not yet appropriate for inclusion in master.release/M.mm/master
— A separate branch maintained for each minor version release, for tracking things like security updates and back-ported changes. These branches are created when master is opened to taking commits for the next major/minor release.M.mm.pp
— Each primary release is tagged with the bare version number of the release.M.mm.ppx#
— Each pre-release is tagged with the version of the upcoming release with a suffix x
denoting the type of pre-release and #
denoting the count.M.mm.pp-x
— Each special-purpose release is tagged with the version of the most recent official release (for any other type), suffixed with a dash and a short descriptor of the release.full/*
— For each release (primary, pre, or special-purpose), the tag that is the name of the release prefixed with full/
points to a merge commit between the release tag and the corresponding commit from autoconf/master
. In other words, this tag points to the actual files that are released in the official tarballs.latest-release
— A tag with no message that points to the tag of the most recent primary release.full/latest-release
— A tag with no message that points to the tag of the most recent primary release in full/*
.latest-unstable
— A tag with no message that points to the tag of the most recent primary release or pre-release.full/latest-unstable
— A tag with no message that points to the tag of the most recent primary release or pre-release in full/*
.No generated autotools files are allowed in master, or in any branch that doesn’t begin with autoconf/
or full/
.
If you are working from the top of master and don’t have a working copy of autotools, the following command will populate your working tree with all of the appropriate files and is the functional equivalent of typing ./bootstrap.sh
on a machine with autotools installed:
git archive origin/autoconf/master | tar xv
Note that the full/*
branches contain the full set of files, including the sources and autotools files. The autoconf/*
branches contain ONLY the autoconf files.