From 9d7f58689846bc24b6e8636f07420a689a5f5745 Mon Sep 17 00:00:00 2001 From: Te-Shu Wang Date: Sun, 30 Aug 2026 11:24:22 +0800 Subject: [PATCH] DOC: document RTD slugs for subpackage releases --- changes/4236.doc.md | 1 + docs/contributing.md | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 changes/4236.doc.md diff --git a/changes/4236.doc.md b/changes/4236.doc.md new file mode 100644 index 0000000000..45f8a2c22c --- /dev/null +++ b/changes/4236.doc.md @@ -0,0 +1 @@ +Document how to reassign Read the Docs version slugs when publishing a subpackage release. diff --git a/docs/contributing.md b/docs/contributing.md index dea7256c36..369e60110a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -356,6 +356,26 @@ This policy exists to lower the cost of routine work and to help newer core deve To give the release visibility and a single place to track progress, open an issue on GitHub announcing the release using the [release checklist template](https://github.com/zarr-developers/zarr-python/issues/new?template=release-checklist.md). The release checklist includes all steps necessary for the release. +#### Read the Docs versions for subpackage releases + +Read the Docs creates a version for every tag in the repository, including tags for +`zarr-python` and the subpackages. This can leave the desired public slug attached to the +wrong tag. For example, the slug `v0.4.0` may already belong to the `zarr-python` tag +`v0.4.0` when releasing `zarr-metadata` from `zarr_metadata-v0.4.0`. + +Before activating a subpackage release in Read the Docs: + +1. Open **Admin > Versions** for the subpackage documentation project. +2. Find the version currently using the desired slug, such as `v0.4.0`, and change its + slug to an unused value, such as `xv0.4.0`. +3. Find the version created from the subpackage tag, such as `zarr_metadata-v0.4.0`, and + assign it the released slug, `v0.4.0`. +4. Verify that the release URL resolves to the subpackage tag, for example + `https://zarr-metadata.readthedocs.io/en/v0.4.0/`. + +Use the same process for `zarr-indexing` tags such as `zarr_indexing-v0.2.0` and any +other subpackage hosted as a separate Read the Docs project. + ## Compatibility and versioning policies ### Versioning