Expand on image maintenance role

2 files changed, 53 insertions, 17 deletions

diff --git a/builds.sr.ht/image-maintenance.md b/builds.sr.ht/image-maintenance.md
new file mode 100644
index 0000000..16f1971
--- /dev/null
+++ b/builds.sr.ht/image-maintenance.md
@@ -0,0 +1,53 @@
+---
+toc: false
+---
+
+# builds.sr.ht image maintenance
+
+Thank you for volunteering to maintain a builds.sr.ht image! Here are some tips
+on how to do it well. Your responsibilities are:
+
+1. Adding new build images as the upstream vendor provides updates
+2. Deprecating old build images as they fall out of upstream support
+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>`
+
+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.
diff --git a/builds.sr.ht/updates.md b/builds.sr.ht/updates.md
deleted file mode 100644
index 0338d84..0000000
--- a/builds.sr.ht/updates.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-toc: false
----
-
-# How to update a build image
-
-1. Prepare the necessary patch. Should include:
-   - Updates to the images/ directory, including adding the new version,
-     removing any obsolete versions, and updating any symlinks
-   - Updating contrib/crontab
-2. Prepare a patch for sr.ht-docs:builds.sr.ht/compatibility.md
-3. Submit a test build based on your image's build.yml which proves that your
-   change works
-
-Then send these patches upstream to sr.ht-dev. Include a link to the successful
-image build and instructions on how to deploy it (usually this is as simple as
-submitting the build.yml with the appropriate version number put in).