How to release Python package

PyPI/GitHub release

Important

Make sure you have your project is standarlized with scikit-package. Otherwise, please start from the Getting started page here.

1. In the repository, create an issue on GitHub with the “Release” option as shown below:

   

2. Check off all items in the first checklist for PyPI/GitHub release.

Instructions for Project Owner for release

1. Review the checklist prepared by the contributor in the issue.

2. Ensure PYPI_TOKEN and PAT_TOKEN are configured at the org level. See Appendix 1, 2, respectively.

3. Check the github_admin_username section in .github/workflows/build-wheel-release-upload.yml is that of the project owner.

4. In your terminal, run git checkout main && git pull upstream main to sync with the main branch.

5. Run the following:

   # For pre-release, use *.*.*rc* e.g., 1.0.0rc0
   # For release, use *.*.* e.g., 1.0.0
   git tag <version-number>
   git push upstream <version-number>
   

6. Done! Once the tag is pushed, visit the Actions tab in the repository to monitor the CI progress.

7. Comment GitHub/PyPI release done! or GitHub/PyPI pre-release done! in the release GitHub issue.

8. The contributor will make a PR into the conda-forge feedstock. Review and approve the PR.

9. Wait for the contributor to test the released package. The issue will be closed by the contributor.

Appendix 1. Setup PYPI_TOKEN

Generate a PyPI API token from pypi.org:

1. Visit https://pypi.org/manage/account/ and log in.

2. Scroll down to the API tokens section and click Add API token.

3. Set the Token name to PYPI_TOKEN.

4. Choose the appropriate Scope for the token.

5. Click Create token and copy the generated token.

Add the generated token to GitHub:

1. Navigate to the Settings page of the org (or repository).

2. Click the Actions tab under Secrets and variables.

3. Click New org secret, name it PYPI_TOKEN, and paste the token value.

4. Done!

Appendix 2. Setup PAT_TOKEN

The GitHub workflow needs to link with this privilege through a personal access token (PAT) of the project owner.

1. Visit https://github.com/settings/tokens

2. Click Generate new token and choose the classic option.

3. Under Note, write, “GitHub CI release”

4. Set the Expiration date of the token.

5. Under Select scopes, check repo and user.

6. Scroll down, click Generate token.

7. Done!

Copy and paste the PAT_TOKEN to your GitHub organization:

1. Visit Settings in the organization.

2. Click the Actions tab under Secrets and variables.

3. Click New organization secret and add a new secret and name it as PAT_TOKEN.

4. Done!

Appendix 3. How to host your package documentation online

You have API doc built and tested locally. Now you want to deploy your doc via i.e., https://diffpy.github.io/diffpy.utils using GitHub Pages.

1. Go to your Settings page in your repository and and click pages under Code and automation.

2. Click Deploy from a branch under Source. Below, choose gh-pages branch and /(root) and click Save.

Done! Wait a few minutes and visit your GitHub Pages URL!