Merge pull request #2497 from jwrober/docs/release-update

Update release process based on findings from 3.0 to 3.1

docs/Contributing/release.rst

@@ -21,50 +21,73 @@ These are the general steps to prepare and finalize a release:
    The easiest way to do this is to copy the contents of the last release, delete the bullet points, and
    add a single bullet of ``* Nothing for this release`` to each section. :strong:`DO NOT` add a tag at this
    time. This prevents an accidental release.
+
 #. A release manager will update the draft as PR's are committed to the repository to help keep track of
    the release cadence progress. As PR's are added to sections the ``* Nothing for this release`` is removed.
+
 #. As PR's are added to the draft release notes, pay attention to the contributor. If a new contributor has
    opened a PR, call it out --- "With this release we welcome @[GithubID] as a new contributor (#[PR])"
+
 #. Multiple PR's can be combined on a single bullet line. Documentation updates are often done this way.
+
 #. When we are getting close to crossing one of the release candidate thresholds, the release manager will
    post to the ``#releases-project`` channel in the ``LT.DEV`` section on the Longturn Discord server. The
    main purpose of the post is to alert the developers of a pending cadence threshold and to gauge if we
    need to delay in any way or if we are good to proceed as normal.
+
 #. A release manager or another regular contributor will update the ``vcpkgGitCommitId`` value in the CI/CD
    build file (:file:`.github/workflows/build.yaml`). Grab the Commit ID of the most recent release from
    https://github.com/microsoft/vcpkg/releases. Commit and push a PR. Ensure all of the CI/CD Action runners
    complete successfully.
-#. If the new release is a change from ``alpha`` to ``beta`` or ``release candidate`` series, the
-   :file:`.github/workflows/release.yaml` file needs an update. In the ``snapcraft`` section, change the
-   ``release`` flag -- ``edge`` for Alpha, ``beta`` for Beta and ``candidate`` for the RC's.
+
+#. If the new release is a change from the ``dev``, ``alpha``, ``beta``, ``candidate``, or ``stable`` release
+   series, there are some file updates needed:
+
+   * :file:`.github/workflows/release.yaml` --- In the ``snapcraft`` section, change the ``release`` flag:
+     ``edge`` for Dev or Alpha, ``beta`` for Beta, ``candidate`` for the RCs, and ``stable`` for Stable.
+
+   * :file:`dist/*.metainfo.xml.in` --- At the bottom in the ``releases`` section, change the ``type`` value.
+     Use ``development`` for Dev, Alpha and Beta, ``candidate`` for the RCs, and ``stable`` for Stable.
+
 #. When it is time, the release manager will finalize the release notes and ask for an editorial review in the
    ``#releases-project`` channel. Updates are made as per review.
+
 #. If the release will be the :strong:`first release candidate` towards a stable release, the release manager
    will:
 
-   #. Delete the existing ``stable`` branch on Github's
+   #. Tag the ``stable`` branch at ``HEAD`` with a ``-final`` tag for the old stable release.
+
+   #. Remove branch protections from the ``stable`` branch in the repository settings.
+
+   #. Delete the existing ``stable`` branch on the repository's
       `branches page <https://github.com/longturn/freeciv21/branches>`_.
+
    #. From the same page, create a new ``stable`` branch from ``master``.
-   #. Update :file:`cmake/AutoRevision.txt` with the hash of the last commit in ``master`` and
-      ``v[major version].[minor version]-dev.0`` with the version of the :strong:`next stable release`, then
-      open a PR for this change to ``master``. This way, development builds from ``master`` will immediately
-      use the version number of the next stable.
-   #. Update :file:`.github/workflows/release.yaml`. In the ``snapcraft`` section, change the ``release``
-      flag to ``stable``.
+
+   #. Restore the ``stable`` branch protection setting.
+
+   #. Update :file:`cmake/AutoRevision.txt` with the hash of the last commit in ``master`` and set a
+      development version (``v[major version].[minor version]-dev.0``). Open a PR for this change to
+      ``master``. This way, development builds from ``master`` will immediately use the version number of the
+      next stable until we release a new unstable release.
 
 #. If the release is a :strong:`release candidate` for a :strong:`stable release`, the release manager will
    make sure that the :guilabel:`Target` branch in the release draft is set to ``stable``.
+
 #. The release manager will add a tag to the release notes page and then click :guilabel:`Publish Release`.
-   The format of the tag is ``v[major version].[minor version]-[pre-release name].[number]`` for pre-releases
-   and ``v[major version].[minor version].[patch version]`` for stable versions. For example:
-   ``v3.0-beta.6`` or ``v3.1.0``. :strong:`The format is very important` to the build configuration process.
+   The format of the tag is ``v[major version].[minor version]-[release name].[number]``. For example:
+   ``v3.0-patch.5`` or ``v3.1-rc.1``. :strong:`The format is very important` to the build configuration
+   process.
+
 #. After a few minutes the continuous integration (CI) will open a PR titled
    ``Release Update of AutoRevision.txt``. The release manager will open the PR, click on the
    :guilabel:`Close pull request` button, and then click :guilabel:`Open pull request` button. This is a
    necessary step to handle a GitHub security feature. GitHub requires a human to be involved to merge CI
