Expand on image maintenance role

1 files changed, 53 insertions, 0 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.