|
| 1 | +.. _releasing: |
| 2 | + |
| 3 | +================ |
| 4 | +Making a release |
| 5 | +================ |
| 6 | + |
| 7 | +Every once in a while, we make a new release of AMUSE, when we feel that enough new |
| 8 | +features have accumulated or when important fixes have been made. AMUSE is quite mature |
| 9 | +by now, and uses a time-based versioning scheme with the `CalVer <https://calver.org/>`_ |
| 10 | +pattern vYYYY.MM.MICRO. |
| 11 | + |
| 12 | +Making a release takes three steps: collecting changes, tagging the release, and making |
| 13 | +a release on GitHub. |
| 14 | + |
| 15 | + |
| 16 | +Collecting changes |
| 17 | +================== |
| 18 | + |
| 19 | +Every release should come with a description of changes, so that the users know what to |
| 20 | +expect. GitHub can make these automatically, but it's nice to check by hand to make sure |
| 21 | +nothing and in particular no one (contributor) goes missing. |
| 22 | + |
| 23 | +All the changes are in the git log, so this is a matter of running ``git log`` with your |
| 24 | +favourite options and making a list of changes and contributors. |
| 25 | + |
| 26 | + |
| 27 | +Tagging the release |
| 28 | +=================== |
| 29 | + |
| 30 | +Each release needs to be tagged in git to make sure we know exactly which version of the |
| 31 | +software is being released, and so that the build system knows which version it's |
| 32 | +building and installing and can set the metadata correctly. |
| 33 | + |
| 34 | +Git knows two different kinds of tags, annotated tags and lightweight tags. Annotated |
| 35 | +tags are intended for releases, and because of the way our build system is set up, they |
| 36 | +*must* be used. Tagging the current main version of AMUSE is done using: |
| 37 | + |
| 38 | +.. code-block:: bash |
| 39 | +
|
| 40 | + git switch main |
| 41 | + git pull |
| 42 | + git tag -a -m 'Release v2025.9.0' v2025.9.0 |
| 43 | +
|
| 44 | +
|
| 45 | +Or whatever the current year and month is. The third number should be used to |
| 46 | +distinguish multiple releases within a single month. |
| 47 | + |
| 48 | +The ``-a`` in the final command makes an annotated tag, ``-m`` adds a (required) message |
| 49 | +to it, and ``v2025.9.0`` is the name of the tag. |
| 50 | + |
| 51 | +Make sure that you follow exactly this pattern (with a ``v`` at the start and periods, |
| 52 | +not underscores or dashes), as the build system relies on it. |
| 53 | + |
| 54 | +If you run |
| 55 | + |
| 56 | +.. code-block:: bash |
| 57 | +
|
| 58 | + git cat-file -t v2025.9.0 |
| 59 | +
|
| 60 | +
|
| 61 | +it should show ``tag``, not ``commit``. |
| 62 | + |
| 63 | +If the tag has been made correctly, then you can push it to GitHub using |
| 64 | + |
| 65 | +.. code-block:: bash |
| 66 | +
|
| 67 | + git push tag v2025.9.0 |
| 68 | +
|
| 69 | +
|
| 70 | +Making a GitHub release |
| 71 | +======================= |
| 72 | + |
| 73 | +Finally, we will make a GitHub release, which adds the release to GitHub's Releases page |
| 74 | +with a nice description, causes GitHub to make a tar.gz archive available for the |
| 75 | +release, and archives the release on Zenodo. |
| 76 | + |
| 77 | +Go to `the AMUSE releases page <https://github.com/amusecode/amuse/releases>`_, and |
| 78 | +click "Draft a new release" at the top. Select the tag you just made, add a title for |
| 79 | +the release (generally just "v2025.9.0" or whatever the version is), and then click |
| 80 | +"Generate release notes". |
| 81 | + |
| 82 | +Check your list of changes and contributors from above against what GitHub generated, |
| 83 | +and edit as needed. Consider whether the release notes make sense from the perspective |
| 84 | +of a user of AMUSE; the developers already know what's going on. In particular, you may |
| 85 | +want to organise the changes a bit, starting with new user-visible features, |
| 86 | +user-visible fixes, then more technical improvements that don't affect the users' every |
| 87 | +day usage. |
| 88 | + |
| 89 | +Once you have something that will help the users quickly see what's new and whether they |
| 90 | +should upgrade, you can set the new release as the latest one, don't make it a |
| 91 | +pre-release (see below), and don't create a discussion, and when all is ready click |
| 92 | +"Publish release" to publish it. |
| 93 | + |
| 94 | + |
| 95 | +Pre-releases |
| 96 | +============ |
| 97 | + |
| 98 | +Pre-releases can be a good way of inviting people to test some big changes, giving you a |
| 99 | +chance to fix any issues before making the final release. Pre-releases should be tagged |
| 100 | +as above, with a version of the form v2025.5.0.rc1 (rc stands for release candidate). |
| 101 | +Then a GitHub release can be made and marked as a pre-release. |
| 102 | + |
| 103 | + |
0 commit comments