Creating a release branch

From postmarketOS
(Redirected from Create a release branch)
Jump to navigation Jump to search

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.


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 release party chat.

week(s) current date
0 - 5

(~6 weeks)

2021-10-16 Edge preparation phase

We get word that Alpine folks are working on a new release.

Tasks for maintainers of devices (and some UIs/packages that we want to have especially tested, e.g. Sxmo) (@Maintainers):

  • ensure that their stuff is stable in postmarketOS edge now and consider not accepting risky patches anymore (especially the later we get into this cycle)
  • check your calendar to verify that they will have time to test the release in the testing and fixing phase.
  • If a holiday is planned or similar and you don't have time, try to find somebody else who can commit to doing the testing instead or, tell us when you will be back so we can adjust the schedule.
  • reply back in the dedicated issue whether you will have time for testing (if we don't hear back, we'll probably have to drop the device; note that devices in main always have 2 maintainers so this should never happen there)
6 - 8

(2 weeks)

Branching phase
  • Alpine release gets published
  • postmarketOS core team works on new release branch (see detailed list below)
  • at the end of the phase, binary packages and images will be available
  • if we did not hear back from device maintainers in the past 6 weeks, we try to find a new maintainer that could take over or if that fails, we must drop the device.

(1 week)

Testing and fixing phase (@Maintainers)

In this one week, do the following:

  • test a fresh installation on devices you maintain (for maintainers of other things than devices, test your UI / packages)
  • if you encounter issues, submit patches to fix them. these fixes must go through master, just mention in the MR that they should be cherry picked to the new stable branch and we'll do that
  • report back in the dedicated issue when everything is working

(1 week)

Building phase

We make sure all fixes are in, new images got generated etc.


(1 week)

Release phase

We put the blog post out, celebrate with party hats and get wasted. (as requested, let's do this in a conference call :D)


(1 week)

Dropping phase

One month later, support for the old release gets dropped.

Release Cycle Tasks for Core Team Members

Edge preparation phase

  • Create an issue where device maintainers can reply back that they will test their device for the new release.
  • Announce in the release party chat, that the new pmOS release cycle begins and get everybody excited!
    • Point them to the timeline here and ask them to carefully read the tasks on the list, what's marked with @Maintainers.
    • Point them to the issue you just created.

Wait for Alpine

  • Wait until Alpine creates their 3.14-stable branch in aports.git (or whatever the next release is based on).
    • Alpine's workflow is setting up new builders and build edge from scratch first, and only after that is done, the new branch gets created. (postmarketOS workflow is the other way around, we create the branch first, then build all packages from there.)
    • There is no fixed timeline from when the builders start up to when the branch gets created, typically a few weeks.
    • The builder status can be followed at

Branching phase

  • Check the issue you created earlier. Did all device maintainers reply that they have time or appoint somebody else? If not, can you find somebody? Otherwise we need to drop the device from the release.
  • Announce the new phase in the release party chat

pmbootstrap: adjust config

  • add apk-tools min version
  • create a merge request
  • when CI passes, merge it (it's a trivial change)
  • make a new pmbootstrap release now (or soon if now does not make sense).
    • 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.

pmaports: create branch and initial changes

  • git checkout -b vXX.YY master
  • Create a === Branch vXX.YY from master === commit (third line: Related:
    • Remove channels.cfg (should only be in master)
    • Change channel=edge to channel=vXX.YY in pmaports.cfg
    • replace master in .gitlab-ci.yml (example)
  • set version info for /etc/os-release in main/postmarketos-base/rootfs-etc-os-release, bump pkgrel and commit
  • 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
  • git push

pmaports: remove packages / aportgen

  • git checkout vXX.YY
  • remove packages:
    • device/testing, device/unmaintained
    • cross/*-armhf, cross/*-x86
    • cross/gcc4*, main/gcc4, cross/gcc6*, main/gcc6
    • main/postmarketos-ui-asteroid (no smartwatches are useful on stable branches at the moment)
  • run pmbootstrap aportgen for packages in cross
    • may not be necessary if the branch was just created, since the packages on edge and the new stable branch will be the same
  • git push

bpo: adjust config

  • add the branch to the config, for x86_64 only, ignore_errors: True
    • bpo/config/const/
  • make a merge request, wait until CI passes
  • merge it and 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
    • 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.
  • wait until all packages for x86_64 are built and published
  • after x86_64 is published, activate armv7, aarch64 arches in bpo (if you activate them before, the builds will fail due to missing cross compilers!)
  • fix up ARM packages too
  • wait until all packages for ARM are built and published

Images: config & issue

  • update bpo's images config to build images for the new branch for all devices in community and main, except for:
    • qemu-*
    • arrow-db410c
  • create an issue in pmaports with a checklist of devices in main and community
    • tag the maintainers of each device
    • ask them to verify that the images work as expected

Adjust CI

  • disable x86, armhf in .gitlab-ci.yml on the release branch
  • make sure pmaports.git CI runs through on the new branch. 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
  • adjust monitoring to run on the new release and make sure it passes

Testing and fixing phase

  • Announce the new phase in the release party chat (this one is especially important for all the maintainers!) - 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

Building phase

  • Did everybody test their devices? If not, we need to drop them.
  • Announce the new phase in the release party chat
  • 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)

Release phase

  • Try to plan a "release party" conference call date, to take place when the blog post is out.
  • Announce the new phase in the release party chat, together with the planned date of blog post release.

No more WIP

  • bpo: configure the new branch to be not WIP anymore
  • ensure that a pmbootstrap release been made with the apk-tools min version change

Write blog post

  • look at previous release blog posts for inspiration, then prepare a MR with the following changes.
    • update config/ in
      • latest_release(_title)
      • 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, Arrow DragonBoard 410c)
    • Explain upgrade path (basically Upgrade release this page for now)
    • Adjust the homepage config to point to the new release in the downloads page
    • Add some cool photos (Martijn takes great photos, maybe ask him ;) )
    • Submit the blog post as MR to Make sure the team sees it.
    • Wait for reviews


  • Merge the blog post
  • Post to mastodon etc. and add the comment links at the bottom
  • 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 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 "Default description template for issues" in pmaports
  • Put a reminder in your calendar to drop support for the old release in one month (see below)
  • Ping Martijn to add the branch to config
  • Do the conference call in jitsi and celebrate the release :)

Dropping phase

A month after a new release has been published:

  • Announce the new phase in the release party chat
  • drop the old release from monitoring
  • 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, move the release from active to old
  • Update "Default description template for issues" in pmaports
  • Go through issue assigned to the old release


Cherry-picking commits from master

  • In merge requests, that shall be cherry picked, add the backport-to-vXX.YY 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).