# 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.