[doc] Add release process documentation

Signed-off-by: Michael Brown <mcb30@ipxe.org>
2026-05-08 15:02:55 +03:00 · 2026-02-25 21:55:05 +00:00
parent ad748f0d92
commit f00d2079d3
1 changed files with 81 additions and 0 deletions
@@ -0,0 +1,81 @@
+Release process
+===============
+
+A release will be generated automatically for any version number tag
+(of the form `v*`).  Release notes will be extracted from the contents
+of the relevant section in [`CHANGELOG.md`][changelog].
+
+The reduced-feature Secure Boot binaries will be signed using the
+[iPXE Secure Boot CA][ipxesbca] and may be booted on a system with
+UEFI Secure Boot enabled using the [iPXE shim][ipxeshim].
+
+Steps
+-----
+
+1.  Edit the top-level [`Makefile`][makefile] to select values for
+    `VERSION_MAJOR`, `VERSION_MINOR`, and `VERSION_PATCH`, and to set
+    `EXTRAVERSION` to an empty string.
+
+2.  Edit [`CHANGELOG.md`][changelog] to create a section and link for
+    the new release.
+
+3.  Commit these changes with a message such as:
+    ```
+    [release] Release version 1.2.3
+    ```
+
+4.  Tag the commit with the correct version number, e.g.:
+    ```
+    git tag v1.2.3
+    ```
+
+5.  Push the tag (and only the tag), e.g.:
+    ```
+    git push origin v1.2.3
+    ```
+    This will automatically create a [draft release][releases]
+    including signed versions of the Secure Boot binaries.
+
+6.  If all checks on the tag succeeded, then push the master branch as
+    normal:
+    ```
+    git push
+    ```
+
+7.  Publish the [draft release][releases].
+
+8.  Edit the top-level [`Makefile`][makefile] to set `EXTRAVERSION`
+    back to the value `+`.
+
+9.  Commit this change with a message such as:
+    ```
+    [release] Update version number after release
+    ```
+
+10. Push the master branch as normal:
+    ```
+    git push
+    ```
+
+Caveats
+-------
+
+Note that pushing the tag will trigger parts of the [build
+workflow][workflow] that are not usually run.  In particular, the UEFI
+Secure Boot signing stage will take place on a dedicated GitHub
+Actions [runner][runners] that has access to a [hardware signing
+token][ipxesbca].  There is a reasonable chance that parts of the
+workflow may fail (e.g. due to an expired code signing certificate).
+To recover from a failure, delete the tag (and the draft release, if
+it has been created).
+
+The signing step can be tested in isolation by pushing to the `sbsign`
+branch, without the need to run through the whole release process.
+
+[changelog]: CHANGELOG.md
+[ipxesbca]: https://github.com/ipxe/secure-boot-ca
+[ipxeshim]: https://github.com/ipxe/shim/releases/latest
+[makefile]: src/Makefile
+[releases]: https://github.com/ipxe/ipxe/releases
+[runners]: https://github.com/ipxe/ipxe/settings/actions/runners
+[workflow]: .github/workflows/build.yml