-   created PR's.
+   created PRs.
+
 #. While inside the ``Release Update of AutoRevision.txt`` PR, the release manager will enable an automatic
    rebase and merge.
+
 #. The release manager will open an issue titled ``Review workarounds after <version> release`` with the
    following text:
 
@@ -73,13 +96,10 @@ These are the general steps to prepare and finalize a release:
 
 #. When all the CI actions are complete, the release manager will make a post in the ``#news-channel`` on the
    Longturn.net Discord server.
-#. The release manager will download the Windows i686 and x86_64 installer packages and use their Microsoft
-   Account to submit the files for Microsoft SmartScreen analysis. The instructions are `provided here
-   <https://learn.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-smartscreen/microsoft-defender-smartscreen-overview#submit-files-to-microsoft-defender-smartscreen-for-review>`_.
-   We do this to help our Windows-based users have an easier time downloading the game in the Microsoft Edge
-   browser.
+
 #. The release manager mentions user @Corbeau on Discord ``#releases-project`` channel giving the new URL to
    update his blog page once all of the GitHub action runners are complete.
+
 #. The release manager mentions user @panch93 on Discord ``#releases-project`` channel so he can update the
    Arch AUR with the latest release.
 

docs/Contributing/stable-branch.rst

@@ -16,23 +16,23 @@ occasions where we are introducing major breaking changes that take time to reso
 back-port a commit (a single patch) or a Pull Request (a collection of commits) over to the ``stable`` branch.
 
 The ``stable`` branch is created when preparing for the first Release Candidate towards a stable release, see
-:doc:`release`.
-This page documents the rules and procedures for maintaining the ``stable`` branch.
+:doc:`release`. This page documents the rules and procedures for maintaining the ``stable`` branch.
 
 Requirements for a Back-Port
 ============================
 
 Only specific categories of commits will be approved for a back-port from ``master`` to ``stable``. They are:
 
-* :strong:`Bug Fixes` -- Not 100% of bug fixes should be back-ported, but certainly most should be considered.
-  `Breaking` bugs that are found and patched should always be back-ported.
-* :strong:`Documentation` -- We can support a ``latest`` and ``stable`` version in our documentation system.
+* :strong:`Bug Fixes` --- Not 100% of bug fixes should be back-ported, but certainly most should be considered.
+  *Breaking* bugs that are found and patched should always be back-ported.
+
+* :strong:`Documentation` --- We can support a ``latest`` and ``stable`` version in our documentation system.
   If there are issues found in our documentation that explicitly targets ``stable``, then we should back-port
   or author a Pull Request with a target of ``stable``.
 
 :strong:`Things we will not back-port`
 
-* :strong:`New Features or general improvements` -- This is what ``master`` branch is for.
+* :strong:`New Features or general improvements` --- This is what ``master`` branch is for.
 
 As we often do, we will allow common sense to dictate any deviations from these rules. However, it should be
 generally understood that there should be a careful consideration of what to back-port from ``master`` to
@@ -46,7 +46,9 @@ the primary comment that the PR is a back-port candidate. If the whole PR is not
 commit within the PR is, then this distinction should be highlighted as part of the comment. The full Commit
 ID is the definitive reference point to reduce ambiguity.
 
-As is customary, all PRs should target the ``master`` branch.
+As is customary, all PRs should target the ``master`` branch by default. If needed, contributors may also
+submit PRs that target the ``stable`` branch. Notes in the description should be clear as to why the PR is
+targeting the nom-development branch.
 
 Who Approves a Back-Port Request?
 =================================
@@ -59,6 +61,10 @@ of patches that need to be back-ported.
 The back-port project is here: https://github.com/orgs/longturn/projects/3. You can find it by going to the
 main Longturn GitHub repository page and click on the projects tab.
 
+.. note::
+  The back-port project is a protected project in the GitHub repository. If you do not have access, an access
+  request can be made in the ``LT.DEV`` section on our Discord server.
+
 As part of the review process, simply tag the PR to the project and add a ``back-port`` label to aid tracking.
 Once the PR has been merged into ``master``, go get the commit ID(s) and add those to the appropriate column
 in the project. Multiple Commit IDs should be separated by a space.
@@ -76,3 +82,8 @@ Follow these steps:
 #. Run ``git cherry-pick -x $(cat commits.txt)``
 #. Push ``stable`` to upstream: ``git push upstream``
 #. Update the project sheet to denote which commits were back-ported.
+
+.. note::
+  The only time that we allow a direct push to ``stable`` branch is via the cherry pick approach described
+  above. All other commits to ``stable`` should either follow the existing back-port process, or via a PR that
+  targets ``stable`` directly so the standard review process is followed.

docs/_static/theme_overrides.css

@@ -51,6 +51,23 @@ h4 {
     font-size: 22px;
 }
 
+/* add whitespace between list items */
+li {
+    margin-bottom: 7px;
+}
+
+li ol li {
+  margin-bottom: 7px;
+}
+
+li ul li {
+  margin-bottom: 7px;
+}
+
+.toctree-wrapper li, .current li {
+    margin-bottom: 3px;
+}
+
 /* set the font of the side nav bar header */
 .wy-side-nav-search {
     font-family: Libertinus Sans, sans-serif;