Unverified Commit b0506a72 authored by Todd Gamblin's avatar Todd Gamblin Committed by GitHub
Browse files

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: default avatarMassimiliano Culpo <massimiliano.culpo@gmail.com>
parent 650ab563
......@@ -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.
......
......@@ -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:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment