Maintainers’ documentation¶
How to release¶
The contents of this section is a detailed version of the “release” part of the .github/PULL_REQUEST_TEMPLATE.md
file.
Requirements¶
You can use a dedicated virtualenv, or install the following in your userspace, but these should be available in your $PATH
:
- Python3 (any version)
- twine
Pre-release¶
- Create a branch with an adequate name, such as
release/x.y.z
. - Edit the
formidable/__init__.py
source file and change the value offormidable.version
to the appropriate version number. - Amend the
CHANGELOG.rst
file to reflect your change. Put there the version number, the date, and do not hesitate to re-arrange its content if needed (e.g.: put sub-sections in the release notes). - If the version deprecates one or more feature(s) check the docs
deprecations.rst
file and change it if necessary. - Check if you have to edit other files and change them accordingly (e.g.: README).
Commit¶
Once your content is ready, commit it:
git commit -am "Release x.y.z"
If you want, you can also make a more detailed commit message, by copying/pasting the contents of the Changelog.
Push¶
Push your branch on Github and wait for the CI to return green.
You can also start to create your Pull-Request at this point, and check if you are at the correct step in the “Release” checklist.
Attention
When to tag?
If you are very confident, you can tag here. But we’d recommend to wait to be sure that you have everything sorted out.
Back to development¶
- Edit the
CHANGELOG.rst
file to add a “master (unreleased)” section, with a dummy log item, such as “Nothing to see here yet”. - Edit the
formidable/__init__.py
source file and put a non-release version number, such asx.y+1.0.dev0
. - Commit this change with, for example, the following command:
git commit -a -m "Back to dev => x.y+1.0.dev0"
Again, push the branch and wait for the tests to be green.
At this point, the pull-request should be ready for review.
Release¶
If the CI has returned a successful result, and your peers have reviewed your PR, you’re ready to proceed with the release.
Tag the right commit¶
You should have two commits in your log corresponding to your latest changes:
$ git log --pretty=format:'%h %ad | %s' --date=short -n 2
8fd30ec 2021-04-29 | Back to dev => x.y+1.0.dev0
5b65073 2021-04-29 | Release x.y.0
Checkout to the “Release” commit and tag it.
$ git checkout 5b65073
$ git tag x.y.0
This tag can be pushed to Github with:
$ git push --tags
Generate files¶
Now you can generate the files using the following command at the root of the project:
$ python3 setup.py sdist bdist_wheel
This should produce two files:
dist/django-formidable-x.y.0.tar.gz
dist/django_formidable-x.y.0-py3-none-any.whl
Merge the Pull Request¶
Merge from Github, or, if you dislike merge commits, type the following commands from your local copy:
$ git checkout master
$ git merge --ff release/x.y.z
$ git push
Upload to PyPI¶
In order to upload to PyPI, you should have an account and have at least the maintainer or owner role for this project and have your .pypirc
correctly configured to upload files (i.e. have the pypi repository as default and correct credentials, using your password or a project token).
Using twine
you may now upload the two files previously generated:
twine upload dist/django-formidable-x.y.0.tar.gz dist/django_formidable-x.y.0-py3-none-any.whl
You can then go to https://pypi.org/project/django-formidable/ to check the latest version.
Hint
Due to asynchronous tasks and cache invalidation, the latest version may not appear immediately. Be patient.
Post-release¶
There are a few cleanup tasks, such as:
- Delete the release branch,
- Edit the Release page on Github to reflect the changelog,
- Eventually make some feedback on the issues impacted by the new release,
- Enjoy & celebrate!