Improve release instructions (#418)

* update

* Update doc/source/preparing_releases_and_hotfixes.rst

* Update doc/source/preparing_releases_and_hotfixes.rst

Co-authored-by: Lily Wang <[email protected]>

---------

Co-authored-by: Lily Wang <[email protected]>

Author: RMeli

doc/source/preparing_releases_and_hotfixes.rst

@@ -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
@@ -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
 ----------------------------------------
@@ -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.