Releasing MGET
Note
This page still need to be fleshed out. While we are still getting the project up and running on GitHub, we plan to release MGET manually. This includes uploading the wheels to PyPI and uploading the docuemtation to Read the Docs. As development progresses, we aim to automate these procedures with GitHub’s automation features. We’re holding off from documenting all of this while it is still in flux.
Setting the version number
Note
This section needs to be reviewed, especially after we sort out automated builds on GitHub.
We do not manually write the version number into any source files. Instead, we use git tags to attach the version number to a commit, and then rely on setuptools_scm to extract the version number from the git tag and store it in the appropriate places. We use setuptools_scm’s default versioning scheme which guesses a unique, incremented version number based on the most recent tag in the repository and the number of revisions since it was created. What this is, and what you should do, depends where you are in the release cycle.
When starting development of a new major or minor release
After making your first commit, add an annotated tag
with the format vX.Y.0.dev0, where X and Y are the major and minor
version numbers, respectively, e.g.:
git tag -a v3.0.0.dev0 -m "Starting development of v3.0.0"
Note that you should still include the full three digits for the major, minor,
and patch numbers, e.g. v3.0.0.dev0, even if some of them are 0. If
you now build (after you added the tag but before you have made any other
commits), setuptools-scm will set the version number to that of the tag.
When starting the development of a patch release
In this situation, because of some clever behavior of setuptools_scm, you do
not need to do anything to maintain the version number. When setuptools_scm
examines the git history and finds that the most recent tag has the format
vX.Y.Z with no .dev on the end, it knows that was a final release and
thus assumes that the next commit will start a patch release. It automatically
increments the patch number Z to Z``+1 and adds ``.dev0. So if your
the most recent tag was v3.0.0, the version number will become
v3.0.1.dev0. You do not need to manually create a tag for this to occur.
When continuing development of a release (committing more changes)
As you commit more changes while developing a release, you also do not need to
do anything to maintain the version number. When you build, setuptools-scm
will access the git history, determine how many commits have happened since
the most recent final release, and append .devX to the build number, where
X is the number of commits you are from the most recent tag.
After making the final commit for a release
After committing the final code change for a release, tag it with the version
number unadorned with .devX, like this:
git tag -a v3.0.0 -m "Completed development of v3.0.0"
Note that you should still include the full three digits for the major, minor,
and patch number, e.g. v3.0.0, even if some of them are 0. As above,
if you now build (before you have made any other commits), setuptools-scm will
set the version number to that of the tag.