Publish a new release

This page describes the maintainer workflow for publishing a DASCore release. DASCore’s package version is derived from git tags, so the release tag is the source of truth and no version file needs to be edited by hand.

Before releasing

Make sure the docs build. Because the doc-build can take a bit of time, the doc-build is not automatically tested on each PR. You can test this using the documentation tag on a new PR, or run it locally following the doc-build instructions.

Next, from the github interface navigate to DASCore’s release page and click on draft new release. For the tag, note the latest release, then choose the next version tag using DASCore’s versioning policy in the general guidelines (eg if the latest version is v0.1.20 then type v0.1.21 for a patch/bug fix release and v0.2.0 for a larger feature release).

Draft the release notes

Compare the merged changes since the previous release and group user-facing changes into a short changelog. The changelog should usually include these sections:

  • New Features
  • Bug Fixes
  • Breaking Changes

The GitHub releases page can generate release notes automatically, but maintainers should review and edit the generated text so it is useful to users. Also note, DASCore includes an agent skill called “draft release” so a coding agent of your choice can help you do this. In the changelog, prefer concise descriptions of behavior and API changes over internal implementation details. Include pull request links when they help readers find more context.

Then click ‘Publish Release’. This will kick off the doc-build and publishing task automatically, as well as publish the tagged source code to PyPI.

Verify package and docs publishing

After publishing, open GitHub Actions and confirm the release workflows complete successfully.

  • PublishPackage builds the distributions and uploads DASCore to PyPI.
  • BuildDeployStableDocs builds the stable documentation, deploys it to GitHub Pages, and uploads docs.zip to the GitHub release. This may take 30 minutes or more.

Once the workflows finish, check that PyPI shows the new version and that the stable documentation site reflects the release. If a workflow fails, fix the underlying issue on master, publish a new patch release if the tag has already been distributed, and avoid moving or replacing a public release tag.

Conda-forge

Unfortunately, simply creating the tag will not publish to conda-forge automatically. To do this, first wait until the new package appears on DASCore’s PyPI page. Next, navigate to DASCore’s feedstock and open a new issue. Click “bot commands” and create an issue with the title “(conda-forge-admin?), please update version”. The conda-forge bot will then see there is a new release on PyPI and open a PR. Alternatively, the bot will automatically see the new version and open a new PR within a day or so.

When this PR opens, examine the requirements and dependencies listed, and make sure they have not gotten out of sync with DASCore’s current pyproject.toml. In general, conda-forge should lean more towards including dependencies that are optional, although some have been abandoned if they are very slow at making conda releases. Once this is correct, merge the pull request. After the feedstock PR is merged, the new version should be published to conda-forge in an hour or so. Verify the new package appears on conda-forge.