Making a release

A core developer should use the following steps to create a release X.Y.Z of scikit-build on PyPI and Conda.

Prerequisites

• All CI tests are passing on GitHub Actions and Azure Pipelines.

• You have a GPG signing key.

Documentation conventions

The commands reported below should be evaluated in the same terminal session.

Commands to evaluate starts with a dollar sign. For example:

$ echo "Hello"
Hello

means that echo "Hello" should be copied and evaluated in the terminal.

Setting up environment

1. First, register for an account on PyPI.

2. If not already the case, ask to be added as a Package Index Maintainer.

3. Create a ~/.pypirc file with your login credentials:

   [distutils]
   index-servers =
     pypi
     pypitest
   
   [pypi]
   username=<your-username>
   password=<your-password>
   
   [pypitest]
   repository=https://test.pypi.org/legacy/
   username=<your-username>
   password=<your-password>
   

where <your-username> and <your-password> correspond to your PyPI account.

PyPI: Step-by-step

1. Make sure that all CI tests are passing on GitHub Actions and Azure Pipelines.

2. Download the latest sources (or use an existing git checkout)

$ cd /tmp && \
  git clone git@github.com:scikit-build/scikit-build && \
  cd scikit-build

3. List all tags sorted by creation date

$ git tag -l --sort creatordate

4. Choose the next release version number

$ release=X.Y.Z

Warning

To ensure the packages are uploaded on PyPI, tags must match this regular expression: ^[0-9]+(\.[0-9]+)*(\.post[0-9]+)?$.

5. In CHANGES.rst replace Next Release section header with Scikit-build X.Y.Z and commit the changes.

$ git add CHANGES.rst && \
  git commit -m "Scikit-build $release"

6. Tag the release

$ git tag --sign -m "Scikit-build $release" $release main

Warning

We recommend using a GPG signing key to sign the tag.

7. Publish both the release tag and the main branch

$ git push origin $release && \
  git push origin main

8. Make a GitHub release. Paste the converted release notes as markdown; convert using

cat CHANGES.rst | pandoc -f rst -t gfm

and then edit the result (it will not be perfect) to prepare the body of the release. You can also try clipboardtomarkdown or copying to a draft discord post. PRs should be converted to simple #<number> form. Be sure to use the tag you just pushed as the tag version, and Scikit-build X.Y.Z should be the name.

Note

For examples of releases, see https://github.com/scikit-build/scikit-build/releases

9. Add a Next Release section back in CHANGES.rst, commit and push local changes.

$ git add CHANGES.rst && \
  git commit -m "CHANGES.rst: Add \"Next Release\" section [ci skip]" && \
  git push origin main

10. Add an entry to the Announcements category of the scikit-build discussions board.

Note

For examples of announcements, see https://github.com/orgs/scikit-build/discussions/categories/announcements

Conda: Step-by-step

Warning

Publishing on conda requires to have corresponding the corresponding Github release.

After a GitHub release is created in the scikit-build project and after the conda-forge Autoticking Bot creates a pull request on the scikit-build-feedstock , follow these steps to finalize the conda package release:

1. Review the pull-request

2. Merge pull-request

In case the bot failed (e.g because of GH rate limitation) and in order to explicitly release a new version on conda-forge, follow the steps below:

1. Choose the next release version number (that matches with the PyPI version last published)

$ release=X.Y.Z

2. Fork scikit-build-feedstock

First step is to fork scikit-build-feedstock repository. This is the recommended best practice by conda.

3. Clone forked feedstock

   Fill the YOURGITHUBUSER part.

   $ YOURGITHUBUSER=user
   $ cd /tmp && git clone https://github.com/$YOURGITHUBUSER/scikit-build-feedstock.git
   

4. Download corresponding source for the release version

$ cd /tmp && \
  wget https://github.com/scikit-build/scikit-build/archive/$release.tar.gz

5. Create a new branch

   $ cd scikit-build-feedstock && \
     git checkout -b $release
   

6. Modify meta.yaml

   Update the version string and sha256.

   We have to modify the sha and the version string in the meta.yaml file.

   For linux flavors:

   $ sed -i "1s/.*/{% set version = \"$release\" %}/" recipe/meta.yaml && \
     sha=$(openssl sha256 /tmp/$release.tar.gz | awk '{print $2}') && \
     sed -i "2s/.*/{% set sha256 = \"$sha\" %}/" recipe/meta.yaml
   

   For macOS:

   $ sed -i -- "1s/.*/{% set version = \"$release\" %}/" recipe/meta.yaml && \
     sha=$(openssl sha256 /tmp/$release.tar.gz | awk '{print $2}') && \
     sed -i -- "2s/.*/{% set sha256 = \"$sha\" %}/" recipe/meta.yaml
   

   Commit local changes.

   $ git add recipe/meta.yaml && \
       git commit -m "scikit-build v$release version"
   

7. Push the changes

   $ git push origin $release
   

8. Create a Pull Request

   Create a pull request against the main repository. If the tests are passed a new release will be published on Anaconda cloud.