Skip to content

Commit

Permalink
move release procedure docs to release repo
Browse files Browse the repository at this point in the history
Signed-off-by: Gerwin Klein <[email protected]>
  • Loading branch information
lsf37 committed Jul 8, 2024
1 parent 4277481 commit 6e03c5e
Showing 1 changed file with 0 additions and 127 deletions.
127 changes: 0 additions & 127 deletions processes/release-process.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,130 +133,3 @@ versioned releases are available:
- [{{repo}}](https://github.com/{{project.name}}/{{repo}})
{% endfor %}
{% endfor %}

## Release procedure

This section describes how a release is done, and is mostly a checklist for
the person performing a versioned release.

### Release window and freeze

When a release is planned, decide on the timeframe of the release window in
which changes can still be made, and then make an announcement to the relevant
channels that a release is coming up and let people know of the release window
that you have decided. This is to give advance notice to contributors so that
they can prepare for the release and get features merged in before the release
is done. A decent timeframe for the release window is a month.

The relevant channels for the announcement are:

- [seL4 discourse][discourse]
- [seL4 announcement mailing list](https://lists.sel4.systems/postorius/lists/announce.sel4.systems/)
- [seL4 Mattermost](https://mattermost.trustworthy.systems/sel4-external/)

Upon the end of the release window, announce the close of the window and the
start of the release freeze on the relevant channels. Pull requests should not
be merged during the release freeze except for those that fix issues and bugs
that occurred during the release window. Work towards getting the continuous
integration builds to be green while working on the next step.

### Preparing changelogs

Before preparing the changelogs for each project, review the changes of each
project since the last release and decide a new version number as according to
the [Version Numbers](#version-numbers) section.

Clone the `seL4_release` repository from the [seL4
organisation](https://github.com/seL4) (this is currently private and you will
need to ask for access).

Move to the directory of the repository that you cloned and execute the
following while replacing the fields:

```shell
./releaseit prerelease --config data/sel4_prerelease.yml --new-version=<new seL4 version>

./releaseit prerelease --config data/capdl_prerelease.yml --new-version=<new capDL version> --sel4-version=<new seL4 version>

./releaseit prerelease --config data/camkes_prerelease.yml --new-version=camkes-<new CAmkES version> --sel4-version=<new seL4 version>
```

These commands clone the projects in the `/tmp` directory of your machine and
apply two commits that add changes to the `CHANGES` and `VERSION` files. Note
that it also creates a `<project>_release.md` file in each project directory.
You now need to add any extra changes since the last release that were not
already included in the `CHANGES` file for each project. To do so, run `git log`
with the relevant arguments to get the commits since the last release or go to
each project's GitHub page and filter the pull requests that were merged since
the last release. Go through each of the commits/pull requests and summarise
them in the `CHANGES` files. You do not need to add changes that are trivial. The
best way to think about this is: "If I'm a user of (seL4, CAmkES, capDL) will
it affect me? Do I need to know about it, e.g has the API changed? Are
variables renamed? New features? New licences? Removal of features?" etc. Make
sure to also update the `Upgrade Notes` section in each `CHANGES` file.

Meanwhile, you can also work on making sure the continuous integration builds
are green while preparing the changelogs. Remember to also include any fixes and
changes from this process to the changelogs.

### Verification

Coordinate with the verification team to make a simultaneous release of the
verification repositories. If the proof builds are green, this should be a
relatively short process. If the proof builds are not green, the release must
wait until those are fixed.

### Release

Once the continuous integration builds are all green (make sure that the
verification builds are also green) and the changelogs are also done, amend the
commits that the release tool made with the updated `CHANGES` file in each
project, sign the commits off and submit pull requests for each project. Make
sure that the pull request **only** contains the two commits, one for updating
the `VERSION` and the `CHANGES` files to the latest version and one for
updating the `VERSION` file to add the `dev` suffix to the contents.

The next step is to copy the contents of each project's `CHANGES` file to the
`<project>_release.md` file in the same directory. Make sure that the top of
the `<project>_release.md` file contains a `project: sel4`, `project: camkes`,
or `project: capdl` tag. Take all of the `<project>_release.md` files and
rename them to the current release version and add them under the `_releases`
folder in the docsite's repository
[here](https://github.com/seL4/docs/tree/master/content_collections/_releases).
Submit a pull request for those changes as well.

Get all pull requests (should be four, one for each project, and one for the
docsite) merged and then wait for GitHub to release the version tags for each
project. Once this is done, we can now carry out the
last remaining tasks and announce the release.

### Post release

Update the links on the docsite to point to the new releases by updating the
version numbers in this
[file](https://github.com/seL4/docs/blob/master/_config.yml).

Announce on the mailing list as well as the seL4 Discourse that the new release
is done. Update the line in this [file](_includes/custom-navbar.html) to point
to the seL4 Discourse announcement.

Build a new version of the seL4 kernel manual and add it
[here](https://github.com/seL4/website/tree/master/content/Info/Docs) and
update the symlink to point to it.

Finally, go to the release tool and run the following command while replacing
the fields:

```shell
./releaseit postrelease --sel4-new-version=<new seL4 version> --camkes-new-version=<new CAmkES version> --capdl-new-version=<new capDL version>
```

This command will add version tags to each sub-project repository for each of
the repositories that are under those projects. Running it without the
`--release` flag will perform a dry-run. If there are issues during the dry-run,
fix them up and when everything is all good, run it with the `--release` flag.

Now, the final task to do it to go to the GitHub pages for the seL4, CAmkES,
and capDL projects and draft new GitHub releases for each of the projects.

Once you're here, hurray the release is done!

0 comments on commit 6e03c5e

Please sign in to comment.