We need to transition the release post process from the `www-gitlab-com` project to the `docs-gitlab-com` project. As part of that effort, we need a new publishing process. ## Target dates - 2026-05-01 - Process outlined (description with details) - 2026-05-21 - 19.0 release - 2025-05-22 or earlier - Announce new process ## Related work - 19.0 transitional process: #643+ - RSS feeds: #637+ - Leaf bundle implementation (19.1 improvement): #641+ - How to create notes for `https://gitlab.com/gitlab-org/gitlab/-/releases` and `gitlab-foss`: #642+ - In-app What's New: https://gitlab.com/gitlab-org/gitlab/-/work_items/597533+ - Localization: #624+ ## Process ### Summary | **When** | **What** | **Who** | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | -------------- | | Ongoing | Label and format epics and issues. | PM | | Ongoing | Add release notes to release file. | PM | | Ongoing | Review and merge release notes MR. | PM/EM/TW | | Release week before release day | Final review of release notes, prep for release, create directory and file for the upcoming release. | TW | | Release day when package is up | Merge the release notes MR. | TW | ### Details #### Create release notes <details> <summary>Expand</summary> Before the release, the PM adds their feature to the single Markdown file for the release, then assigns it to a writer for review. This was previously an [automated process](https://handbook.gitlab.com/handbook/marketing/blog/release-posts/#release-post-item-generator), and maybe can be automated again as part of the [Future improvements](https://gitlab.com/groups/gitlab-org/-/work_items/21822) epic. Content is stored in [gitlab-org/gitlab](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/releases). Each major version has a separate directory: `doc/releases/{major_version}/`. For example: `doc/releases/19/`. Each monthly release has a single Markdown file in that directory. </details> #### Review release notes <details> <summary>Expand</summary> After the MR is created, the writer reviews the metadata and content in the release notes. We can almost completely reuse the process outlined in the [Release-Post-Item](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/.gitlab/merge_request_templates/Release-Post-Item.md) MR template. Validation should be added where possible. In particular, categories must be validated — see https://gitlab.com/gitlab-org/gitlab/-/work_items/599192. After review, writers can merge immediately, or hold off until any point before publishing. Holding off might be helpful if the team expects further edits or changes. </details> #### Edit existing release notes <details> <summary>Expand</summary> Any edits to previously merged release notes (eg. delaying to a later release or fixing body text) need to be manually adjusted and submitted to a writer to merge. The MR can be created by anybody. If this happens before the release is published, the changes won't impact anything else. After release day, this will likely cause the RSS feed to regenerate. We should consider this further. </details> #### Publish release notes <details> <summary>Expand</summary> During release week, the TW release manager performs a final review and creates an MR to publish the release notes. This can be done at any point, but the MR can't be merged until the actual release goes live. We can use the existing Release post structural check schedule for this. In the same MR, the TW release manager also creates the boilerplate for the following release. For example, when merging changes for 19.4, create the file for 19.5. This could be automated in the future. </details> ## Implementation 1. Create process for monthly release 2. Ensure the RSS feed works with this solution. #637+ 3. Create process documentation - Modify the [TW release](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/.gitlab/issue_templates/release.md) issue template to reflect new process. - Transfer to the `gitlab-org/gitlab` repo and modify [Release-Post-Item](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/.gitlab/merge_request_templates/Release-Post-Item.md) MR template to reflect new process. - Update [handbook](https://handbook.gitlab.com/handbook/marketing/blog/release-posts/) <hr> ## Old notes <details> The PMs should be creating epics and issues for the features for each release. The docs team will take these epics/issues and based on labels, convert them to a monthly release post page on the docs site. ### Field mapping Query all epics and issues for the milestone that are labeled ~"release post item". Then, use these labels to build the page. [For example, here are the results for 19.0](https://gitlab.com/gitlab-org/gitlab/-/work_items?sort=created_date&state=all&label_name%5B%5D=release%20post%20item&milestone_title=19.0&first_page_size=20). NOTE: All issues must be public! Confidential issues should not be included. | Label | Used for | |---|---| | ~"release post item::top" ~"release post item::primary" ~"release post item::secondary" | Use for sorting, top, then primary, then secondary by buckets | | stage (labels look like ~"stage::create") | Use for sorting, group into the buckets below | | offerings ~"GitLab.com" ~"GitLab Self-Managed" ~"GitLab Dedicated" | The labels are not rendering here but we do have them. People might not be using them consistently, we'll have to educate. | | Tier: ~"GitLab Free" ~"GitLab Premium" ~"GitLab Ultimate" | Use for the **Tier** | Not labels, but other content: | Text | Used for | |---|---| | title | Use for the H2 | | description | Use for description | | documentation link | use for the docs link, might have to make relative | And into text: ``` On <date>, GitLab <x.y> was released with the following features. In addition, we want to thank all of our contributors, including this month's notable contributor. ``` ### Current structure The `feature_content` method (in `lib/release_posts/post_entry.rb`) generates a YAML block with these fields: * title * description * image/video * **`available_in`** - Tier availability (core, premium, ultimate), derived from labels like `GitLab Core`, `GitLab Premium`, `GitLab Ultimate`, or `GitLab Free` on the issue/epic * **`gitlab_com`** - Defaults to `true` * **`self_managed`** - Defaults to `true` * **`gitlab_dedicated`** - Defaults to `true` * **`gitlab_dedicated_for_government`** - Defaults to `true` * **`add_ons`** - Defaults to an empty array `[]` * **`documentation_link`** - Automatically extracted from the issue/epic description by finding URLs starting with `https://docs.gitlab.com/` * **`reporter`** - Set to the PM username for the group (looked up from `stages.yml` team data), falling back to `GITLAB_USERNAME` env var, then `gitlab_bot` * **`stage`** - Derived from the `devops::*` stage label on the issue/epic * **`categories`** - Derived from `Category:*` labels on the issue/epic, cross-referenced with the categories data file * **`issue_url`** / **`epic_url`** - The web URL of the source issue or epic (whichever applies) </details>