Analysis: Increase transparency on the monthly release preparation

Context

gitlab-com/gl-infra/software-delivery&1 (closed) proposes to move the active stable branch generation one week earlier in the release schedule to allow for thorough testing and timely backports. This will increase the quality, safety, and reliability of the monthly release while enabling a better developer experience and confidence.

Current workflow New workflow
Screenshot_2025-06-24_at_11.07.01_a.m. Screenshot_2025-06-24_at_11.10.02_a.m.
  • 3rd Tuesday of the month: RC and stable branch creation
  • 3rd Wednesday of the month: Final tag
  • 3rd Thursday of the month: Release
  • 2nd Wednesday of the month: Initial RC and stable branch creation
  • Up to 3rd Tuesday of the month: Bug fixes are backported to the active stable branch
  • 3rd Tuesday of the month (Late EMEA or early AMER): Final RC is created
  • 3rd Wednesday of the month Tag the final version
  • 3rd Thursday of the month Release

Problem

Currently, it is hard for engineers to figure out if a code change was included in the monthly release:

  • There is no single source of truth process to check if a merge request makes it into the cut
  • In the current monthly setup, multiple Slack announcements are made throughout the monthly run-up to highlight the 'minimum commit' and the 'candidate commit'; however, the meaning of those concepts is hard to grasp for folks outside Delivery.
  • During the run-up for the release, engineers make a last-minute request to release managers to include a change.
  • Release managers often get the question of when the 'cut-off' date is.

Changing the monthly release process will likely increase the confusion engineers have around monthly release dates.

Discussion: How to increase transparency about the changes included in a monthly release?

Engineers require transparency on the monthly release preparation, particularly a date for each monthly release that guarantees inclusion. There are several angles to transparency: tooling, documentation, and awareness.

Tooling

Multiple tools are available to verify if a merge request will be included in the monthly release:

The above tooling is documented in different places (handbook, release/docs repo). This is a suboptimal experience; it makes it difficult for engineers to find the documentation. Likely, this tooling should be listed and explained in a single section in the Release handbook.

On the other side, the Release dashboard reflects monthly and patch release due dates. However, it states a Release date, not a due date for changes to be included in the monthly or patch.

Documentation

The handbook offers a quick summary

The documentation could use a revamp to link all the available tooling and explain the timelines

Awareness

Once the tooling has been updated and the documentation has been revamped, engineers need to be aware of these changes. This will be part of the rollout of the early branch and the maintenance policy. A LevelUp training will increase and measure engagement.

Exit criteria

Documentation

  • Have a section in the handbook that details all the ways to check if a merge request made it into the monthly #21315 (closed)
  • Update monthly release documentation on the handbook #21122
  • Add documentation on how to backport bug fixes to the ongoing stable branch #21121

Tooling

Awareness

  • Prepare a LevelUp training to broadcast and guarantee that engineers have taken. #21252
Edited by Mayra Cabrera