Releasing on GitHub

Phew, what a whirlwind. Now that we've got our code on GitHub, our docs on ReadTheDocs and Travis going we're ready to release!

A release is simply a point in the lifecycle of a software project where the maintainers believe the software is worth trying and using. Pre-release releases are used for cases where the code is in early preview and may still contain bugs. Stable releases typically aren't released with known bugs and are geared towards wide adoption.

Creating or "cutting" a new release is also the point where the maintainer typically provides pre-built or binary releases. In our case, we've setup Travis to automatically provide mpy binary files for every release.

To get started, pull up your repo and click the releases button.

Once there, click Create a new release.

Now, decide on a version number for this release. CircuitPython's tools require Semantic Versioning (shortened to SemVer) to work. SemVer is three numbers separated by periods. This is not the same as a decimal number since there are two periods. Anything less than 1.0.0 is typically pre-release and anything after marked alpha, beta or rc for release candidate is also. For example, 1.0.0-rc.1 would be the first release candidate for 1.0.0 and be pre-release. Normal releases would be something like 0.10.0. Do not start the version with a v.

The first number should be incremented and others reset to 0 when the library was changed in a way that may require old code to be rewritten. Changing public function names for example would cause 1.3.0 to become 2.0.0.

The second number should be incremented, leaving the first and setting the third to zero if new functionality was added but the existing code is compatible. For example add a new function would lead from 1.3.3 to 1.4.0.

Lastly, the third number should be incremented if existing functionality was fixed. For example a function released in 1.4.0 didn't always work as expected and it was fixe in 1.4.1.

Once you decide on a version number enter it into the top box. This will create a git tag that will mark when in the git history the release occurred. You can also do this from git and then refer to an existing tag here.

Next, fill in the title and give the release a description including pointers to other related resources.

The release description uses Markdown for formatting and you can preview what it would look like after the save using the Preview tab. Here is a copy of the release description so you can start with it!

Download: file
Adds basic `hello` functionality.

To use in CircuitPython, download the .mpy file and copy it to the `lib` folder on the `CIRCUITPY` drive. Or, simply install the [Community bundle](https://github.com/adafruit/CircuitPython_Community_Bundle).

Read the [docs](https://circuitpython-example.readthedocs.io/en/latest/) for info on how to use it.
If you chose not to set up Travis to build your release binaries, this is when you can upload them yourself.

Now that everything looks good, lets publish the release. Don't forget to tick the pre-release box (under the arrow) if you want this to be marked as such.

After you hit publish you'll be taken to the release page on GitHub. This is a great place to link folks to so they can get all of the latest information on the release. GitHub includes zip files of the full source code by default.

The release also triggers a build from Travis. Navigate to the Travis project to check on it. Everything should be green.

Once Travis is green, the release should be updated with the .mpy file for the release. This file can then be copied to the CIRCUITPY drive to be used.

The other way folks can use the library is by downloading it as a part of a larger bundle. We have the Adafruit bundle for officially supported libraries and the Community bundle for those created and maintained by the larger community.

This guide was first published on Jul 31, 2017. It was last updated on Jul 31, 2017. This page (Releasing on GitHub) was last updated on Sep 02, 2019.