From b0506a722efbc9d94fb8673235af3a18984b2217 Mon Sep 17 00:00:00 2001 From: Todd Gamblin Date: Tue, 7 Jul 2020 11:44:15 -0700 Subject: releases: document `releases/latest` tag (#17402) We got rid of `master` after #17377, but users still want a way to get the latest stable release without knowing its number. We've added a `releases/latest` tag to replace what was once `master`. Co-authored-by: Massimiliano Culpo --- README.md | 2 + lib/spack/docs/developer_guide.rst | 91 ++++++++++++++++++++++++-------------- 2 files changed, 61 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 2ab9d2dfdf..1cafb5c963 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,8 @@ change the way Spack concretizes dependencies within a release branch. So, you can base your Spack deployment on a release branch and `git pull` to get fixes, without the package churn that comes with `develop`. +The latest release is always available with the `releases/latest` tag. + See the [docs on releases](https://spack.readthedocs.io/en/latest/developer_guide.html#releases) for more details. diff --git a/lib/spack/docs/developer_guide.rst b/lib/spack/docs/developer_guide.rst index 5c57f28226..5e905c3d1b 100644 --- a/lib/spack/docs/developer_guide.rst +++ b/lib/spack/docs/developer_guide.rst @@ -557,8 +557,10 @@ packages. They should generally only contain fixes to the Spack core. Both major and minor releases are tagged. After each release, we merge the release branch back into ``develop`` so that the version bump and any -other release-specific changes are visible in the mainline (see -:ref:`merging-releases-to-develop`). +other release-specific changes are visible in the mainline. As a +convenience, we also tag the latest release as ``releases/latest``, +so that users can easily check it out to get the latest +stable version. See :ref:`merging-releases` for more details. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -641,7 +643,7 @@ for a major release, the steps to make the release are as follows: #. Follow the steps in :ref:`publishing-releases`. -#. Follow the steps in :ref:`merging-releases-to-develop`. +#. Follow the steps in :ref:`merging-releases`. #. Follow the steps in :ref:`announcing-releases`. @@ -744,7 +746,7 @@ release: #. Follow the steps in :ref:`publishing-releases`. -#. Follow the steps in :ref:`merging-releases-to-develop`. +#. Follow the steps in :ref:`merging-releases`. #. Follow the steps in :ref:`announcing-releases`. @@ -794,45 +796,70 @@ Publishing a release on GitHub for ``download_count`` to see this. -.. _merging-releases-to-develop: +.. _merging-releases: -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Merging back into ``develop`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Updating `develop` and `releases/latest` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Once each release is complete, make sure that it is merged back into -``develop`` with a merge commit: +We merge each release into ``develop``, we tag the latest release as +``releases/latest``. -.. code-block:: console +#. Once each release is complete, make sure that it is merged back into + ``develop`` with a merge commit: + + .. code-block:: console - $ git checkout develop - $ git merge --no-ff releases/v0.15 - $ git push + $ git checkout develop + $ git merge --no-ff releases/vX.Y # vX.Y is the new release's branch + $ git push -We merge back to ``develop`` because it: + We merge back to ``develop`` because it: - * updates the version and ``CHANGELOG.md`` on ``develop``. - * ensures that your release tag is reachable from the head of - ``develop`` + * updates the version and ``CHANGELOG.md`` on ``develop``. + * ensures that your release tag is reachable from the head of + ``develop`` -We *must* use a real merge commit (via the ``--no-ff`` option) because it -ensures that the release tag is reachable from the tip of ``develop``. -This is necessary for ``spack -V`` to work properly -- it uses ``git -describe --tags`` to find the last reachable tag in the repository and -reports how far we are from it. For example: + We *must* use a real merge commit (via the ``--no-ff`` option) because it + ensures that the release tag is reachable from the tip of ``develop``. + This is necessary for ``spack -V`` to work properly -- it uses ``git + describe --tags`` to find the last reachable tag in the repository and + reports how far we are from it. For example: -.. code-block:: console + .. code-block:: console + + $ spack -V + 0.14.2-1486-b80d5e74e5 + + This says that we are at commit ``b80d5e74e5``, which is 1,486 commits + ahead of the ``0.14.2`` release. - $ spack -V - 0.14.2-1486-b80d5e74e5 + We put this step last in the process because it's best to do it only once + the release is complete and tagged. If you do it before you've tagged the + release and later decide you want to tag some later commit, you'll need + to merge again. + +#. If the new release is the **highest** Spack release yet, you should + also tag it as ``releases/latest``. For example, suppose the highest + release is currently ``0.15.3``: + + * If you are releasing ``0.15.4`` or ``0.16.0``, then you should tag + it with ``releases/latest``, as these are higher than ``0.15.3``. + + * If you are making a new release of an **older** major version of + Spack, e.g. ``0.14.4``, then you should not tag it as + ``releases/latest`` (as there are newer major versions). + + To tag ``releases/latest``, do this: + + .. code-block:: console -This says that we are at commit ``b80d5e74e5``, which is 1,486 commits -ahead of the ``0.14.2`` release. + $ git checkout releases/vX.Y # vX.Y is the new release's branch + $ git tag --force releases/latest + $ git push --tags -We put this step last in the process because it's best to do it only once -the release is complete and tagged. If you do it before you've tagged the -release and later decide you want to tag some later commit, you'll need -to merge again. + The ``--force`` argument makes ``git`` overwrite the existing + ``releases/latest`` tag with the new one. .. _announcing-releases: -- cgit v1.2.3-60-g2f50