From d935d2b0fbd6d6d511c82957acada8e56ca8ecdd Mon Sep 17 00:00:00 2001 From: ojustino Date: Fri, 10 May 2024 13:59:46 -0400 Subject: [PATCH 1/2] Wrote release guide --- docs/index.rst | 1 + docs/release.rst | 155 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 docs/release.rst diff --git a/docs/index.rst b/docs/index.rst index 1bef558..5251467 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,4 +51,5 @@ Using STIPS basic_tutorial examples bugs + release help diff --git a/docs/release.rst b/docs/release.rst new file mode 100644 index 0000000..e22186c --- /dev/null +++ b/docs/release.rst @@ -0,0 +1,155 @@ +****************************** +Developer Release Instructions +****************************** + +This page offers a complete walkthrough on how to prepare and release a new +version of STIPS on GitHub and PyPI, as well as how to sync the ReadTheDocs +documentation with the new release. + +Pre-merge instructions +====================== + +Pull request checklist +---------------------- + +In addition to addressing any byproducts of the code review, you should be able +to answer "yes" to all of the following questions before merging a pull request +intended for a release: + +* Has ``setup.cfg`` been updated to reflect the release's new version number? + +* If any dependencies have changed, have you updated them in all applicable files? These include: + + * ``setup.cfg`` + * ``environment.yml`` + * ``environment_dev.yml`` + * ``docs/installation.rst`` + +* Are you able to install the new version of STIPS locally with ``pip`` and ``conda``? + +* Can you run the example notebooks in the ``notebooks/`` directory without encountering errors? + +* Has ``CHANGES.rst`` been updated to include the current release and its associated updates at the top? + +* Are all CI tests in the release's pull request passing? + +* Has at least one developer given the pull request an official approval on GitHub? + +Once you've completed the checklist, merge the pull request and begin the +release procedure in earnest. + +Post-merge instructions +======================= + +Tagging the merge commit +------------------------ + +Apply a tag to the merge commit, substituting in the proper version number. + +.. code-block:: text + + git tag -s vX.Y.Z -m "Release vX.Y.Z" + +.. note:: + The ``-s`` option allows you to sign the tag using the GNU Privacy Guard (GPG). + While it's not strictly necessary, it's a good security measure. + Follow GitHub's documentation for `creating a GPG key `_ + and `adding it to your account `_ + if you don't have one. + +Next, push the tag online. (If your remote that points to ``spacetelescope``'s +online version of the repository is not named ``origin``, be sure to substitute +its name in below.) + +.. code-block:: text + + git push origin vX.Y.Z + +Release creation (on GitHub) +---------------------------- + +After the tests triggered by pushing the new tag succeed, follow these steps to +manually create a new release in the ``STScI-STIPS`` GitHub repository. + +#. Click "Releases" on main repository page or `follow this link `_. +#. Press the "Draft a new release" button above the list of releases. +#. Press "Choose a tag" and select the one you just pushed online. The target branch should already be selected as ``main``. +#. Press "Generate release notes" to list the commits included in this release. +#. In the "Release title" textbox, type ``Release X.Y.Z``, substituting in the proper version number. +#. Above the list of commits in the larger textbox for comments, write a single-sentence summary of the release's major updates. +#. Press "Publish" to complete this section. + +Release creation (for PyPI) +--------------------------- + +Continue by building wheel and source distribution files to publish to PyPI so +users can ``pip`` install STIPS without cloning the repository. You will need a +PyPI account and maintainer status on `the STIPS project `_ +if you don't already have it there. + +.. note:: + + It's highly recommended that you clone a new copy of the ``STScI-STIPS`` + repository into a new directory on your system and work from there while + completing this section. + + +Make sure you've installed the necessary packages for this procedure: + +.. code-block:: text + + pip install --user --upgrade setuptools wheel twine + +Then, identify the largest subdirectories in your STIPS directory: + +.. code-block:: text + + du -h + +Due to past commits that included large files, STIPS' ``.git/`` subdirectory +will likely be the largest at over 200 MB. Even with compression, working with +the repository as is generates distribution files that surpass PyPI's file size +limit for uploads. + +Since the files in ``.git/`` aren't necessary for users to download as part of +a pip installation, delete them before building anything: + +.. code-block:: text + + rm -r .git + +Now, create the wheel and source distribution files: + +.. code-block:: text + + python setup.py sdist bdist_wheel + +The resulting wheel file and tarball are located in the ``dist`` directory. + +Finally, upload them to PyPI. : + +.. code-block:: text + + python setup.py sdist bdist_wheel + +Note that PyPI uploads now require an API token. +`Refer to their instructions `_ if you haven't +yet set one up. + +While the official release is now complete, keep reading for instructions on +updating the documentation on ReadTheDocs. + +Documentation +============= + +Navigate to `the active STIPS ReadTheDocs page `_. +(Note that the RTD project name is ``stips``, matching the package name but not +the GitHub repository name.) Verify that new builds of ``latest`` and +``vX.Y.Z`` have been run successfully. If not, build them manually under the +"Build a version" header. If you followed earlier instructions, the release +commit will be the repository's current latest commit, so both versions should +be identical for the moment. + +The versions of the documentation that should be visible to the public and +marked as "Active" on their "Edit" pages are ``latest`` and the new release, +``vX.Y.Z``. In the future, we may make past versions visible, too. From 1aeef077e1eb79d08073fbc51903ada855bdb266 Mon Sep 17 00:00:00 2001 From: ojustino Date: Mon, 13 May 2024 18:00:23 -0400 Subject: [PATCH 2/2] Added a description of webhooks Co-authored-by: Sebastian Gomez --- docs/release.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/release.rst b/docs/release.rst index e22186c..491b8e2 100644 --- a/docs/release.rst +++ b/docs/release.rst @@ -69,7 +69,7 @@ Release creation (on GitHub) ---------------------------- After the tests triggered by pushing the new tag succeed, follow these steps to -manually create a new release in the ``STScI-STIPS`` GitHub repository. +manually create a new release in the ``spacetelescope/STScI-STIPS`` GitHub repository. #. Click "Releases" on main repository page or `follow this link `_. #. Press the "Draft a new release" button above the list of releases. @@ -126,7 +126,7 @@ Now, create the wheel and source distribution files: The resulting wheel file and tarball are located in the ``dist`` directory. -Finally, upload them to PyPI. : +Finally, upload them to PyPI: .. code-block:: text @@ -143,8 +143,8 @@ Documentation ============= Navigate to `the active STIPS ReadTheDocs page `_. -(Note that the RTD project name is ``stips``, matching the package name but not -the GitHub repository name.) Verify that new builds of ``latest`` and +(Note that the ReadTheDocs project name is ``stips``, matching the package name +but not the GitHub repository name.) Verify that new builds of ``latest`` and ``vX.Y.Z`` have been run successfully. If not, build them manually under the "Build a version" header. If you followed earlier instructions, the release commit will be the repository's current latest commit, so both versions should @@ -153,3 +153,12 @@ be identical for the moment. The versions of the documentation that should be visible to the public and marked as "Active" on their "Edit" pages are ``latest`` and the new release, ``vX.Y.Z``. In the future, we may make past versions visible, too. + +Troubleshooting: webhooks +------------------------- + +ReadTheDocs is connected to the ``spacetelescope/STScI-STIPS`` GitHub repository +via a webhook, which can be found on `the repository's "Webhooks" page `_. +If for any reason the link happens to break, the webhook can be re-linked by +creating a new secret for the GitHub incoming webhook on `the ReadTheDocs "Integrations" page `_ +and then pasting it to the webhook on GitHub with the matching Payload URL.