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

#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.