Skip to content

Latest commit

 

History

History
158 lines (98 loc) · 4.92 KB

releasing.rst

File metadata and controls

158 lines (98 loc) · 4.92 KB

Release procedures

Here we try to keep an up to date record of how Mopidy releases are made. This documentation serves both as a checklist, to reduce the project's dependency on key individuals, and as a stepping stone to more automation.

Releasing extensions

Extensions that are maintained in the Mopidy organization use a quite stream-lined release procedure.

  1. Make sure that everything has been merged into the main branch on GitHub, and that all CI checks are green.

  2. Perform any manual tests you feel are required.

  3. Bump the version in setup.cfg in line with :ref:`our strategy <versioning>`. For example, to 2.0.2.

  4. Commit the bumped version:

    git commit -m "Release v2.0.2"

  5. Tag the commit with an annotated tag:

    git tag -a -m "Release v2.0.2" v2.0.2

    It is encouraged to use -s to sign the tag if you have a GnuPG setup.

  6. Push to GitHub:

    git push origin main --follow-tags

  7. Go to the GitHub repository's tags page, e.g. https://github.com/mopidy/mopidy-foo/tags. Find the tag and select "Create release" in the tag's dropdown menu.

  8. Copy the tag, e.g. v2.0.2 into the "title" field. Write a changelog entry in the description field, and hit "Publish release".

  9. GitHub Actions now builds the package and uploads it to PyPI.

This procedure has several benefits:

  • Everyone with commit access can make releases.
  • No one, except those with direct PyPI access, can make releases without also leaving the source code of what they released publicly available on GitHub, creating an audit log in case of any malicious actions.
  • The changelog can be amended post-release through the GitHub Releases UI.

The primary drawback of this procedure is that there is no obvious way to maintain a changelog in-between releases. The preferred solution is to make releases often, so that writing up a changelog from the recent Git commits is done in a minute or two.

How to setup this release workflow

If you maintain a Mopidy extension, you're encouraged to adopt the same procedure.

To setup this on your own repo, you must:

  1. Copy .github/workflows/release.yml from the Mopidy cookiecutter project.
  2. Create an API token in your account settings at PyPI with scope to access the extension's PyPI package.
  3. Copy the token to a new secret called PYPI_TOKEN in your GitHub repo's settings. Ignore the section titled "Using this token" on PyPI.

With the release.yml file and the PYPI_TOKEN secret in place, releases should automatically be uploaded to PyPI when you follow the procedure above.

Releasing Mopidy itself

Mopidy itself is a bit more complicated than extensions because the changelog is maintained in the Git repo.

Preparations

  1. Make sure that everything has been merged into the main branch on GitHub, and that all CI checks are green.
  2. Make sure the changelog in the docs/changelog.rst file includes all significant changes since the last release. Commit and push it.
  3. Perform any manual tests you feel are required.

Release

  1. Select a version number in line with :ref:`our strategy <versioning>`, e.g. v3.3.0 in the following examples.

  2. Update the release in docs/changelog.rst with the right version number and release date.

  3. Commit the final touches to the changelog:

    git commit -m "Release v3.3.0"

  4. Tag the commit with an annotated tag:

    git tag -a -m "Release v3.3.0" v3.3.0

    It is encouraged to use -s to sign the tag if you have a GnuPG setup.

  5. Verify that Mopidy reports the new version number:

     mopidy --version

If it doesn't, check that you've properly tagged the release.

  6. Push to GitHub:

    git push origin main --follow-tags

  7. Go to the GitHub repository's tags page. Find the tag and select "Create release" in the tag's dropdown menu.

  8. Copy the tag, e.g. v3.3.0 into the "title" field. Write a changelog entry in the description field, and hit "Publish release".

  9. GitHub Actions now builds the package and uploads it to PyPI.

Post-release

  1. Make sure the new tag is built by Read the Docs, and that the "stable" version shows the newly released version.
  2. Spread the word through an announcement post on the Discourse forum.
  3. Notify distribution packagers, including but not limited to: