Merge branch 'main' into issue-1153-additional-vader-workers

Author: rieder

doc/developing/index.rst

@@ -7,4 +7,5 @@ Contents:
    :maxdepth: 2
 
    documenting
+   releasing
    design/index

doc/developing/releasing.rst

@@ -0,0 +1,103 @@
+.. _releasing:
+
+================
+Making a release
+================
+
+Every once in a while, we make a new release of AMUSE, when we feel that enough new
+features have accumulated or when important fixes have been made. AMUSE is quite mature
+by now, and uses a time-based versioning scheme with the `CalVer <https://calver.org/>`_
+pattern vYYYY.MM.MICRO.
+
+Making a release takes three steps: collecting changes, tagging the release, and making
+a release on GitHub.
+
+
+Collecting changes
+==================
+
+Every release should come with a description of changes, so that the users know what to
+expect. GitHub can make these automatically, but it's nice to check by hand to make sure
+nothing and in particular no one (contributor) goes missing.
+
+All the changes are in the git log, so this is a matter of running ``git log`` with your
+favourite options and making a list of changes and contributors.
+
+
+Tagging the release
+===================
+
+Each release needs to be tagged in git to make sure we know exactly which version of the
+software is being released, and so that the build system knows which version it's
+building and installing and can set the metadata correctly.
+
+Git knows two different kinds of tags, annotated tags and lightweight tags. Annotated
+tags are intended for releases, and because of the way our build system is set up, they
+*must* be used. Tagging the current main version of AMUSE is done using:
+
+.. code-block:: bash
+
+    git switch main
+    git pull
+    git tag -a -m 'Release v2025.9.0' v2025.9.0
+
+
+Or whatever the current year and month is. The third number should be used to
+distinguish multiple releases within a single month.
+
+The ``-a`` in the final command makes an annotated tag, ``-m`` adds a (required) message
+to it, and ``v2025.9.0`` is the name of the tag.
+
+Make sure that you follow exactly this pattern (with a ``v`` at the start and periods,
+not underscores or dashes), as the build system relies on it.
+
+If you run
+
+.. code-block:: bash
+
+    git cat-file -t v2025.9.0
+
+
+it should show ``tag``, not ``commit``.
+
+If the tag has been made correctly, then you can push it to GitHub using
+
+.. code-block:: bash
+
+    git push tag v2025.9.0
+
+
+Making a GitHub release
+=======================
+
+Finally, we will make a GitHub release, which adds the release to GitHub's Releases page
+with a nice description, causes GitHub to make a tar.gz archive available for the
+release, and archives the release on Zenodo.
+
+Go to `the AMUSE releases page <https://github.com/amusecode/amuse/releases>`_, and
+click "Draft a new release" at the top. Select the tag you just made, add a title for
+the release (generally just "v2025.9.0" or whatever the version is), and then click
+"Generate release notes".
+
+Check your list of changes and contributors from above against what GitHub generated,
+and edit as needed. Consider whether the release notes make sense from the perspective
+of a user of AMUSE; the developers already know what's going on. In particular, you may
+want to organise the changes a bit, starting with new user-visible features,
+user-visible fixes, then more technical improvements that don't affect the users' every
+day usage.
+
+Once you have something that will help the users quickly see what's new and whether they
+should upgrade, you can set the new release as the latest one, don't make it a
+pre-release (see below), and don't create a discussion, and when all is ready click
+"Publish release" to publish it.
+
+
+Pre-releases
+============
+
+Pre-releases can be a good way of inviting people to test some big changes, giving you a
+chance to fix any issues before making the final release. Pre-releases should be tagged
+as above, with a version of the form v2025.5.0.rc1 (rc stands for release candidate).
+Then a GitHub release can be made and marked as a pre-release.
+
+

doc/install/installing.rst

@@ -10,8 +10,8 @@ To install AMUSE, we need to
 (AMUSE can also be installed without Conda if needed, as described below, but we
 recommend using Conda.)
 
-If you have a Mac, then you should skip to :ref:`Setting up macOS`, and if you're
-running Linux then you can go straight to :ref:`Installing Conda`. For Windows, continue
+If you have a Mac, then you should skip to :ref:`setting_up_macOS`, and if you're
+running Linux then you can go straight to :ref:`installing_conda`. For Windows, continue
 here with installing WSL.
 
 Installing WSL
@@ -55,9 +55,10 @@ updates. We can then install them using this:
    sudo apt -y upgrade
 
 
-Now you can continue with :ref:`Installing Conda`, using the Ubuntu terminal window to
+Now you can continue with :ref:`installing_conda`, using the Ubuntu terminal window to
 enter the instructions.
 
+.. _setting_up_macOS:
 
 Setting up macOS
 ----------------
@@ -99,6 +100,7 @@ loaded, and then you're ready to install Conda.
 If you use Bash instead of zsh, then you'll need to edit ``.bashrc`` instead. When in
 doubt, you can safely edit both files to be sure.
 
+.. _installing_conda:
 
 Installing Conda
 ----------------
@@ -108,10 +110,9 @@ available. Conda is a package manager, a program with which you can install othe
 programs. It's very widely used in science and beyond, so having a working Conda setup
 is very useful also outside of the world of AMUSE.
 
