Release process¶
This page describes the recommended release process for maintainers of Django-AWS-API-Gateway-WebSockets.
It is intended for project maintainers rather than end users.
Overview¶
A release usually involves:
reviewing open changes;
updating the version;
updating the changelog;
running tests;
building the package;
checking the package contents;
publishing to PyPI;
creating a Git tag or GitHub release;
confirming that Read the Docs has rebuilt.
Before starting¶
Before preparing a release, check that:
the main branch is green in CI;
all intended pull requests have been merged;
documentation has been updated;
new public behaviour is covered by tests;
the changelog has been updated;
dependency updates are intentional;
the package builds successfully.
Check the current version¶
The package version is defined in pyproject.toml.
Check the current version before deciding the next one.
Use semantic versioning¶
Use semantic versioning where practical:
MAJORBreaking changes.
MINORNew backwards-compatible functionality.
PATCHBackwards-compatible bug fixes.
Examples:
1.4.1 -> 1.4.2 bug fix
1.4.1 -> 1.5.0 new feature
1.4.1 -> 2.0.0 breaking change
Update the version¶
Update the version in pyproject.toml.
Example:
[project]
version = "1.5.0"
If the version is referenced anywhere else in the project, update those references too.
Update the changelog¶
Update docs/changelog.rst with the new release notes.
A typical entry should include:
version number;
release date;
added features;
bug fixes;
documentation changes;
deprecations;
removals;
security-related changes, where appropriate.
Example:
1.5.0 - 30th April 2026
=======================
- Added WebSocket token documentation.
- Added deployment and troubleshooting guides.
- Improved API Gateway setup documentation.
If the project adopts Towncrier or another changelog tool, generate the changelog before building the release.
Example Towncrier workflow:
towncrier build --version 1.5.0
Review generated changes before committing them.
Run formatting and pre-commit checks¶
Run pre-commit checks before release.
pre-commit run --all-files
If pre-commit updates files, review and commit the changes.
Run tests¶
Run the test suite.
coverage erase
python -W error::DeprecationWarning -W error::PendingDeprecationWarning -m coverage run --parallel -m pytest --ds tests.settings
coverage combine
coverage report
If the project uses tox for the full compatibility matrix, run tox before publishing.
tox
At minimum, make sure CI has passed for the supported Python and Django combinations.
Build the documentation locally¶
Build the Sphinx documentation locally.
cd docs
make html
Open the generated HTML and check:
the index page renders correctly;
new pages are included in the toctree;
cross-references work;
code blocks render correctly;
there are no unexpected warnings;
the changelog is visible.
Build the package¶
Build the source distribution and wheel.
python -m build --sdist --wheel
This creates files under:
dist/
If the build package is not installed in your release environment, install it
into your virtual environment first.
python -m pip install build
Check the package¶
Use Twine to check the built distributions.
python -m twine check dist/*
If Twine is not installed, install it into your virtual environment.
python -m pip install twine
Inspect the package contents¶
Before uploading, inspect the generated files.
Useful checks include:
package modules are included;
migrations are included;
management commands are included;
license file is included;
README is included;
metadata is correct;
version is correct.
You can inspect the source distribution manually by unpacking it from dist/.
Test publish if needed¶
For larger releases, consider uploading to TestPyPI first.
python -m twine upload --repository testpypi dist/*
Then install from TestPyPI in a clean virtual environment and perform a smoke test.
python -m pip install --index-url https://test.pypi.org/simple/ django-aws-api-gateway-websockets
Publishing to PyPI¶
When ready, upload to PyPI.
python -m twine upload dist/*
Use a PyPI API token rather than a password.
Do not commit PyPI tokens to the repository.
Create a Git commit¶
Commit the release changes.
git add pyproject.toml docs/changelog.rst
git commit -m "Release 1.5.0"
Include any other files that were intentionally changed as part of the release.
Create a Git tag¶
Create an annotated tag for the release.
git tag -a 1.5.0 -m "Release 1.5.0"
Push the commit and tag.
git push origin main
git push origin 1.5.0
If your project uses a v prefix for tags, use that consistently instead.
Example:
git tag -a v1.5.0 -m "Release 1.5.0"
git push origin v1.5.0
Create a GitHub release¶
Create a GitHub release from the tag.
The release notes can usually be copied from docs/changelog.rst.
Include:
summary of the release;
notable features;
bug fixes;
breaking changes;
upgrade notes;
links to documentation.
Confirm Read the Docs build¶
After pushing to main or creating a release, confirm that Read the Docs has
rebuilt successfully.
Check:
the build completed;
the new changelog is visible;
the version shown in the docs is correct;
new pages render as expected.
If GitHub Actions triggers the Read the Docs build, check the workflow result as well.
Post-release checks¶
After publishing, perform a quick smoke test.
In a clean virtual environment:
python -m pip install django-aws-api-gateway-websockets
Then check:
the package imports;
Django can include the app in
INSTALLED_APPS;migrations are available;
management commands are available;
documentation links work;
PyPI shows the correct version.
Start the next development cycle¶
After the release, decide whether to update the version to the next development version.
For example:
[project]
version = "1.5.1.dev0"
Only do this if that matches the project’s versioning approach.
Release checklist¶
Use this checklist for each release.
Pre-release¶
Main branch is up to date.
CI is passing.
Version has been updated.
Changelog has been updated.
Documentation has been updated.
Tests have been run.
Pre-commit checks pass.
Documentation builds locally.
Build¶
Old build artifacts have been removed.
Source distribution has been built.
Wheel has been built.
Twine check passes.
Package contents have been inspected.
Publish¶
Package has been uploaded to PyPI.
Git commit has been created.
Git tag has been created.
Commit and tag have been pushed.
GitHub release has been created.
Read the Docs build has completed.
Post-release¶
Package installs from PyPI.
Version on PyPI is correct.
Documentation version is correct.
Changelog is visible.
Any release announcement has been made.
Cleaning old build artifacts¶
Before building, remove old artifacts.
rm -rf dist build *.egg-info
On Windows PowerShell:
Remove-Item -Recurse -Force dist, build, *.egg-info
Common release problems¶
PyPI rejects the upload¶
Possible causes:
the version already exists on PyPI;
the API token is invalid;
the package metadata is invalid;
the distribution files are malformed.
PyPI does not allow replacing an existing published version. If a version was uploaded incorrectly, publish a new version.
Documentation does not update¶
Check:
Read the Docs build status;
GitHub Actions workflow status;
.readthedocs.ymlconfiguration;Sphinx build warnings or errors;
whether the relevant branch or tag is active in Read the Docs.
Package is missing files¶
Check package configuration and manifest settings.
Verify that important files are included in the source distribution and wheel.
Common missing files include:
migrations;
management commands;
templates;
static files;
license;
README.
Version mismatch¶
Check that the version in pyproject.toml matches the intended release.
If documentation reads the package version from project metadata, rebuild the documentation after updating the version.