diff options
| -rw-r--r-- | builds.sr.ht/image-maintenance.md | 114 |
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. |