From 975561c4a686246ce0f2eecafb13312c2d1a2447 Mon Sep 17 00:00:00 2001 From: Minijackson Date: Fri, 13 Dec 2024 11:31:09 +0100 Subject: [PATCH] docs: document the EPNix release process --- docs/development/guides/index.rst | 13 ++ docs/development/guides/release-process.rst | 164 ++++++++++++++++++++ docs/index.rst | 9 ++ 3 files changed, 186 insertions(+) create mode 100644 docs/development/guides/index.rst create mode 100644 docs/development/guides/release-process.rst diff --git a/docs/development/guides/index.rst b/docs/development/guides/index.rst new file mode 100644 index 0000000..7249fb5 --- /dev/null +++ b/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 diff --git a/docs/development/guides/release-process.rst b/docs/development/guides/release-process.rst new file mode 100644 index 0000000..8c0d737 --- /dev/null +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index b21dc46..6c82428 100644 --- a/docs/index.rst +++ b/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