Creating a release branch

From postmarketOS Wiki

This is relevant for maintaining the repository only, regular users will not need this guide.

Alpine's release timeline

From the alpine-devel mailing list: 

 The freeze period for 3.16 will start around first half of April 2022, and the freeze period
 for 3.17 will start around first half of October 2022.
 
 We are aiming for releases every May and November, and should start set
 up the builders a month in advance.

In more detail: the Alpine release process

Timeline

Alpine starts working on a new release approximately every six months. This is when the cycle described in the table below begins. The weeks are estimated based on experience, it will get more accurate the more often we go through the release cycle. (But of course, if something unexpected happens in either Alpine or postmarketOS, it may lead to a delay of the release.) All phases are announced in the testing chat.

Get the current calendar week with date +%V.

Calendar Week Phase Name Description
CW 47

(2024-11-18 - 2024-11-24)

Pre-Build

Team:

  • Create release branch in pmaports
  • Start building of binary pkgs early, so we can get through it for sure

Release branches are not yet in feature freeze, but we should avoid making major changes to master.

CW 48

(2024-11-25 - 2024-12-01)

Branch

Team:

  • Rebase the release branch on master once
  • Build binary packages and images (configure BPO for that)

Release branches are in feature freeze:

We can cherry pick fixes where it makes sense, but new features need to go through master and can only go to stable via service packs.

CW 49

(2024-12-02 - 2024-12-08)

Test

Maintainers:

  • Test your devices and UIs (test yourself if you can and/or coordinate with the Testing Team)
  • Report back in the issue (template for devices)
  • Fix stuff that is broken by creating MRs against pmaports master and noting that this should be cherry picked to the release branch.
CW 50

(2024-12-09 - 2024-12-15)

Release

Team:

  • Write the release blog post.

Team + Maintainers:

  • Celebrate with party hats and get wasted.

One month later:

Calender Week Phase Name Description
CW 02

(2025-01-06 - 2025-01-12)

Drop

Team:

  • Mark previous release as unsupported.

Detailed tasks for Team

The tasks below are in a format that's convenient for copying/pasting into a gitlab issue, where each task is checkbox. 

Timeline and template: https://wiki.postmarketos.org/wiki/Create_release_branch

