Skip to content

Improve release instructions #418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lilyminium merged 3 commits into from
Mar 31, 2025
Merged

Improve release instructions #418

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9316b0a
update
RMeli Mar 31, 2025
05dc8ab
Update doc/source/preparing_releases_and_hotfixes.rst
RMeli Mar 31, 2025
1c3d2d7
Update doc/source/preparing_releases_and_hotfixes.rst
RMeli Mar 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions doc/source/preparing_releases_and_hotfixes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,9 @@ For now, the UserGuide is released at the same time as the core library. If it's
cd doc/source/scripts
python -m pytest tests/snapshot/ --snapshot-update

#. Define the ``GITHUB_TOKEN`` environment variable with a GitHub personal access token that has the ``repo`` scope.
The access token is used by the script at the next step.

#. Make a Pull Request with a re-generated ``releases.md`` which contains a copy of the GitHub release notes. This can be generated by doing:

.. code-block:: bash
Expand All @@ -186,6 +189,8 @@ For now, the UserGuide is released at the same time as the core library. If it's

#. This will automatically trigger a Github Action to build a new set of docs for that release and upload them. Due to the large size of the ``gh-pages`` branch on the UserGuide, this can be both slow and flaky, make sure to keep an eye out for any potential failures.

#. Follow the instructions in the `Clean up old development builds`_ section to remove old developer builds of the documentation.


Create a blog post outlining the release
----------------------------------------
Expand All @@ -205,10 +210,13 @@ Once the release is completed you can go ahead and update the ``develop`` branch
#. Once these changes are merged into the ``develop`` branch, message the developers on discord and GitHub Discussions letting them know that the feature freeze is over.


Clean up old developer builds of the documentation
--------------------------------------------------
.. _Clean up old development builds:
Clean up old developement builds
--------------------------------

Whilst new docs are automatically deployed on a release, old developer builds (appended with ``-dev``) are not automatically cleaned up. To avoid causing large amounts of files being uploaded to GitHub Pages, we need to delete these old developer builds manually. To do this switch to the ``gh-pages`` branch, make sure it is up to date with upstream (i.e., run ``git pull`` ), delete the old files, and push the change directly. You should do this for both the core library and the UserGuide.

Whilst new docs are automatically deployed on a release, old developer builds (appended with ``-dev``) are not automatically cleaned up. To avoid causing large amounts of files being uploaded to GitHub Pages, we need to delete these old developer builds manually. To do this switch to the ``gh-pages`` branch, delete these old files, and push the change directly. You should do this for both the core library and the UserGuide.
In addition, update `versions.json` to remove the old `-dev` entry.

While this is still a manual procedure, you should also edit `versions.json` to remove the old dev links.

Expand Down