Phew, what a whirlwind. Now that we've got our code on GitHub, our docs on ReadTheDocs and GitHub Actions 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 Actions 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!
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.
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 few release workflows from Actions. Navigate to the Actions page to check on them. Everything should be green.
Once Actions 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.
Common Release Failures
Almost all release failures happen in the 'Build and Publish' section of the 'upload-pypi' workflow. Here are the two most common ones.
HTTPError: 400 Client Error: File already exists.
This happens when there is no change in the driver since the last release. This usually happens when something needs to be re-released with no changes for some reason, often the incorrect semver version being used. The easiest way to fix this is to make a tiny change in a docstring or comment in the driver file and re-release.
HTTPError: 403 Client Error: Invalid or non-existent authentication information.
This happens when PyPi credentials haven't been added. It's possible that library shouldn't be on PyPi, so be sure of that before adding credentials. To get that fixed, create an issue on GitHub and assign it to CircuitPythonLibrarians, and briefly explain the issue, linking to the Release Action.
Error: unexpected status code: 403 {"message":"Resource not accessible by integration" while uploading a release
This happens when the workflow on github is not allowed write access to the repository. To fix this, go to "repository settings". On the left, open the "actions" section and click "general". Finally, under "workflow permissions" allow "read and write permissions". This is necessary in order to allow uploading files to a GitHub release from the release action.
Text editor powered by tinymce.
