RELEASING

Release Checklist
-----------------------------------------
[ ] Update classifiers in pyproject.toml to include the latest supported Python
    versions.
[ ] Update NEWS with list of changes:
    [ ] Invoke `tox -e news -- --version <NEXT_VERSION>`
    [ ] Make sure that only `template.rst` remains in changelog.d/
    [ ] Manually clean up the new NEWS file.
    [ ] Replace entries in the "Misc" section that are not likely to be
        interesting to anyone consuming the package (e.g. changes to CI) with
        a reference to the Github PR.
[ ] Commit the changes in git and make a pull request.
[ ] Follow the "Releasing" steps below


Optional:
----------
[ ] Check that README.rst is up-to-date.
[ ] Check that the documentation builds correctly (cd docs, make html)


Versioning
----------
Try and keep to a semantic versioning scheme (http://semver.org/). The versions
are managed with `hatch-vcs` (using `setuptools-scm`), so to update the
version, simply tag the relevant commit with the new version number.


Instructions
-----------------------------------------
See the instructions at https://packaging.python.org/en/latest/distributing/
for more details.


Building and Releasing
----------------------
Releasing is automated via the `publish.yml` GitHub Actions workflow. When a
new tag is pushed to the repository, or the publish action is triggered
manually (see
https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow
for more details), the project is automatically built and uploaded to Test
PyPI. When a GitHub release is created, the result is uploaded to PyPI.

Before publication, the full test suite is run on all platforms against the
official release artifacts (both sdist and wheel). If this fails the artifacts
will not be uploaded. In the event of a transient failure, rerunning all failed
jobs should trigger the publication without needing to make a release.

Uploads use PyPI's trusted publishing, so no API tokens are needed. The
trusted publisher for both PyPI and Test PyPI is configured with the workflow
name `publish.yml` and the environment name `release`, which is the GitHub
environment the upload job runs in.

To make a release:

1. After having made a PR with all the relevant changes, trigger the "Upload
   package" to trigger an upload to Test PyPI. If desired, you can push a
   `.dev0` or `.rc0` tag first, so that all uploads will have a prefix for the
   *next* version rather than the previous version (e.g. if you are releasing
   `3.1.2`, without making a new tag releases will have a version like
   `3.1.1+gff8893e.d20220603`; if you push a `3.1.2.dev0` tag first, the version
   number will be `3.1.2.dev0`, and subsequent commits will be things like
   `3.1.2.dev0+fe9dacc4.d20220603`).

2. Check the Test PyPI page for `python-dateutil` to ensure that the dev release
   worked correctly: https://test.pypi.org/project/python-dateutil/

   Dev releases may not appear as the default page, so click "Release history"
   and navigate to the release you are trying to check. Make sure that the
   metadata looks right and in particular that the `Requires` metadata is
   present.

4. If the release failed or was unsatisfactory in some way, make the required
   changes and got back to step 1. Pushing a new tag is not necessary.

5. When everything looks good, merge the release PR, pull the result to your
   local branch and create a new tag with a non-dev version number,
   e.g. `3.1.2`. Push this to the repository, wait for the Test PyPI run to
   trigger, and ensure that the upload worked.

6. Create a new GitHub release with the new entries from `NEWS` in the
   description. This will trigger the workflow to build and release the final
   version to PyPI.org. Check https://pypi.org/project/python-dateutil to
   ensure that everything worked correctly.

7. Delete any dev tags created during the testing process from your upstream
   and local branches.