builds.sr.ht: update image maintenance guildelines

1 files changed, 74 insertions, 40 deletions

diff --git a/builds.sr.ht/image-maintenance.md b/builds.sr.ht/image-maintenance.md
index 34bcf7a..b49a698 100644
--- a/builds.sr.ht/image-maintenance.md
+++ b/builds.sr.ht/image-maintenance.md
@@ -12,43 +12,77 @@ on how to do it well. Your responsibilities are:
 3. Maintaining the builds.sr.ht integration and docs for this image
 4. First-line support for user issues for this build image
 
-## Adding new images
-
-To add a new version, you should submit a patch to sr.ht-dev which updates the
-images/ directory accordingly, updating any aliases (symlinks) if appropriate.
-You should also update contrib/crontab to set the rebuild schedule for your
-image.
-
-Also prepare a patch for [sr.ht-docs](https://git.sr.ht/~sircmpwn/sr.ht-docs)'s
-builds.sr.ht/compatibility.md page.
-
-If possible, please also submit a tweaked version of `images/<your
-image>/build.yml` which demonstrates a successful build of your updated image.
-Include a link to this build log in the "timely commentary" of your patch to
-sr.ht-dev.
-
-If you're adding a brand-new image, rather than a new version for an existing
-vendor, also include detailed instructions on how we can bootstrap your images
-from scratch. For example, this may be instructions on how to set up a local
-virtual machine based on the vendor OS, then instructions on how to build the
-initial image in this environment.
-
-## Removing deprecated images
-
-When an image is deprecated upstream, we remove it from our supported images.
-This is a three step process:
-
-1. Remove the image from `sr.ht-docs:builds.sr.ht/compatibility.md`
-2. Notify users who have used the image in the past 30 days and give them a two
-   week grace period to update their builds
-3. Remove the image from `builds.sr.ht:images/<vendor>` and update
-   `contrib/crontab`
-
-Please prepare a patch for sr.ht-docs and a patch for builds.sr.ht and send them
-to sr.ht-dev at the same time; we will handle notifying users and wait two weeks
-between applying each patch. Please also include a summary of any important
-changes that users should be aware of when upgrading to the latest version.
-
-If upstream releases a new version at the same time that they deprecate an old
-version, please prepare *separate* patches for builds.sr.ht for removing the old
-and adding the new.
+## Releasing new versions
+
+When a new version of your distribution is released upstream, you should prepare
+a patch for builds.sr.ht which makes the new version available to SourceHut
+users. **You must test new image versions**.
+
+To test new versions, create a clone of builds.sr.ht with the patch applied on
+git.sr.ht, then update your image's build.yml file to point to your git
+repository, and remove the deploy task. Submit this build to builds.sr.ht to
+test-build your new image version from an earlier version which is already
+available, and address any problems that arise during testing.
+
+If you use symlinks (e.g. for the "latest" version of your distribution), submit
+*separate* patches to add new images and to update symlinks, so that we can
+build the named image (e.g. "debian/trixie") before we update the symlinks (so
+that "debian/latest" doesn't point to a yet-to-be-deployed trixie image).
+
+Submit your patch(es) to sr.ht-dev, including at least the following:
+
+* A patch for builds.sr.ht adding the new version, with the URL for your
+  successful test build provided in the timely commentary
+* A patch for builds.sr.ht updating symbolic links, if necessary for your image
+* A patch for sr.ht-docs updating the compatibility matricies
+* An update for contrib/crontab to schedule rebuilds of the new release
+* Any special instructions for deploying the image that require manual
+  intervention from the patch integrator
+
+## Deprecating old versions
+
+We remove distribution releases from SourceHut once they are deprecated by
+upstream, following a 2-week notice period for anyone who has used the
+deprecated image within the 30 days prior to its deprecation.
+
+To remove a deprecated release for your distribution, prepare patches according
+to the following criteria:
+
+* Update builds.sr.ht to drop the image. If you use symlinks, prepare two
+  patches, one updating the symlinks (first patch), and one dropping the named
+  release (second patch)
+* Update the compatibility matrix in sr.ht-docs
+* Update contrib/crontab to unschedule rebuilds of the depreacted release
+* Do not mix the changes in with patches which introduce a *new* release
+
+We will apply patches which update any symbolic links, update the compatiblity
+matrix, then email affected users and wait to apply the patch removing the named
+release until the 2-week notice period expires.
+
+## Introduction of a new distribution
+
+To introduce a new distribution or operating system, you need to prepare a patch
+for builds.sr.ht which updates the images/ directory appropriately. This should
+include a "functions" file, which gives the build workers information on how to
+boot your image; a "genimg" script which, when run from within your target
+operating system, produces the image as a qcow2 file; and a build manifest which
+will automate this process.
+
+It is recommended that you reference existing build images to get an idea of how
+the system can be applied to your target.
+
+Submit your patch to sr.ht-dev and include the following:
+
+* Detailed instructions for bootstrapping the image from scratch for the
+  reviewers and patch integrators, such as how to set up a virtual machine
+  appropriately to run the genimg script. We cannot accept binaries provided by
+  the patch submitter; we will run through the entire bootstrapping procedure
+  independently using upstream sources.
+* An update to `contrib/crontab` which adds your image to the rebuild schedule.
+* A patch for sr.ht-docs adding your image's release details, including details
+  on the upstream deprecation lifecycle and other details pertinent to users of
+  this distribution.
+
+You are **strongly** advised to set up a local instance of builds.sr.ht for
+testing against; we will have very little patience for reviewing untested
+patches of this scale.