Here we explain everything the release manager should do when creating a new release of python-graphblas.

The release manager gets to learn and summarize every significant change since the last release, and they decide how to communicate the changes to users, contributors, and fellow maintainers via the changelog. The release manager may--and should!--ask any questions they have about any changes they are unsure about.

Active maintainers should approve when to do a release, thereby giving their approval of the changes since the previous release. If there is not consensus, then work to get consensus. Creating the release notes is currently a manual process, but releasing, building, uploading to PyPI, etc. is automated with Github Actions and triggered by drafting a new release (with a new tag) on Github.

Alpha releases may be done when we want to test it for any reason; for example, if we change the automated CI scripts, or if we want feedback about a feature from a user. Alpha releases have versions such as 2023.3.0a0, 2023.3.0a1, etc., and must be chosen as a pre-release--Set as pre-release checkmark--when drafting a new release on Github. Alpha releases should have complete release notes. The release notes should be moved to the latest (non-alpha) release once it's available, and the the release notes for the alpha release should be changed to e.g. "This is a pre-release; see 2023.3.0".

We have no set frequency for how often we perform releases. Releases could occur daily, weekly, monthly, or even yearly, but to date we typically release approximately monthly. Releasing too frequently may make it difficult for users to keep up to date with changes and the different versions. Not all releases need to have major new features. Valid reasons:

• support new versions of Python or dependencies
• add or remove deprecations
• bug fixes (major or minor)
• documentation enhancements
• somebody asked for a new release

• On Github, select "Draft a new release" button
• "Set as latest release" checkmark (the default)
• Set tag and title as the same, such as YYYY.M.N
  • YYYY is the year, such as 2023
  • M is the month (not zero-padded), such as 3 or 10
  • N is enumerated from 0 for the current year and month
    • For example, the first release in a month is 2023.3.0, the second is 2023.3.1, etc.
• Add release notes (see example below)
  • Also, post the release notes to Release notes review thread on the Discord channel for a day or so for general awareness and to get feedback and approval
• Click "Publish release" and viola!
  • CI should build wheels, sdist, and upload to PyPI
  • Monitor CI and check PyPI for any errors
• Build on conda-forge
  • https://github.com/conda-forge/python-graphblas-feedstock
  • If patient, the auto-tick bot should automatically create a PR
    • Review the PR (such as if any dependencies changes) and merge
    • Usually, no changes are necessary
  • If impatient or changing dependencies, create a PR from scratch
    • Typically, only version number and sha256 hash values need changed
    • Add @conda-forge-admin, please rerender comment to PR to rerender

It is also good practice to run ./scripts/check_versions.sh to see if there are any new versions of dependencies that we ought to support.

Release notes are for people (users, contributors, maintainers, etc), and we manually write release notes to summarize what people ought to know. Typically, all PRs are in release notes, and a single PR may appear multiple times if it did multiple things. Release notes are currently only on Github; we don't yet have a CHANGELOG.md file or a change log section in our documentation, but we could add these if requested and we feel doing so adds enough value. If the amount of changes in a single release consistently becomes unmanageable, then we can revisit how we write changelogs.

How we organize the changelog has evolved organically. Changes should be organized by sections; see example sections below. When writing release notes, please try to follow conventions as done in previous release notes. However, the current release manager may change the sections and how they are organized; if you do so, please update the example below. To learn more about changelogs, see how other projects do them and see e.g. https://keepachangelog.com/

Example release notes illustrating all sections:

Breaking changes
----------------
- Change something in a backward-incompatible way (#nnn)
    - Explain why we thought this was necessary (and not a deprecation)
    - Explain the breakage and what users should do about it

Highlights
----------
- Add something amazing this release! (#nnn)
    - Describe in more detail
    - Example: `this is awesome`
    - No need to duplicate this in "Enhancements" section below

Expired deprecations
--------------------
- Removed deprecated feature (#nnn)
    - Use something else instead

Deprecations
------------
- Deprecate something (#nnn)
    - Use something else instead
    - Will be removed in version 2023.11.0 or later

Enhancements
------------
- Add something (#nnn)

Bug fixes
---------
- Fix something (#nnn)

Maintenance
-----------
- Do something that maintainers may care about, but not most users (#nnn)
- Misc. maintenance (#mmm, #nnn, #ooo)

Security
--------
- We haven't had any security reports or fixes yet (#nnn)

New contributors
----------------
- We welcomed @xxx as a new code contributor this release :tada:

**_PSA: announce something important about the broader GraphBLAS community_**