Improve releasing docs (#850)

Author: mfisher87

docs/contributor_guide/how-tos/release.md

@@ -2,47 +2,83 @@
 
 ## Automated Releases with `jupyter_releaser`
 
-The recommended way to make a release is to use
-[`jupyter_releaser`](https://jupyter-releaser.readthedocs.io/en/latest/get_started/making_release_from_repo.html)
-in GitHub Actions.
-Follow the linked instructions.
+We use [`jupyter_releaser`](https://jupyter-releaser.readthedocs.io/en/latest/) to
+create our releases in GitHub Actions.
+This document is a quick reference that will work for most releases.
+For full detailed instructions, see the
+[`jupyter_releaser` "Making your first release" document](https://jupyter-releaser.readthedocs.io/en/latest/get_started/making_release_from_repo.html).
 
+:::{important}
 **This project uses [Semantic Versioning](https://semver.org)**.
+:::
+
+## Prerequisites
+
+- To do the following steps, you must have "admin" privileges on the repository.
+
+## Step 1a: Prep release
+
+**This step will bump versions, update the changelog, and create a "draft" release in
+GitHub.**
+
+- From the [JupyterGIS actions menu](https://github.com/geojupyter/jupytergis/actions),
+  select "Step 1: Prep Release" action from the left pane.
+- On the right, click "Run workflow". This will present a menu you need to fill out.
+- The only thing you normally need to input here is the "new version specifier".
+  **The default value is `next`, but we recommend always specifying a numeric specifier, e.g. `0.3.0`**.
+
+  :::{danger}
+  **Specifying a version part (e.g. `minor` or `patch`) for "New Version Specifier" will
+  cause Step 2 to fail.**
+
+  Read below for more important information about the version specifier.
+  :::
+
+### Version specifier
+
+Ensure you understand the [Semantic Versioning](https://semver.org) version part
+definitions ("major", "minor", "patch") before selecting a version.
 
 :::{important}
-Because this project is in early development, we **do not bump the major version number**.
-Most changes are minor version bumps, even breaking changes.
-See [the SemVer FAQ](https://semver.org/#how-should-i-deal-with-revisions-in-the-0yz-initial-development-phase) for more.
+Because this project is currently in early development (pre-1.0), we **do not bump the
+major version number**.
+
+This means that **even breaking changes are minor version bumps**.
+
+See [the SemVer FAQ](https://semver.org/#how-should-i-deal-with-revisions-in-the-0yz-initial-development-phase) for more details.
 :::
 
-### Specifying a version spec
+## Step 1b: Review changelog
 
-When prompted for a "New Version Specifier", the default value is `next`.
-This will bump the packages as follows:
+**This step will make the release notes more readable for end-users.**
 
-- `0.1.0a0` -> `0.1.0a1`
-- `0.1.0b7` -> `0.1.0b8`
-- `0.1.0` -> `0.1.1`
+- Visit the new [GitHub "draft" release](https://github.com/geojupyter/jupytergis/releases) created in Step 1a.
+- Edit the release text to fix any typos and make other edits for end-user
+  accessibility.
+  - Remove any bot-created PRs, for example pre-commit hook updates or dependabot PRs.
+  - Remove any bots from the contributor list.
+  - Edit text for readability by end-users where appropriate.
+  - **Click "Save draft" to save your changes**.
 
-This is often **not** what we want.
-To bump to another version, you can specify the desired version directly.
-For example:
+    :::{danger}
+    **Do not click "Publish a release" in the GitHub UI**.
+    That will be done automatically in Step 2.
+    :::
 
-- `0.1.0b8`
-- `0.4.0`
-- `1.0.0`
-- `1.2.0rc0`
+## Step 2: Publish a release
 
-You can also specify a version part, e.g.:
+- From the [JupyterGIS actions menu](https://github.com/geojupyter/jupytergis/actions),
+  select "Step 2: Publish Release" action from the left pane.
+- On the right, click "Run workflow". This will present a menu, but you can leave it
+  blank.
 
-- `patch`
-  - Would bump `0.3.0` -> `0.3.1`
-- `minor`
-  - Would bump `0.3.0` -> `0.4.0`
-- `major`
-  - Would bump `0.3.0` -> `1.0.0`
+## Step 3: Conda Forge release
 
-## Conda Forge release
+:::{important}
+Before moving on to the Conda Forge release, ensure that JupyterGIS has released on PyPI.
+Check [the PyPI JupyterGIS page](https://pypi.org/project/jupytergis/) to see if the new
+release is present.
+:::
 
 After the PyPI release, a Conda Forge bot will automatically open a PR on
 [our feedstock repo](https://github.com/conda-forge/jupytergis-packages-feedstock).
@@ -53,10 +89,19 @@ title `@conda-forge-admin, please update version`.
 If you need maintainer access to handle releases, you may request access by opening an
 issue with the title `@conda-forge-admin, please add user @my-username`.
 
+:::{caution}
 If the dependencies of JupyterGIS have changed, the Conda Forge recipe must also be
 manually updated -- the bot will not do this for you, but it will likely warn you in a
 comment that it must be done.
+
 Please update `recipe/meta.yaml` to reflect those changes.
+:::
+
+Once the Conda Forge PR is merged, it may take up to an hour for it to be installable.
+Even after the new release is visible on
+[the Anaconda.org JupyterGIS page](https://anaconda.org/conda-forge/jupytergis/files),
+it may still take up to another hour until it's actually installable with `micromamba`
+or similar tools.
 
 ## Release assets
 
@@ -75,3 +120,14 @@ JupyterGIS is published to:
 
 Release assets are also available on GitHub. For example for
 [`0.3.0`](https://github.com/geojupyter/jupytergis/releases/tag/v0.3.0):
+
+## Troubleshooting
+
+### "Step 2: Publish release" fails to build a package with a version like `minor`
+
+In Step 1, if you provide a version specifier like `next`, `patch`, or `minor`, Step 2
+will fail.
+Please specify a numeric version specifier like `0.3.0`.
+
+**If you need to re-run Step 1, delete the draft release it created first**, then start
+over.