Update release process and procedure documentation

docs/developers/coredev/release.md

@@ -2,50 +2,65 @@
 
 # Release guide
 
-This guide documents `napari`'s release process. Most required tools mentioned here are in https://github.com/napari/napari-release-tools
+This guide documents `napari`'s release process as of 0.6.0.
+Most required tools mentioned here are in https://github.com/napari/napari-release-tools.
 
-# Timeline
+## Timeline
 
-Currently, we are releasing a new napari version every 2-3 weeks. Release candidates are made available as a reasonableness check for 1-24h before the full release is published: since the release cadence is so high, any new bugs can be quickly rectified, and more quickly identified by making a full release.
+Currently, we are releasing a major version every six to twelve months.
+We plan minor napari version releases every 1-2 months.
+We will ship bug fix releases as needed.
 
-When major API changes and deprecations happen, we will provide longer release candidate cycles to ensure proper testing by the community.
+Prior to major and minor releases, we will have a release testing cycle with
+alpha prereleases and release candidates. All will be made available to the
+community for testing. The length of time between these prereleases will
+depend on the size of the release and feedback received. A conservative estimate
+is one week between each prerelease.
 
-The latest release candidate can be installed with
+The latest prerelease (alpha or release candidate) can be installed with:
 
 `python -m pip install --pre napari`
 
-# Release management
+`uv pip install --pre napari`
+
+:::{important}
+Note: the `--pre` in the above commands will install prereleases of napari and all dependencies! This may result in errors or warnings. If this happens, you can instead install napari without `--pre`, but instead specify `a0` in the installation. For example, for a prerelease of a hypothetical `1.0.0` version of napari, you would install `"napari>=1.0.0a0"`. Replace `1.0.0` with the actual version you are interested in.
+:::
+
+## Release management
+
 The release will be coordinated by a release manager whose responsibilities include the following.
 
-## One week before release
+### Step 1: Preparing for the release
 - Look through currently open PRs and get a sense of what would be good to merge before the first release candidate. Set milestones appropriately;
 - Ensure `conda-recipe/meta.yaml` in `napari/packaging` is up-to-date (e.g. `run` dependencies match `pyproject.toml` requirements);
 - Create a zulip thread in [the release channel](https://napari.zulipchat.com/#narrow/stream/215289-release) letting people know the release candidate is coming and pointing out PRs that would be nice to merge before release.
 
 At this stage, bug fixes and features that are close to landing should be prioritized. The release manager will follow up with PR authors, reviewing and merging as needed. New features should wait until after release.
 
-## 1-2 days before release
+### Step 2: Generating release notes
 
 - Add a header and highlights section to the [`additional notes`](https://github.com/napari/napari-release-tools/tree/main/additional_notes) folder for the given release. Use the [highlight label](https://github.com/napari/napari/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen+label%3Ahighlight) for the relevant milestone to note which PRs to comment on.
 - Generate release notes with the [`generate_release_notes.py` script from napari/napari-release-tools](https://github.com/napari/napari-release-tools/blob/main/generate_release_notes.py);
 - make a PR with the release notes, making sure to add the new document to the [napari/docs table of contents file](https://github.com/napari/docs/blob/main/docs/_toc.yml). See an example of such a PR: [https://github.com/napari/docs/pull/485](https://github.com/napari/docs/pull/485)
 
 At this point the release manager should ideally be the only person merging PRs on the repo for the next few days before the release.
 
-## 1-0 days before release
+### Step 3: Making the prerelease
 
 - Merge any remaining PRs and update release notes accordingly;
 - Merge release notes;
 - Make the release candidate and announce on zulip;
 - Announce to release stream on zulip that the first release candidate is available for testing.
 
-## The day of release
+### Step 4: Testing the prerelease
+
 - Make sure final rc has been tested;
 - Ensure all PRs have been added to release notes;
 - Make sure docs are correctly deployed;
 - Make release and announce on zulip.
 
-# Release process
+## Release procedures
 
 Additional `release` dependencies (`python -m pip install -e .[release]`, from the `napari/napari` root folder) are required to complete the release process.
 
@@ -58,7 +73,7 @@ This likely has been done already, but if it has not, follow
 [this guide](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions)
 to add it as a secret.
 
-## Determining the version
+### Determining the version
 
 The version of `napari` is automatically determined at install time by
 [`setuptools_scm`](https://github.com/pypa/setuptools_scm) from the latest
@@ -68,7 +83,7 @@ The version of `napari` is automatically determined at install time by
 the new version number. It is likely something like `X.Y.Z`. Before making a
 release though we need to generate the release notes.
 
-## Generating release notes
+### Generating release notes
 
 1. Grab the `generate_release_notes.py` script from the
    [napari/napari-release-tools](https://github.com/napari/napari-release-tools)
@@ -94,7 +109,7 @@ release though we need to generate the release notes.
 
 4. Make and merge a PR with these release notes before moving onto the next steps.
 
-## Update constraints files
+### Update constraints files
 
 `napari` uses a set of constraints files to prevent test failures due to dependency updates. This also allows for reproducible builds (see [](dev-installation)).
 These constraints files need to be updated at least weekly on Monday, and may also be triggered manually by a maintainer. You can find these files at
@@ -112,7 +127,7 @@ uv pip compile --python-version 3.11 --upgrade --output-file resources/constrain
 
 To see other examples, check out the [upgrade test constraints action](https://github.com/napari/napari/blob/main/.github/workflows/upgrade_test_constraints.yml).
 
-## Tagging the new release candidate
+### Tagging the new release candidate
 
 First we will generate a release candidate, which will contain the letters `rc`.
 Using release candidates allows us to test releases on PyPI without using up the actual
@@ -135,7 +150,7 @@ before making the real release.
 
 You can read more on tagging [here](https://git-scm.com/book/en/v2/Git-Basics-Tagging).
 
-## Testing the release candidate
+### Testing the release candidate
 
 Our CI automatically makes a release, copying the release notes to the tag and uploading the distribution to PyPI.
 You can trigger this by pushing the new tag to `napari/napari`:
@@ -157,7 +172,7 @@ incrementing the number after `rc` on tag (e.g. `vX.Y.Zrc2`).
 
 Once you are satisfied with the release candidate it is time to generate the actual release.
 
-## Generating the actual release
+### Generating the actual release
 
 To generate the actual release you will now repeat the processes above but now dropping the `rc`.
 For example:
@@ -229,7 +244,9 @@ For more details, follow the instructions for
 
 Please make sure a correct build for the problematic release is available before (or shortly after) the `admin-requests` PR is merged!
 
-## Post release: update the documentation
+## Post release
+
+### Update documentation based on user feedback
 
 The [napari docs](https://napari.org) are versioned, meaning that each release has its own documentation, selected through the version switcher dropdown. Once you tag a new version in the `napari/napari` repo, the [`build_and_deploy.yml` workflow](https://github.com/napari/docs/blob/main/.github/workflows/build_and_deploy.yml) will automatically create a new folder for this version number in the `gh-pages` branch of the `napari/napari.github.io` repo.
 
@@ -248,3 +265,8 @@ git push
 
 2. In the `napari/docs` repo, update the [`docs/_static/version_switcher.json` file](https://github.com/napari/docs/blob/main/docs/_static/version_switcher.json) so that `stable` points to the right version. The active version switcher is read from the file in the `dev` folder, so this can be done as the last step in the process.
 
+### Plan a bug release
+
+If any critical bugs are found in the release, a bug release should be planned.
+This will be a minor release with the bug fixes and no new features.
+The release manager should coordinate with the maintainers to ensure that the bug release is made in a timely manner.