Update docs + add release template

.github/ISSUE_TEMPLATE/versioned_release.md

@@ -0,0 +1,55 @@
+---
+name: Versioned Release Checklist
+about: The process for creating a new release.
+title: Release vYYYY.MM.DD Checklist
+labels:
+ - metadata
+ - packaging
+ - release
+ - zenodo
+assignees: ""
+---
+
+[Additional release process documentation](https://catalystcoop-pudl.readthedocs.io/en/latest/dev/run_a_release.html).
+
+```[tasklist]
+## Release Checklist
+- [ ] Set a release date & notify team
+- [ ] Close out the [PUDL Release Notes](https://catalystcoop-pudl.readthedocs.io/en/latest/release_notes.html) with an overview of the changes in this release
+- [ ] Push vYYYY.MM.DD tag
+- [ ] Verify that the new [GitHub (software) release](https://github.com/catalyst-cooperative/pudl/releases) has been published
+- [ ] Verify RTD build for new version is up to date (activate new version first in [RTD admin panel](https://readthedocs.org/projects/catalystcoop-pudl/versions/))
+- [ ] Verify [`catalystcoop.pudl` PyPI (software) release](https://pypi.org/project/catalystcoop.pudl/)
+- [ ] Verify that [PUDL repo archive on Zenodo](https://zenodo.org/doi/10.5281/zenodo.3404014) has been updated w/ new version
+- [ ] Wait 6-10 hours for a successful build to complete
+- [ ] Verify that `stable` and the version tag point at same git ref
+- [ ] Verify that [`stable` docs on RTD](https://catalystcoop-pudl.readthedocs.io/en/stable/) have been updated
+- [ ] Verify `gs://pudl.catalyst.coop/vYYYY.MM.DD` has the new expected data.
+- [ ] Verify `gs://pudl.catalyst.coop/stable` has the new expected data.
+- [ ] Verify `s3://pudl.catalyst.coop/vYYYY.MM.DD` has the new expected data.
+- [ ] Verify `s3://pudl.catalyst.coop/stable` has the new expected data.
+- [ ] Verify that draft deposition for [this Zenodo archive](https://doi.org/10.5281/zenodo.3653158) has the new expected data
+- [ ] Update Zenodo description and other metadata based on release notes (see task list below)
+- [ ] Manually publish the new Zenodo deposition with the updated metadata
+- [ ] Create an Announcement for the release in [our GitHub Discussions](https://github.com/orgs/catalyst-cooperative/discussions)
+- [ ] Update the [release documentation](https://catalystcoop-pudl.readthedocs.io/en/latest/dev/run_a_release.html) to better reflect the actual process for next time
+- [ ] Wait 2-12 hours for a bot to create a PR in the [PUDL conda-forge feedstock](https://github.com/conda-forge/catalystcoop.pudl-feedstock/pulls), and then review and merge it.
+- [ ] Review the `conda-forge` PR, updating dependencies and CLI entrypoints if necessary. Our direct dependencies (from `pyproject.toml`) should be pinned to the actual version appearing in `environments/conda-linux-64.lock.yml`
+```
+
+```[tasklist]
+### Zenodo Metadata Tasks
+- [ ] Make sure all Catalyst members are listed in creators (automate!)
+- [ ] Update Zenodo deposition description to reflect current release (automate!)
+- [ ] Set correct version for Zenodo data release archive (automate!)
+- [ ] Set keywords for Zenodo data release archive (automate!)
+- [ ] Set language of Zenodo data release archive (automate!)
+- [ ] Zenodo PUDL repo archive: update release notes (cut-and-paste from GitHub)
+- [ ] Zenodo PUDL repo archive: add keywords (automate with a `.zenodo.json` file for the repo)
+- [ ] Zenodo PUDL repo archive: set language to English (automate with a `.zenodo.json` file for the repo)
+```
+
+```[tasklist]
+### Issues that we ran into
+- [ ] Take notes here during the release if stuff happens.
+```

docs/dev/run_a_release.rst

@@ -5,21 +5,25 @@ Run a Versioned Release
 So the time has come and we would like to release a ``stable`` version of our
 data/code out into the world. By the end of this, we'd like for:
 
-* the release notes to have a fully dated release
-* the git tag ``vYYYY.MM.DD`` to identify a specific version
-* the ``stable`` Git branch to refer to the same commit as that tag
+* The release notes to have a fully dated release and a narrative overview of
+ what's changed since the last release.
+* The git tag ``vYYYY.MM.DD`` to identify a specific version.
+* The ``stable`` Git branch to refer to the same commit as that tag.
 * Our data outputs corresponding to that tag on Zenodo,
- ``pudl.catalyst.coop/stable`` buckets in GCS/AWS, and Kaggle
+ ``pudl.catalyst.coop/stable`` buckets in GCS/AWS.
 * Our code corresponding to that tag on PyPI
 * The conda package to be updated with the newest code
 * Updated ``stable`` and ``vYYYY.MM.DD`` documentation on ReadTheDocs
 
-
 Here's how to do it!
+--------------------
 
 1. Tell the rest of the team you're planning on releasing a new version of the
  code in #team. Remind them that any changes to the release notes *after* the
- next nightly build has passed need to go into a new version.
+ next nightly build has passed need to go into a new version. Create a
+ `Versioned Release Checklist
+ <https://github.com/catalyst-cooperative/pudl/issues/new/choose>`__ issue to
+ track your progress.
 
 2. The night before you plan to release, update the release notes with a
  paragraph or two explaining what this new release is, and attach a specific
@@ -39,16 +43,23 @@ Here's how to do it!
  * PyPI has the most current version of our code
 
 6. Verify that the Zenodo draft deposition has all the expected data (raw FERC
- databases, PUDL database, everything the right size).
+ databases, PUDL database, everything the right size. Compare to the files in
+ the GCS/AWS distribution buckets).
 
 7. Update the Zenodo metadata to include the description from the release
- notes, and update the various links.
+ notes and update the links to other resources related to the release. Make sure
+ all the metadata fields are complete and accurate.
 
 8. Publish the Zenodo deposition! Wahoo! You're now done!
 
-9. Except... within 24 hours after the PyPI version is updated, we'll get [a PR
- in the PUDL conda-forge feedstock
- repo](https://github.com/conda-forge/catalystcoop.pudl-feedstock/pulls) from
- the :user:`regro-cf-autotick-bot` updating our ``conda`` packaging. If
- PUDL's direct dependencies have changed in this release, we need to update
- them in the conda packaging recipe in that PR.
+9. Except... within 24 hours after the PyPI version is updated, we'll get `a PR
+ in the PUDL conda-forge feedstock repo
+ <https://github.com/conda-forge/catalystcoop.pudl-feedstock/pulls>`__ from
+ the :user:`regro-cf-autotick-bot` updating our ``conda`` packaging. Review the
+ PR, updating dependencies and CLI entrypoints as needed. The dependencies listed
+ in the ``meta.yaml`` recipe should be the same as those listed in our
+ ``pyproject.toml``, and should be pinned to the actual versions appearing in
+ ``environments/conda-linux-64.lock.yml``. Investigate any superfluous or missing
+ dependencies identified by the ``conda-forge`` analysis, and remove/add them as
+ needed to ensure that we are explicitly including all of our direct dependencies
+ in ``pyproject.toml`` and ``meta.yaml``.