Releases#

Maintainers are suggested to read the entire content of this document.

Release a new version on GitHub#

To release a new version on GitHub, follow the steps below:

Update version number in openbox/__init__.py and update CHANGELOG.md.
Commit and create a new git tag (e.g. v0.8.1). Push the commit and the tag to GitHub.
Wait and make sure tests are passed on GitHub Actions!
Create a new release on GitHub by clicking “Draft a new release” on https://github.com/PKU-DAIR/open-box/releases. Select the tag you just created. Fill in the title (e.g. v0.8.1 - Mar 8, 2023) and description (from CHANGELOG.md).
Double check the release information and the test results on GitHub Actions.
Click “Publish release”. The release will trigger GitHub Actions to build and upload packages to PyPI.

Version Control#

Currently, the version number is manually updated in openbox/__init__.py.

If no new features are added, only bug fixes, the version number should be updated to x.y.z+1.

If API is changed, the version number should be updated to x.y+1.0.

See PEP 440 – Version Identification and Dependency Specification.

TODO: To automatically update version number, setuptools_scm can be used.

You may take BoTorch as an example.

Python Packaging#

See pyproject.toml and MANIFEST.in.

Tutorial:

Caution: In this repo, package will be uploaded to PyPI by GitHub Actions triggered by publishing a release. So, you don’t need to upload the package manually.

To build and test python package locally, or upload the package manually:

python -m pip install --upgrade pip setuptools build twine

# Build
python -m build --sdist --wheel
# For quick build, you may use --no-isolation option.

# Check
tar tf dist/*.tar.gz
unzip -l dist/*.whl
twine check dist/* --strict

# Manually upload to TestPyPI
# twine upload --repository testpypi dist/*
# Manually upload to PyPI (make sure old version files are removed in dist/ !!!)
# twine upload dist/*

# Install from TestPyPI
pip install -i https://test.pypi.org/simple/ ${package_name}

Tips:#

TestPyPI can be used to test package before uploading to PyPI: https://test.pypi.org/
distutils is deprecated with removal planned for Python 3.12. Use setuptools instead.
Deprecated: python setup.py install
setup.py is suggested (by setuptools) to be replaced by setup.cfg or pyproject.toml: https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html

pyproject.toml:#

Configuring setuptools using pyproject.toml files: https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html
Configuring setuptools using setup.cfg files: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html
project metadata: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/

To include files in the package, use `MANIFEST.in`:#

Define entry points:#

Run python -m openbox will execute the entry point defined in pyproject.toml [project.scripts].

PyPI#

OpenBox PyPI: https://pypi.org/project/openbox/

Maintainer access of PyPI project is required to upload packages manually.

Currently, this repo uses GitHub Actions to build and upload packages to PyPI when publishing a release. An API token has been generated on PyPI (To create a new one: https://pypi.org/manage/account/token/) and added to GitHub Secrets (GitHub project - Settings - Security - Secrets and variables - Actions - New repository secret).

PyPI now supports Trusted Publisher Management (https://pypi.org/manage/account/publishing/). If necessary, migrate to Trusted Publisher Management to allow publishing packages from GitHub Actions.

Configure GitHub Actions#

See .github/workflows/publish_on_release.yml.

API token or Trusted Publisher Management is required to upload packages to PyPI.