docs: document the EPNix release process

docs/development/guides/index.rst

@@ -0,0 +1,13 @@
+Guides
+======
+
+`How-to guides`_ for EPNix developers.
+
+.. _How-to guides: https://diataxis.fr/how-to-guides/
+
+----
+
+.. toctree::
+   :maxdepth: 1
+
+   release-process

docs/development/guides/release-process.rst

@@ -0,0 +1,164 @@
+Release process
+===============
+
+This document provides instructions
+on how to make a new EPNix release.
+
+EPNix releases are tied to Nixpkgs_ versions,
+so one should be made for each Nixpkgs release.
+
+.. _Nixpkgs: https://github.com/NixOS/nixpkgs
+
+Read the release notes
+----------------------
+
+Check the `NixOS release notes`_,
+and take note of each change that might affect EPNix.
+
+.. _NixOS release notes: https://nixos.org/manual/nixos/stable/release-notes
+
+Upgrade Nixpkgs
+---------------
+
+Search for the old release version,
+for example ``nixos-23.05``,
+and make sure to replace with the newer version,
+when appropriate.
+
+You should find at least:
+
+- the ``nixpkgs`` flake input in :file:`flake.nix`
+- the ``epnix`` flake input in :file:`templates/top/flake.nix`
+- workflows in :file:`.github/workflows/`
+- documentation code examples
+
+Once done,
+run ``nix flake lock``,
+and create a commit with these changes.
+
+The commit message should be:
+:samp:`flake: upgrade NixOS {old.version} -> {new.version}`.
+
+Update Maven hashes
+-------------------
+
+Maven hashes might depend on the Java or Maven version used,
+so a major Nixpkgs upgrade might cause those hashes to change.
+
+Build the packages that have Maven hashes in them:
+
+.. code-block:: bash
+
+   nix build -L \
+     '.#channel-finder-service' \
+     '.#phoebus-olog' \
+     '.#phoebus-deps'
+
+And update the hashes accordingly,
+if needed.
+
+Create a separate commit for each hash update.
+
+Apply breaking changes
+----------------------
+
+If there are breaking changes in the Nixpkgs release notes,
+apply them when appropriate,
+both in the code
+and in the documentation.
+
+.. admonition:: Example
+
+   If the way MySQL is configured has changed,
+   reflect those changes in the Archiver Appliance module implementation.
+
+.. admonition:: Example
+
+   If the way Elasticsearch is configured has changed,
+   reflect those changes in the documentation,
+   in the Phoebus services guides.
+
+Create a commit for each breaking change.
+
+Document breaking changes
+-------------------------
+
+If some breaking changes in Nixpkgs or EPNix affect users,
+document them in the release notes,
+in :file:`docs/release-notes/{newversion}.rst`.
+
+.. admonition:: Example
+
+   If the way Elasticsearch is configured has changed,
+   add instructions on how to migrate to the new configuration format
+   in the release notes.
+
+Fix comments
+------------
+
+If there are "TODOs" in the code base that mention the new release,
+see if they can be solved.
+
+For example,
+if there's a comment :samp:`TODO: remove for NixOS {new.version}`,
+remove the comment
+and related code block.
+
+Create a commit for each resolved TODO.
+
+Run the tests
+-------------
+
+Run the EPNix checks.
+This can be done by pushing your branch to DRF's GitLab,
+and waiting for the CI to complete.
+
+If you don't have access to DRF's GitLab,
+run ``nix flake check -L``.
+
+.. caution::
+
+   Running all EPNix checks can take a lot of resources.
+
+If there are issues with some tests,
+fix them,
+and add a commit for each fix.
+
+Open a pull request
+-------------------
+
+Once you've verified that the new version is working,
+open a Pull Request on GitHub.
+
+Create the new release branch
+-----------------------------
+
+Once your Pull Request is merged,
+and you've integrated all changes you want for the new release,
+go into GitHub's `branches view`_,
+and create a new :samp:`nixos-{new.version}` branch on master.
+
+.. _branches view: https://github.com/epics-extensions/EPNix/branches
+
+Update the documentation release name
+-------------------------------------
+
+Create a new commit
+on the new :samp:`nixos-{new.version}` branch,
+and update the ``release`` variable in :file:`docs/conf.py`,
+so that it is :samp:`nixos-{new.version}`.
+
+.. admonition:: Example
+
+   .. code-block:: python
+      :caption: :file:`docs/conf.py`
+      :emphasize-lines: 5
+
+      project = "EPNix"
+      copyright = "The EPNix Contributors"
+      author = "The EPNix Contributors"
+      release = "dev"
+      release = "nixos-24.05"
+
+Open a Pull Request with that commit,
+targeting the :samp:`nixos-{new.version}` branch.

docs/index.rst

@@ -108,4 +108,13 @@ This documentation follows the `Diátaxis`_ documentation framework.
 
    release-notes/*
 
+.. toctree::
+   :caption: EPNix development
+   :hidden:
+   :titlesonly:
+   :glob:
+   :reversed:
+
+   development/guides/index
+
 .. TODO: link an index to Nix options and packages