-If you already have a working Conda setup, then you can continue to :ref:`Installing
-AMUSE`.
+If you already have a working Conda setup, then you can continue to :ref:`installing_amuse`.
 
-If you cannot or don't want to use Conda, see :ref:`Using a virtualenv` below.
+If you cannot or don't want to use Conda, see :ref:`using_a_virtualenv` below.
 
 If you do not yet have Conda, then you can install it using the following commands in
 the terminal. (Linux users can open one from the menu, Windows and macOS users will
@@ -135,6 +136,8 @@ Finally, close your terminal window and open a new one to make the ``conda`` com
 properly available.
 
 
+.. _installing_amuse:
+
 Installing AMUSE
 ----------------
 
@@ -145,22 +148,22 @@ command in your terminal to download it as above, for example:
 
 .. code-block:: bash
 
-   curl -L -O "https://github.com/amusecode/amuse/archive/refs/tags/v2025.5.0.tar.gz"
+   curl -L -O "https://github.com/amusecode/amuse/archive/refs/tags/v2025.9.0.tar.gz"
 
 
 This ``.tar.gz`` file needs to be unpacked first (you may need to change the version if
 you downloaded a newer one):
 
 .. code-block:: bash
 
-   tar xf v2025.5.0.tar.gz
+   tar xf v2025.9.0.tar.gz
 
 
 Then we can enter the directory with the AMUSE source code:
 
 .. code-block:: bash
 
-   cd amuse-2025.5.0
+   cd amuse-2025.9.0
 
 
 And then you can start the installer:
@@ -183,40 +186,6 @@ Slack <https://amusecode.slack.com>`_ or by `making an issue on
 GitHub <https://github.com/amusecode/amuse/issues/new/choose>`_.
 
 
-Installing from a Git repository
-````````````````````````````````
-
-If you plan to modify AMUSE or one of the codes in it, then you may want to install from
-a local git clone instead of from a tar file. This will take more disk space and more
-download time, so it shouldn't be the first option, but if you want to do it then you
-can. You'll need to gave `git` installed:
-
-.. code-block:: bash
-
-   git clone https://github.com/amusecode/amuse.git
-
-
-Then you can enter the source directory using:
-
-.. code-block:: bash
-
-   cd amuse
-
-
-Select a version to build (use either one of these, or whichever version is relevant):
-
-.. code-block:: bash
-
-   git switch main                          # current development version
-   git checkout checkout v2025.5.0          # tagged release
-
-And now you can start the installer as before:
-
-.. code-block:: bash
-
-   ./setup
-
-
 Additional packages
 ```````````````````
 
@@ -268,17 +237,89 @@ and then you can run it as before using
 
 
 You should now have a working AMUSE setup. To start
-using it, see :ref:`Getting started with AMUSE` or the :ref:`Interactive tutorial`
+using it, see :ref:`getting_started_with_amuse` or the :ref:`interactive_tutorial`
+
+
+Debugging conda package installation
+````````````````````````````````````
+
+If you encounter problems with installing packages using ``conda``, or AMUSE doesn't
+compile correctly, then you should check that you are using the ``conda-forge`` channel
+rather than something else.
+
+Conda can use different sources of packages, which it calls channels. Different channels
+contain software packaged by different people, and packages from different channels are
+often incompatible. If you type
+
+.. code-block:: bash
+
+    conda list
+
+
+then you should see a list of packages that are installed in the active environment, and
+which channel they came from. Ideally, all of them have ``conda-forge`` as the channel.
+
+If not, then you can reinstall the package from ``conda-forge`` and see if that improves
+the situation.
+
+To reinstall a package from ``conda-forge``, use
+
+.. code-block:: bash
+
+    conda install -c conda-forge <package name>
+
+
+If you want to combine AMUSE with another package that isn't available from conda-forge,
+then you may have to install that from another channel, and hope that things work. Or
+ask the maintainers of that package to add it to conda-forge and be a bit more
+compatible with the rest of the world.
 
 
 Alternative installation options
 ================================
 
 The above instructions are the easiest way to install AMUSE, and they should work for
 almost everyone wanting to use AMUSE to do astrophysics. Nevertheless, there may be
-cases where you need a different setup, for example because you cannot use Conda.  In
+cases where you need a different setup, for example because you cannot use Conda. In
 that case, you'll want one of these alternative installations.
 
+.. _installing_from_git:
+
+Installing from a Git repository
+--------------------------------
+
+If you plan to modify AMUSE or one of the codes in it, then you may want to install from
+a local git clone instead of from a tar file. This will take more disk space and more
+download time, so it shouldn't be the first option, but if you want to do it then you
+can. You'll need to gave `git` installed:
+
+.. code-block:: bash
+
+   git clone https://github.com/amusecode/amuse.git
+
+
+Then you can enter the source directory using:
+
+.. code-block:: bash
+
+   cd amuse
+
+
+Select a version to build (use either one of these, or whichever version is relevant):
+
+.. code-block:: bash
+
+   git switch main                          # current development version
+   git checkout checkout v2025.9.0          # tagged release
+
+And now you can start the installer as before:
+
+.. code-block:: bash
+
+   ./setup
+
+
+.. _using_a_virtualenv:
 
 Using a virtualenv
 ------------------

doc/interactive_tutorial/index.rst

@@ -1,3 +1,5 @@
+.. _interactive_tutorial:
+
 Interactive tutorial
 ====================