### Preparation
- [ ] Discuss who's in charge of the release (doesn't necessarily mean doing all the work, it can be delegated. just someone to keep pushing it forward)
- [ ] Create gitlab milestone for the release
- [ ] Create an issue in pmaports named "vYY.MM Infrastructure", add it to the milestone, copy paste the checkboxes from this list
- [ ] Assign the person who's in charge of the release to the infrastructure issue
- [ ] Update the [timeline](https://wiki.postmarketos.org/wiki/Creating_a_release_branch) for the next release
- [ ] Post it in the testing channel

### Pre-Build phase

Since v24.06 we are not only including devices and kernels from main and community categories, but also from testing/unmaintained (if they build). Building these kernels takes some extra time, this is what the pre-build phase is for. The branch will be rebased once in the branch phase.

#### Requirements

- [ ] Alpine's main repository must be built and published
- [ ] Alpine's community repository must be built and published

#### pmbootstrap: adjust config
- [ ] add apk-tools min version
  - [ ] https://pkgs.alpinelinux.org/packages?name=apk-tools&branch=edge
  - [ ] `pmb/config/__init__.py:apk_tools_min_version`
- [ ] should be a trivial 1 line change, push it to master directly
- [ ] (can be done later, at start of test phase) make a new [pmbootstrap release](https://wiki.postmarketos.org/wiki/Pmbootstrap_release) <small>bpo uses the master branch, so it will be fine without a release, however users will want to try out the new release and may not run master.</small>

#### pmaports: create branch and initial changes
- [ ] `git checkout -b vYY.MM master`
- [ ] Create a `=== Branch vYY.MM from master ===` commit (third line: `Related: https://wiki.postmarketos.org/wiki/Create_release_branch`)
  - [ ] Remove channels.cfg (should only be in master)
  - [ ] Change `channel=edge` to `channel=vYY.MM` in pmaports.cfg
  - [ ] Change `supported_arches` to `x86_64,aarch64,armv7` in pmaports.cfg
  - [ ] disable x86, armhf, riscv64 in .gitlab-ci.yml on the release branch and delete .ci/build-* scripts for these arches
- [ ] `git push`
- [ ] '''protect the new release branch in gitlab''', so nobody can force-push to it

#### pmaports: update master branch
- [ ] `git checkout master`
- [ ] add the new branch to [channels.cfg](https://wiki.postmarketos.org/wiki/Channels.cfg_reference), [like this](https://gitlab.postmarketos.org/postmarketOS/pmaports/-/commit/c43571ceaf9b8155519bc9fb760bdeccd96e7e9c)
- [ ] `git push`

#### pmaports: update os-release / remove packages / aportgen
- [ ] `git checkout vYY.MM`
- [ ] update `postmarketos-base`:
  - [ ] set version info for `/usr/lib/os-release` in `main/postmarketos-base/rootfs-usr-lib-os-release` (`PRETTY_NAME="postmarketOS vYY.MM"`, `VERSION_ID="vYY.MM"`, `VERSION="vYY.MM"`)
  - [ ] `pmbootstrap pkgrel_bump postmarketos-base`
  - [ ] `pmbootstrap config mirror.pmaports none`
  - [ ] `pmbootstrap checksum postmarketos-base`
  - [ ] commit
- [ ] remove packages:
  - [ ] `cross/*-armhf` and other unsupported arches in cross dir (keep gcc-x86 and musl-dev-x86, they are needed for systemd-boot for x86_64)
  - [ ] main/postmarketos-ui-asteroid (no smartwatches are useful on stable branches at the moment)
  - [ ] main/postmarketos-ui-framebufferphone until [aports#13857](https://gitlab.alpinelinux.org/alpine/aports/-/issues/13857) is resolved
  - [ ] gcc4* and gcc6* from main and cross
- [ ] run `pmbootstrap aportgen` for packages in cross
- [ ] `git push`

#### bpo: adjust config
- add the branch to the [build.postmarketos.org](https://gitlab.postmarketos.org/postmarketOS/build.postmarketos.org) config
  - [ ] `bpo/config/const/__init__.py:branches`
  - [ ] ignore_errors: True
  - [ ] add it below `branches["master"]`, so it builds with lower priority than master until it's released
- [ ] make a merge request, wait until CI passes, merge it (or if you can directly push to master that's also fine since it's a trivial change)
- [ ] roll it out/ask somebody who can do that
- [ ] restart bpo, it will start building x86_64 packages

#### bootstrap of binary packages
- [ ] fix failing x86_64 packages (Remember: patches need to go through edge first, then get backported to the stable branch!)
  - Try to get build fixes merged to edge quickly, ask for reviews in #postmarketos-devel, and consider merging trivial fixes right after they pass CI.
  - Devices in testing and archived categories that don't build: consider trying to fix them, or just delete them from the branch
- [ ] wait until all packages for x86_64 are built and published
- [ ] fix up ARM packages too
- [ ] wait until all packages for ARM are built and published

#### Adjust CI
- [ ] make sure pmaports.git CI runs through on the new branch (run `pmbootstrap ci`). Examples of why it might fail:
  - one postmarketos-ui package has a package from alpine testing in their _pmb_recommends.
    - remove the UI if it is not used much (can bring it back on demand) or fork the package to the new branch
    - consider fixing it in edge, so we don't run into this with the next release
  - CODEOWNERs point at devices that have been deleted for the stable release
- [ ] adjust [monitoring](https://gitlab.postmarketos.org/postmarketOS/monitoring) to run on the new release and make sure it passes ([example](https://gitlab.postmarketos.org/postmarketOS/monitoring/-/merge_requests/10))

#### Adjust release upgrade script
- [ ] add the new release to upgrade.sh in [postmarketos-release-upgrade](https://gitlab.postmarketos.org/postmarketOS/postmarketos-release-upgrade/)
- [ ] bump SCRIPT_VERSION, tag a new release
- [ ] package it for edge (make MR), backport it to the new release, but NOT to the old release yet (otherwise users may upgrade by accident, without realizing that the new version is not out yet!)
- [ ] adjust CI of postmarketos-release-upgrade to test the new release too (git grep for the previous release to see what needs to be adjusted)

### Branch phase

#### Rebase on master
- [ ] `git checkout vYY.MM`
- [ ] `git rebase -i origin/master`
- [ ] temporarily enable force-push for the vYY.MM branch
- [ ] `git push --force-with-lease`
- [ ] disable force-push for the vYY.MM branch again

#### Update BPO config
- [ ] update bpo's images config to build images for the new branch for all devices in community and main, except for:
  - qemu-*
- [ ] bpo: configure the new branch to be not WIP anymore
- [ ] roll-out bpo changes

#### pmb release done?
- [ ] ensure that a pmbootstrap release been made with the apk-tools min version change

### Test phase
- [ ] Create an issue in pmaports with a checklist of devices and UIs in main and community
  - Tag the testers of each device and UI
  - Ask them to verify that the images work as expected
- [ ] Announce the new phase in the testing chat - and ask them to do the testing within one week, as in the timeline.
- Prioritize merging fixes from maintainers (they do the heavy lifting in the testing and fixing phase, see timetable)
- Make sure to properly cherry pick fixes from MRs to edge, if they are intended for the upcoming release
- [ ] add new version to the pmaports gitlab issue template (.gitlab dir)

### Release phase
- [ ] Did a reasonable amount of devices get tested? (we may consider dropping devices that were not tested)
- [ ] Make sure all fixes are in
- [ ] Make sure new images are generated *with* the fixes (unless it's a fix for something that doesn't impact the experience much and is fine to get with the first update after installing)
- [ ] Announce the new phase in the testing chat, together with the planned date of blog post release (and testing)

#### Write blog post
- [ ] look at previous release blog posts for inspiration, then prepare a MR with the following changes.
  - [ ] update config/download.py in postmarketos.org.git:
    - [ ] latest_release
    - [ ] update devices and categories. only list the ones where we actually build images.
- [ ] write a blog post for the new release:
  - [ ] Highlight major changes since the last release
  - [ ] Mention new devices, and total list of devices
    - [ ] Count devices that have their own wiki page as separate device
    - [ ] E.g. OnePlus 6, 6T are two devices (two wiki pages), but variants of "Samsung Galaxy A3 (2015)" are one device (one wiki page)
    - [ ] Don't count/list devices for which we don't build images (e.g. qemu-amd64)
  - [ ] Explain upgrade path (previously: [Upgrade release](https://wiki.postmarketos.org/wiki/Upgrade_release), maybe just update that wiki page and link to it again)
  - [ ] Adjust the homepage config to point to the new release in the downloads page
  - [ ] Add some cool photos
  - [ ] Submit the blog post as MR to postmarketos.org.git. Make sure the team sees it.
  - [ ] Wait for reviews

#### Release!
- [ ] Backport the new postmarketos-release-upgrade version that allows upgrading to the new release, to the previous release
- [ ] Add the branch to pkgs.postmarketos.org
- [ ] Merge the blog post
- [ ] Edit channels.cfg, change descriptions:
  - [ ] New release: "Latest release / Recommended for best stability"
  - [ ] Old release: "Old release (supported until YYYY-MM-DD)" (one month from date of the release)
- [ ] Update the [Releases](https://wiki.postmarketos.org/wiki/Releases) wiki page
  - [ ] Move the new release to the list of active releases, link to the blog post
  - [ ] Add a supported until date for the old release (but keep in the "active" list for now)
- [ ] Update [Template:Latest stable release](https://wiki.postmarketos.org/wiki/Template:Latest_stable_release) on the wiki with the new version
- [ ] Update "Default description template for issues" in pmaports (.gitlab dir)
  - [ ] In "On what postmarketOS version did you encounter the issue?", change:
    - [ ] previous release: add " (supported until YYYY-MM-DD)"
    - [ ] add the new release
- [ ] Put a reminder in your calendar to drop support for the old release in one month (see below)
  - [ ] create a new issue with dropping the old release ([template](https://wiki.postmarketos.org/wiki/Creating_a_release_branch#Dropping_phase))
- [ ] Create an issue for the next release notes

Drop phase

A month after a new release has been published:

- [ ] make the postmarketos-upgrade-gtk3 package available in the old release, and let all postmarketos-ui- packages depend on it (see git log of previous EOL branch)
  - [ ] ensure it builds locally with pmbootstrap
  - [ ] push it to the branch
  - [ ] make sure bpo built and released the updated packages
- [ ] drop the old release from [monitoring](https://gitlab.postmarketos.org/postmarketOS/monitoring)
- [ ] drop the "oldold -> old" release check from [postmarketos-release-upgrade](https://gitlab.postmarketos.org/postmarketOS/postmarketos-release-upgrade/) CI
- [ ] bpo: configure images so they don't get built for the old release anymore
- [ ] bpo: configure branches so we don't try to build packages for old branches anymore
  - e.g. on startup all branches are checked for new packages, we should keep the amount of branches that get checked minimal
- [ ] pmaports.git channels.cfg: change description:
  - "Old release (unsupported)"
- [ ] Update [Releases](https://wiki.postmarketos.org/wiki/Releases), move the release from active to old
- [ ] Go through issues assigned to the old release
  - e.g. https://gitlab.postmarketos.org/postmarketOS/pmaports/-/issues?label_name[]=release-v21.03
  - close or re-label them as it makes sense
- [ ] remove images for the previous releases, they take up a lot of disk space and people can build their own images with pmbootstrap if needed

Maintenance

Cherry-picking commits from master

  • In merge requests, that shall be cherry picked, add the backport-to-vYY.MM label.
  • If the new release is not finished, backport the patch to the branch right after merging.
  • If the new release is finished, add it to the service pack branch and issue (see creating a service pack)
  • It would be best if the person that merged the patch did the backport, but the author of the patch should double-check and do it in case it wasn't done, just to be sure.
  • Use git cherry-pick -x ffffffff (insert commit to cherry pick accordingly). The -x will add a (cherry picked from commit ffffffff) line to the commit message.
  • Cherry picked commits shall not be squashed, then it's hard to understand which commits were already picked and which were not.
  • If git reports conflicts, resolve them.
    • If you have cherry-picked a commit, that has touched a lot of devices that don't exist in the stable branch, then you can use git rm $(git status | grep "deleted by us" | cut -d ':' -f 2).
    • Look at the git diff to make sure that the result is as expected.
  • If it's something non-trivial, then make a merge request for the cherry-picked commits so we see that it was done correctly, it builds and that we may test the packages before merging.
  • Avoid cherry-picking multiple patches that touch the same pmaports in the wrong order (related comment).
Retrieved from "https://wiki.postmarketos.org/index.php?title=Creating_a_release_branch&oldid=66176"