Improve documentation on making releases (#2157)

choldgraf · web-flow · commit 27ca6ef2a151 · 2025-12-04T12:04:12.000-08:00
diff --git a/docs/contribute-docs.md b/docs/contribute-docs.md
@@ -74,6 +74,7 @@ Some pages in the MyST documentation include executable code cells that demonstr
 
 This will execute all `{code-cell}` directives in the documentation and include their outputs in the built site.
 
+(docs:update-mystmd.org)=
 ## How to update the live website at mystmd.org
 
 When you change the content here or in most other MyST repositories, it will _not_ automatically update mystmd.org. We use [a custom MyST theme](#about:mystmd.org) that aggregates content from several MyST repositories into a single website. The content for the live website mystmd.org is hosted by Curvenote. To update the content of `mystmd.org`, [dispatch the action on `main`](https://github.com/jupyter-book/mystmd/actions/workflows/docs.yml).
diff --git a/docs/developer.md b/docs/developer.md
@@ -524,80 +524,108 @@ And to see a list of available templates that can be resolved for Typst, you can
 
 https://api.mystmd.org/templates/typst
 
+(howto:release)=
 ## How to make a release
 
-:::{important} Release Coordination
-We use the [`#release_coordination`](https://discord.com/channels/1083088970059096114/1384242935645737141) Discord channel to coordinate and collaborate on releases. For example, to ensure that features are not half-shipped, additional PRs can make it into a release, or other release responsibilities that can be shared among the team (e.g. release notes, theme deployments, social media posts, documentation updates).
-:::
+This process follows the general steps of making a release in the Jupyter Book community. Here are the basic steps to follow for any project:
 
-### Make a release of `mystmd`
+1. [Tell others about the upcoming release](#release:coordination).
+2. Publish the release in the package repository for the tool. For example:
+   - [How to publish a release of `mystmd`](#release:mystmd).
+   - [How to publish a release of `myst-theme`](#release:myst-theme).
+3. [Make a release on GitHub](#release:github).
+4. [Update the documentation](release:docs).
+5. (optionally) [Create and share a blog post](#release:share).
 
-To publish a new release of `mystmd`, we do two things:
+(release:coordination)=
+### Coordinating the release with the team
 
-1. [Publish to NPM](#release-npm).
-2. [Publish a GitHub release](#release-github).
+We use the [`#release_coordination`](https://discord.com/channels/1083088970059096114/1384242935645737141) Discord channel to coordinate and collaborate on releases.
+This is a way to generate excitement and get any last-second work in before shipping.
+It also gives others a heads-up that some new functionality is about to go live.
 
-We describe each below.
+### Publish a release for the repository
 
-(release-npm)=
+When you publish a release, you upload a new version of the tool for package managers to use. The specifics depend on the toolchain for your package (in particular, it is different for Python vs. JavaScript tools). Here are a few specifics for the `mystmd` repository.
 
+(release:mystmd)=
 #### Publish a `mystmd` release to NPM
 
+`mystmd` is published to NPM via a GitHub Action. Here's how to publish a release.
+
 - Find the **changesets** PR. This contains a list of the version updates that will be included with this release. [Here's an example of a release PR](https://github.com/jupyter-book/mystmd/pull/1896).
 - Double-check the changes that have been merged to `main` and make sure nothing particularly complex or breaking has been merged. Bias towards action, but use your best judgment on whether to move forward.
 - After merging that PR, [this GitHub action will make a release](https://github.com/jupyter-book/mystmd/blob/main/.github/workflows/release.yml).
   - It calls `npm run version` to generate the changelog (to review the changelog, you can run that command locally too).
   - It then publishes the updated packages to the [`mystmd` npm registry](https://www.npmjs.com/package/mystmd) (it calls `npm run publish:ci`, which calls `changeset publish`).
   - It creates a git version tag (which you'll use in making the GitHub release).
-- Next, [make a release on GitHub](#release-github).
 
-(release-github)=
+You're done!
+
+(release:myst-theme)=
+#### Publish a release of `myst-theme`
+
+The process for releasing `myst-theme` infrastructure is similar to the release process for `mystmd`. Here's a brief overview:
+
+- Find the changesets PR in `myst-theme` and merge it, similar to [the `mystmd` release process](#release:mystmd).
+  [Here's an example PR in `myst-theme`](https://github.com/jupyter-book/myst-theme/pull/574).
+- Double-check the changes that have been merged to `main` and make sure nothing particularly complex or breaking has been merged.
+  Bias towards action, but use your best judgment on whether to move forward.
+- Merge that PR. This will trigger the release process by running our release action. [Here's an example run of that action](https://github.com/jupyter-book/myst-theme/actions/runs/15005221275).
+  - The action will build the latest version of the theme infrastructure, and update the template files in the [`myst-templates` GitHub organization](https://github.com/myst-templates). [Here are the lines that update this template](https://github.com/jupyter-book/myst-theme/blob/8283e4505fdb418355ca25ae114ba7bea3cec956/.github/workflows/release.yml#L39-L50).
+
+You're done!
 
-#### Automated releases on GitHub
+(release:github)=
+### Automated releases on GitHub
 
-After a successful NPM release, our [`release.yml` workflow](https://github.com/jupyter-book/mystmd/blob/main/.github/workflows/publish-github-release.yml) will automatically create a new GitHub Release. The release notes are generated using [`github-activity`](https://github.com/cheukting/github-activity) and include a summary of all merged PRs and commits since the previous release.
+After a successful NPM release, our [`release.yml` workflow](https://github.com/jupyter-book/mystmd/blob/main/.github/workflows/publish-github-release.yml) will automatically create a new GitHub Release.
+The release notes are generated using [`github-activity`](https://github.com/cheukting/github-activity) and include a summary of all merged PRs and commits since the previous release.
 
-**Maintainers are encouraged to review the new GitHub Release and edit the description as needed.** For example, you may want to add an executive summary, highlight important changes, or clarify upgrade instructions for users.
+**Maintainers are encouraged to review the new GitHub Release and edit the description as needed.**
+For example, you may want to add an executive summary, highlight important changes, or clarify upgrade instructions for users.
 
 You can find the latest releases at: https://github.com/jupyter-book/mystmd/releases
 
-When you've confirmed the release has been made, consider sharing it for others to discover!
+(release:docs)=
+### Update documentation
 
-:::{note} Here's an announcement snippet you can copy/paste
-:class: dropdown
+When we make a release we should ensure that the documentation is up-to-date with the latest version. This will depend on the tool that you're using.
 
-```md
-TITLE: 🚀 Release: MySTMD v1.3.26
+**For tools hosted at mystmd.org**, follow these [instructions to update the content at mystmd.org](#docs:update-mystmd.org).
 
-BODY:
-The [Jupyter Book project](https://compass.jupyterbook.org) recently made a new release! 👇
+**For most other tools**, the documentation should auto-update with new releases (e.g., via a GitHub action).
 
-[MySTMD v1.3.26](https://github.com/jupyter-book/mystmd/releases/tag/mystmd%401.3.26)
+(release:share)=
+### Create and share a blog post
 
-See the link above for the release notes on GitHub! Many thanks to the [Jupyter Book team](https://compass.jupyterbook.org/team) for stewarding our development and this release.
-```
+Feel free to use the blog to post release notes as well.
+This should be as simple and quick as possible, don't over-think it. Here are some simple steps:
 
-:::
+1. Copy and paste the [release notes you generated](#release:notes) into a new file [on our blog repository](https://github.com/jupyter-book/blog).
+2. Use the following YAML header metadata for the post:
 
-**Here are a few Jupyter-adjacent spaces to share with** (you can just copy/paste the same text into each):
+   ```yaml
+   ---
+   date: <release-date>
+   author: The Jupyter Book Team
+   title: <title from GitHub release>
+   tags: release
+   ---
+
+   <content from GitHub release>
+   ```
+3. Self-merge the blog post.
+
+Feel free to celebrate new releases and share the news publicly so that others know about new enhancements in our projects.
+
+**Spaces to publicize releases**. Here are a few places that are worth sharing (you can just copy/paste the same text into each):
 
 - [The MyST Discord](https://discord.mystmd.org/)
 - [The Jupyter Zulip Forum](https://https://jupyter.zulipchat.com)
 - [The Jupyter Discourse](https://discourse.jupyter.org)
 - Social media spaces of your choosing.
 
-(release-myst-theme)=
-
-### Make a release of the `myst-theme`
-
-The process for releasing `myst-theme` infrastructure is similar to the release process for `mystmd`. Here's a brief overview:
-
-- Find the changesets PR in `myst-theme` and merge it, similar to [the `mystmd` release process](#release-npm). [Here's an example PR in `myst-theme`](https://github.com/jupyter-book/myst-theme/pull/574).
-- Double-check the changes that have been merged to `main` and make sure nothing particularly complex or breaking has been merged. Bias towards action, but use your best judgment on whether to move forward.
-- Merge that PR. This will trigger the release process by running our release action. [Here's an example run of that action](https://github.com/jupyter-book/myst-theme/actions/runs/15005221275).
-  - The action will build the latest version of the theme infrastructure, and update the template files in the [`myst-templates` GitHub organization](https://github.com/myst-templates). [Here are the lines that update this template](https://github.com/jupyter-book/myst-theme/blob/8283e4505fdb418355ca25ae114ba7bea3cec956/.github/workflows/release.yml#L39-L50).
-- Make a release on GitHub, by following the same process in [](#release-github).
-
 ## Practices we follow
 
 ### Build system
