..
   set tw: 72

==========================
How To: Make a new release
==========================

This howto uses version number "1.5.1" throughout as an example. Remember to
edit all copy-pastes that have "1.5.1" in them to the correct version number!

Choosing a version number
-------------------------

While we use `SemVer <https://semver.org/>`_, SemVer is open to interpretation
so here is ours.

Increase the middle digit every time when

* there is a change in the database schema that necessitates a migration
  on the production SQL server. (Django also has migrations that do *not*
  necessitate this.)
* there is a change that automatically rewrites the data in the database (aka
  a "data migration")
* there is a change in the REST API that cannot be ignored by clients
  (especially *removed* attributes)
* there is a wonderful new feature that needs to be highlighted
* the deployer needs to do extra steps, like ensuring that a new
  dependency is installed
* there is a bugfix that necessitates some hands-on action from the deployer

Increase the final digit when

* changing documentation
* changing something in CI/CD like updating CI/CD specific dependencies
* adding a bugfix that nobody should notice

Releases that only change the final digit should *never* be mentioned
in :file:`NOTES.md`.

We plan to increase the first digit when dropping a REST API version. We have
not needed to do this yet.

.. attention::

   It should not be necessary to do any of this in a virtualenv. If one is needed,
   file a bug. Dependencies are: ``python``, ``git``, ``tar``, something that
   can list the contents of a zip file, something that can build a python
   package (we use ``build`` as an example), and something that can upload
   a package to PyPI (here we use ``twine`` as an example.)

Checklist
---------

.. tip::

   It is a good idea to do this in a fresh copy of the repo. Then several of
   the more paranoid steps below will be less necessary.

#. Ensure you're on the correct branch to be released. Either ``main`` or
   newest stable, which has a name of the form ``stable/1.5.x``. Release from
   the stable branch only under exceptional circumstances. For instance:
   there's a critical bugfix for production and there's a lot of new stuff on
   main that is not ready to go.

#. Check that there are no files that have not been commited:

    .. code:: console

        $ git status

#. Stash away all files git does not know about:

    .. code:: console

        $ git stash -u

#. Generate the tailwind CSS:

    .. code:: console

        $ make setup-tailwind-standalone

#. Run the tests one last time:

    .. code:: console

        $ tox

#. Check that :file:`CHANGELOG.md` and :file:`NOTES.md` are up to snuff. We use
   `towncrier <https://towncrier.readthedocs.io>`_ to add to the changelog from the
   files in :file:`changelog.d/`.

   Run :code:`towncrier build --version 1.5.1`. This will update
   :file:`CHANGELOG.md` and delete everything in :file:`changelog.d/`.

   To preview what the addition to the changelog file would look like you can add the
   flag ``--draft``. This will not delete the files or update :file:`CHANGELOG.md`.
   It will only output the preview in the terminal.

   If you want manually set the date that is added to the changelog you can use the
   flag ``--date DATE``. Otherwise it will be today.

   Read the new entry in :file:`CHANGELOG.md` and adjust it as necessary for
   better language. Reorder as per the order the commits/pull-requests were
   commited, newest on top. That makes it easier to compare with the ``git log``
   for maximum detail.

   Copy steps that a deployer needs to do to :file:`NOTES.md`, feel free to add
   more detail.

   Use ``git add -u`` to ensure the changes to :file:`changelog.d/` are
   included. Make one standalone commit for this step.

#. Check that HEAD is the commit we want to tag with the new version:

    .. code:: console

        $ git log --oneline  --decorate HEAD~5..HEAD

   This is preferably the commit that adjusted the changelog and notes.

#. Tag the correct commit with an annotated tag. The format of the tag itself
   is ``vX.Y.Z`` where X, Y and Z are integers. Don't forget the ``v``. The
   annotation should be a very brief summary of the most important changes. The
   annotation need not be unique, there just must be *something* to make the
   tag annotated.

    .. code:: console

        $ git tag -m 'Post release bugfixes' v1.5.1

#. Push the tag and changelog commit (given that ``origin`` is the correct
   remote):

    .. code:: console

        $ git push origin

   Note: we bypass pull-requests here.

#. Create a wheel and source tarball:

    .. code:: console

        $ python -m build

   This will create a wheel in the :file:`dist/` directory.

   (You can install ``build`` locally for your user with :command:`pipx` and
   run :command:`pyproject-build` instead, it'll do the same thing.)

#. Do a quick manual check of the contents of the wheel: Check that the
   correct version is in the filename (if not, you might have forgotten
   to tag, or the git index is dirty):

    .. code:: console

        $ ls dist/

   Then check the contents. For a wheel (``.whl``), use any tool that can
   analyze a zip-file, for instance ``zipinfo``:

    .. code:: console

        $ zipinfo dist/FILENAME.wheel

   For a tarball:

    .. code:: console

        $ tar tzf dist/FILENAME.tar.gz

   Check that no unwanted files are included, like editor swap files, ``.pyc``
   files, or ``__pycache__`` directories. Also check that the following
   build-artifacts are included:

   - src/argus/version.py
   - src/argus/htmx/static/styles.css
   - src/argus/htmx/tailwindtheme/styles.css
   - src/argus/htmx/tailwindtheme/tailwind.css
   - src/argus/htmx/tailwindtheme/custom-themes/\*.css

   Note that the last directory SHOULD always have a ``README.md`` file, but
   will only have css files if adding extra themes or overriding existing
   themes in a branded package. For upstream, there should generally be none.

#. Upload the wheel at `PyPI <https://pypi.org/>`_, for instance with
   `twine <https://twine.readthedocs.io/>`_:

    .. code:: console

        $ twine upload dist/*.whl

   Use your own user if you've been given access or ask for a token for
   the team-user, see also :file:`~/.pypirc`.

#. Unstash any files git does not know about, development can continue:

    .. code:: console

        $ git stash pop

#. Turn the tag into a release on Github:

   #. On the "Code" tab, find the column to the right of the list of
      files and scroll until you find "Releases". Click on
      "Releases".

   #. To the right, find the button "Draft new release". Click.

   #. Type in the tag in the box that says "Tag version" left of the
      '@', in order to select the tag.

   #. Copy the tag and date from the changelog to where it says "Release
      title".

   #. Copy the changelog into the box below, dedent the headers once.

   #. Finally, click the "Publish release"-button. Done!