Gitlab hero border pattern left svg Gitlab hero border pattern right svg

GitLab Release Posts

  1. You are here:
  2. Handbook
  3. Marketing
  4. Blog Handbook
  5. GitLab Release Posts

Release posts

Release posts are blog posts that announce changes to the GitLab application. This includes our regular cadence of monthly releases which happen on the 22nd of each month, and patch/security releases whenever necessary.

Release posts follow a process outlined here, and the templates that are used to create them also highlight what needs to be done, by who, and when those items are due.

Templates

The sections below also link to these templates, but they're provided here for quick reference.

Monthly releases

Monthly releases are blog posts with an exclusive layout aiming to apprise the reader of the changes, new features, and other considerations for the new release that comes out on the 22nd of every month. They follow a process that involves collaboration across many different roles, and each persona's responsibilities are outlined on this page.

At a high level, the process is:

Date Step
By the 7th The Release Post Manager creates a branch on www-gitlab-com and MR in that project that will collect all the release post items in to a single blog entry
1st - 10th PMs contribute individual MRs for all of their content blocks (top/primary/secondary features, deprecations, removals, and upgrades) as release post items in the /data/release_posts/unreleased directory. For primary items, PMs will also add the item to features.yml.

EMs can also contribute individual MRs for deprecations, removals, and upgrades as release post items in the /data/release_posts/unreleased directory.

PMs add recurring content blocks for Omnibus improvements, deprecation warnings, and more
by the 16th PMMs, TWs, and PM Directors review individual release post items MRs

EMs and PMs contribute to MRs for Performance Improvements and Bug Fixes
by the 17th EMs merge those MRs in to master as the features they represent are merged in to the GitLab codebase.

Release Post Manager merges recurring content blocks for performance improvements and bug fixes. Any MRs added after the 17th should be submitted against the Release Post branch, not Master.
on the 18th At 8 AM PT, (3 PM UTC) the Release Post Manager aggregates all the content blocks by updating the release post branch from the master branch, and moving all the "unreleased" items into the release post branch for final content assembly.

The Release Post Manager adds the MVP for the release and selects a cover image

The Messaging lead picks a top features and/or themes to highlight and finalizes the introduction content
18th - 20th The Release post manager, Messaging Lead, and TW Lead perform final reviews/revisions to ensure everything is ready to publish.

Any changes after 8 AM PT (3 PM UTC) on the 18th will be done via the release-X-Y branch, not master branch, and is subject to approval by the Release post manager.
22nd of Month The Release post manager, publishes the blog post to master on the morning of the 22nd, immediately following the package itself being published by the Release team The GitLab.org Releases page will also populate the changelog via the process outlined in gitlab!44837

Note: The specific steps that should be followed, when they are due, and the order they should be followed in are described in the Monthly release post MR template and the Monthly release post item MR template.

Participants

Release Post Manager

Each month a Product Manager will lead the release post, as defined in the Release Post Scheduling page. The Release Post Manager is listed as the Author of the release post when the post is published. Each month a Product Manager also acts as a shadow to support the Release Post Manager tasks if needed, act as back up on decisions in absence of the Release Post Manager and prepare to run the next release post. By shadowing the month prior to leading the effort, Product Managers are prepared and aware of any shifts in processes or optimizations needed since the last time they participated.

Product Managers can volunteer for any release that doesn't have someone assigned yet. To add yourself as release post manager or release post manager's shadow, simply do an MR to add your name to Release Post Scheduling page. Otherwise, PMs will be assigned using a fair scheduling principle:

  1. Members that never managed a release post before
  2. Members that have the longest interval since they managed their last release post

After joining the company, there is a grace period of a few months where the new Product Manager will get up to speed with the process, then they will be scheduled to manage a release post.

Adding members to the list is a shared task, and everyone can contribute by following the principle described above. Scheduled people are pinged in the merge request to make them aware. They don't need to confirm or approve, since they can always update the list if they are not available for the given release post.

Important: if you're scheduled for a given month and you can't make it, because you're on vacation, overloaded, or for any other reason, that is okay, as long as you swap the release post manager role with someone else before creating the merge request and starting the whole process. If you take it, you're responsible for the entire process and must be available to carry it out until the end.

The Release Post Manager is accountable for:

The initial steps of creating a release post branch and the release post merge request are explained below. All subsequent steps for Release Post Manager are documented as checklist items in the merge request that gets created below.

Important: Please check beforehand if you have merge rights to the www project. If you don't, ask someone to grant you access or pair with someone else to merge the post with you on the 22nd. If someone else merges it, make sure you're available to follow up with anything that might come up in the last minute.

Create your release post branch and required directories/files

Note: In the following sections we refer to the GitLab version as X.Y and the date of the release as YYYY/MM/22. You should replace those values with the current version and date. The day will always be the 22nd, so no need to change that.

There are two ways to create the initial monthly release post in the about.GitLab.com repository: a) using a script and b) manually. The script does exactly what you would manually, but automates the process.

First way: using a script
  1. Make sure you have set everything up to contribute to the about.GitLab.com repository.

  2. Locally, in a terminal, run the task:

    bundle exec rake "release:monthly"

    You will be asked to submit the release post date (in ISO format) and the GitLab version (in major.minor format). If any of the two are wrongly submitted or the release branch already exists, the task will abort.

  3. Push the branch that was created and follow the link to create the merge request.
Second way: manually

The manual way can be done either locally or using the GitLab Web IDE:

  1. Create a new branch release-X-Y from master
  2. On release-X-Y branch, create the blog post file, containing the introduction and the blog post frontmatter information:
    1. In source/releases/posts/ directory, add a new file called YYYY-MM-22-gitlab-X-Y-released.html.md by copying the monthly release blog template.
  3. On release-X-Y branch, create the release post data directory, to which features and other data will be added:
    1. Create a new directory X_Y in the data/release_posts directory.
    2. Copy data/release_posts/unreleased/samples/mvp.yml into data/release_posts/X_Y/mvp.yml.
    3. Copy data/release_posts/unreleased/samples/cta.yml into data/release_posts/X_Y/cta.yml.

Important! Please use the most recent templates for each of these files. They can be found when browsing the repository in the master branch.

Create the release post MR

Create a merge request with the introductory changes after the previous post has been merged and before the feature freeze date to make the post available to receive contributions from the team:

  1. The source branch must be release-X-Y and the target branch master.
  2. Set the title to WIP: Release post - GitLab X.Y.
  3. Confirm that "Delete source branch when merge request is accepted" is selected.

  4. Use the release post template for your MR.

    release post MR template

Important: all the files related to the release process, including data/features.yml, data/mvps.yml and source/includes/home/ten-oh-announcement.html.haml must be committed in this MR.

Create MRs for Bugs and Performance Improvements

Create two merge requests that simply contain the sample templates for these content blocks. Having separate MRs (from the main Release Post MR) allows discussions to be easier to follow and the contribution process to be simpler.

Note: The Release Post Manager is not responsible for creating any content here, but only creating the MRs and adding the initial template so that there's a single place for others to add their own content.

  1. For each bug and performance MR, create a new branch from master. Name the branches release-X-Y-bugs and release-X-Y-performance-improvements
  2. Open a merge requests targeted at the master branch. Name the MRs WIP: release-X-Y-bugs and WIP: release-X-Y-performance-improvements and use the Release-Post-Bug-PerformanceImprovement-Block template
  3. Assign appropriate milestone and labels: release post release post item Technical Writing
  4. Confirm that "Delete source branch when merge request is accepted" is selected.
  5. Add bugs.yml and performance_improvements.yml to the corresponding release-X-Y-bugs and release-X-Y-performance-improvements branches to data/release_posts/13_1

Merge individual items in to your branch

Important: This procedure applies until the 17th, at 11:59 PM PT (6:59 AM UTC). After this time, anyone who wants to include a change in the upcoming release post can either coordinate updates directly on the release post branch with the Release Post Manager or submit it in a separate MR, targeting the release-X-Y branch, and assign it to the Release Post Manager to merge. For more information, see our documentation ho how to Develop on a feature branch.

When it is time to assemble the release post, this will be done by moving the content block files from data/release_posts/unreleased to data/release_posts/X_Y, and images from source/images/unreleased to source/images/X_Y.

Those block items comprise of the release post items that each PM creates for each feature.

The bin/release-post-assemble script makes this easy to do:

# Checkout the release branch
git checkout release-X-Y

# Pull any updates to the release branch
git pull

# Fetch and merge updates from master, including new unreleased features
git pull origin master

# Move release post items and images to the release director
bin/release-post-assemble

# Push the changes
git push

Communication

The release post manager, the Messaging lead and the TW lead will need to communicate about topics that are related to the release post but not relevant to all participants in the main Slack release post channel. The Release Post Manager will create a Slack channel called "X-Y-release-post-prep to faciliate communication specific to the release post leads, which will be utilized till the 21st to minimize noise in the main release post Slack channel. On the 22nd, this channel will be abandoned and all communication will default to the main release post Slack channel for the final day of collaboration.

Content reviews

The due dates for various reviews across all participants can be found on the release post MR and release post item MR templates (#templates). PM contributors are encouraged to cease attempts to add new content blocks after the final merge deadline of the 17th, and especially after final content assembly happens at 8 AM PT (3 PM UTC). But if highly impactful features are released it is up to the discretion of the Release Post Manager to work with the PM and Messaging lead to add more content blocks up until the 21st.

Keeping an eye on the various content reviews (TW, PMM and Director) for the individual release post items (content block MRs) is the responsiblity of PM contributor. However, it is recommended that the Release Post Manager keep an eye on how many items are not yet marked with the Ready label on the 10th of the month or not yet merged on the 16th of the month, and check in with PMs in Slack Release Post channel to support and clear hurdles if needed. A really easy way to do this is to keep your eyes on the Preview page and copy edit and link check items as new items appear.

The content review of the Performance Improvements and Bug Fixes MRs are the responsibility of the Release Post Manager and the TW Lead.

The review of all content for quality, including the marketing intro, is recommended for the Release Post Manager to keep things smooth, since it is the Release Post Manager's responsibility to make sure all content is completed until by the 20th of the month, ensuring a one day buffer is left for final error fixes and small improvements.

Next steps

Now that you have created the release post MR, refer to the checklist in the MR for each action that you need to take and the due dates of each action.

Updating Release Post Manager assignments

To update the release post managers list, edit the data file below.

PM Contributors

Product Managers are responsible for raising MRs for their content blocks and ensuring they are reviewed by necessary contributors by the due date. These are mostly added by the Product Managers, each filling up the sections they are accountable for, but anyone can contribute, including community contributors. Content blocks should also be added for any epics or notable community contributions that were delivered.

Contribution instructions

In parallel with feature development, a merge request should be prepared by the PM with the required content. Do not wait for the feature to be merged before drafting the release post item, it is recommended PMs write Release Post Item MRs as they prepare for the milestone Kickoff.

Important: This procedure applies until the 17th, at 11:59 PM PT (6:59 AM UTC). After this time, anyone who wants to include a change in the upcoming release post can either coordinate updates directly on the release post branch with the Release Post Manager or submit it in a separate MR, targeting the release-X-Y branch, and assign it to the Release Post Manager to merge. For more information, see our documentation of how to Develop on a feature branch.

Key dates
Instructions

Content

Be sure to reference your Direction items and Release features. All items which appear in our Upcoming Releases page should be included in the relevant release post. For more guidance about what to include in the release post please reference the Product Handbook.

When writing your content blocks, be sure to reference Writing release blog posts and Writing about features to ensure your release post item writeups align with how GitLab communicates. This will also ensure a smoother and more speedy review process for your release post items.

PM contributors are encouraged to use discretion if wanting to add new content blocks after the final merge deadline of the 17th, and especially after final content assembly happens at 8 AM PST (3 PM UTC). But if if highly impactful features are released that can not wait till the next blog post, PMs shoudl reach out and coordinate with the Release Post Manager. It is up to the discretion of the Release Post Manager to work with the PM and Messaging lead to add more content blocks up until the 21st.

Primary vs Secondary

When creating your content for a Release Post item you'll need to determine if it's a Primary or Secondary feature. Do this in collaboartion with your PMM counterpart and reference this guidance if you're unsure:

A feature should be Primary if the feature…

Reviews

PM Director/Group Manager and PMM reviews are highly recommended, but the Tech Writer review is the only one required for inclusion in the Release Post. The Tech Writing review should be focused on looking for typos, grammar errors, and helping with style. PMs are responsible for coordinating any significant content/tech changes. Communicating priority about which release post items are most important for review will help Product Section leads, PMMs, and Tech Writers review the right items by the 10th of each month, so ensure the proper labels ares applied to the MR and assign reviewers to the MR when it is ready for them to review (ex: Tech Writing, Direction, Deliverable, etc).

Recommendations for optional PM Director/Group Manager and PMM Reviews:

As Director and PMM reviews are not required, but recommended, PMs should consider a few things when determining which content blocks to request a review for:

If the answer to any of these is "yes", it is recommended that you coordinate with your Director and PMM to review the content block by the 16th. As the PM it is your responsibility to communicate what MRs need review from the TWs, PMMs, and Directors as well as the MRs relative priority if you have multiple content block MRs that need reviews.

Merging Content Block MRs

Engineering Managers are the DRIs for merging these MRs when the feature is merged in to the codebase itself. This allows all of the relevant parties (Product Managers, PMMs, Section Leads, Technical Writers) to have enough time to review the content without having to scramble or hold up engineering from releasing a feature.

To enable Engineering Managers to merge their feature blocks as soon as an issue has closed, please ensure all scheduled items you want to include in the release post have content blocks MRs created for them and have the Ready label applied when content contribution and reviews are completed.

Reviwing, editing and updating merged content blocks

After content block MRs are merged, they can be viewed on the Preview page and should be updated/edited via MRs to master up until the final merge deadline of the 17th. Starting on the 18th, content block MRs should be viewed in the Review app of the release post branch after final content assembly, and updated/edited on the release post branch by coordinating with the Release Post Manager.

Accountability

You are responsible for the content you add to the blog post. Therefore, make sure that:

As noted in the Release Post Item template:

Write the description of every feature as you do to regular blog posts. Please write according to the markdown guide.

Important! Make sure to merge master into the release post branch before pushing changes to any existing file to avoid merge conflicts. Do not rebase, do git pull origin master then :wq.

PMs checklist

Once the PMs have included everything they're accountable for, they should check their item in the release post MR description:

PMs check list

By checking your item, you will make it clear to the Release Post Manager that you have done your part in time (during the general contributions stage) and you're waiting for review. If you don't check it, it's implicit that you didn't finish your part in time, despite that's the case or not.

Once all content is reviewed and complete, add the Ready label and assign this issue to the Engineering Manager (EM). The EM is responsible for merging as soon as the implementing issue is deployed to GitLab.com, after which this content will appear on the GitLab.com Release page and can be included in the next release post. All release post items must be merged on or before the 17th of the month. If a feature is not ready by the 17th deadline, the EM should push the release post item to the next milestone.

Notes for PMs

Vacations:

If you are on vacation before/during the release, fill all your items and create placeholders in the release post Yaml file for all the items you cannot add for whatever reason. To complete them, and to follow up with all the content you are responsible for, assign someone to take over for you and notify the Release Post Manager.

Replies:

Please respond to comments in the MR thread as soon as possible. We have a non-negotiable due date for release posts.

Documentation:

Please add the documentation_link at the same time you add a content block to the release post. When you leave it to add it later, you will probably forget it, the reviewer will ping you later on during the review stage, and you will have little time to write, get your MR reviewed, approved, merged, and available in docs.gitlab.com.

Always link to the EE version of GitLab docs in the blog post, even if it is a CE feature.

Bugs:

It's the PMs discretion on which bugs or performance improvements to include in a release post. When evaluating what to include consider the following factors:

It's also recommended you collaborate with your EM in deciding what to include.

Messaging lead

Each month a Product Marketing Manager (PMM) will lead the messaging and positioning for the release post.

The messaging lead is responsible for:

Top three features

This section provides guidance on how to decide on top 3 features or themes and timelines:

Best practices for the release post:

Feature order

The messaging lead orders the primary features in the release post to align with the themes they've identified and incorporated into their introduction for the release post.

Content blocks are listed in the post in alphabetical order, so to order the content, add a 2-digit numerical prefix to the name of each individual content block file. Eg: 01_filename.yml, 02_filename.yml, etc.

Marketing coordination

PMM Reviewers

Messaging review

Each PM is responsible for pinging their PMM counterpart when they need a review on the messaging for a Release Post Item MR or changes to features.yml.

TW Lead

Note: Technical writers review the individual release post items according to the stage/group they are assigned to. Each month, one of the technical writers is also responsible for the structural check of the final release post merge request. This section is about the latter.

The TW Lead is responsible for a final review of:

While individual TW reviewers are responsible for reviewing the structure and content of individual feature items, the TW Lead still has overall responsibility for confirming that style and language remain reasonably consistent and that all links point to relevant content.

Structural check

A technical writer, once assigned to the release post merge request, will check the syntax and the content structure.

The checklist in the main release post merge request description will guide them through the structural check.

Given that the technical writing review occurs in release post items' merge requests, the purpose of the structural check is:

Pay special attention to the release post markdown file, which adds the introduction. Review the introduction briefly, but do not change the writing style nor the messaging; these are owned by PMMs, so leave it to them to avoid unnecessary back-and-forths. Make sure feature descriptions make sense, anchors work fine, all internal links have the relative path.

Making changes

Until the 18th, at 8 am Pacific Time, the TW Lead should be able to make changes directly to the release post. After that time, anyone who wants to include a change in the upcoming release may need to submit it in a separate MR, with a target of the release-X-Y branch. For more information, see our documentation ho how to Develop on a feature branch.

TW checklist

If the TW Lead identifies issues with the content when checking it for these items, they should at least inform the the responsible TW reviewer, as this can be useful feedback. Time permitting, the TW reviewer is more likely to create a better resolution.

Release post top feature

Pay close attention to the content of this item. As this will be the "headline" feature for the release, it's especially important "to get this right".

To identify the Top feature, look for top directly beneath features in the RP .yml file:

features:
  top:

Review the respective RP .yml file for at least the contents of the checklist. Each TW reviewer retains prime responsibility for each RP, Deprecations, Removals, and Upgrades.

Release post primary features

All release post primary features should already have been reviewed by the TW reviewer. If you find an issue, do work with the TW reviewer, if time permits.

To identify the primary features, look for primary directly beneath features in the RP .yml file:

features:
  primary:

Review the respective RP .yml file for at least the contents of the checklist.

Release post secondary features

All release post Secondary features should already have been reviewed by the TW reviewer. If you find an issue, do work with the TW reviewer, if time permits.

To identify the primary features, look for primary directly beneath features in the RP .yml file:

features:
  secondary:

Review the respective RP .yml file for at least the contents of the checklist.

Images or videos are not required for secondary features.

Frontmatter

In its frontmatter:

---
release_number: "X.Y"
title: "GitLab X.Y Released with Feature A and Feature B"
author: "Name Surname"
author_gitlab: gitlab.com-username
author_twitter: twitter-username
categories: releases
image_title: '/images/X_Y/X_Y-cover-image.ext'
description: "GitLab X.Y Released with XXX, YYY, ZZZ, KKK, and much more!"
twitter_image: '/images/tweets/gitlab-X-Y-released.jpg'
layout: release
featured: yes
# header_layout_dark: true #uncomment if the cover image is dark
# release_number_dark: true #uncomment if you want a dark release number
---

Layout:

The last two entries of the post's frontmatter give the option for a different layout. If you want to use a dark cover image, you'll need to uncomment header_layout_dark: true.

If you want only the release number to be dark, uncomment release_number_dark: true.

These two variables work independently; you can assign either of them or both of them to the same post.

Note: Because there are no individual TW reviewers for the performance improvements and bug fixes (#performance-improvements-and-bug-fixes) content block MRs, Engineering Managers and Product Managers will contribute to MRs created by the Release Post Manager. The MR will be assigned to the TW Lead by th 16th to review, mark with Ready label and assign to the Release Post Manager to merge.

Bugs MR

As the TW Lead, you're responsible for reviewing an MR created for bug fixes. This MR has not been reviewed by any other TW. For this MR, you'll check:

Performance Improvements MR

As the TW Lead, you're responsible for reviewing an MR created for performance improvements. This MR has not been reviewed by any other TW. For this MR, you'll check:

MVP entry

As the TW Lead, you're responsible for reviewing the entry for the MVP of the month. This MR has not been reviewed by any other TW. For this MR, you'll check this MR for:

TW Reviewers

Note: TW reviewers should not be confused with the TW lead.

Each person of the Technical Writing team is responsible for the review of each individual release post item that falls under their respective stage/group.

When the PM creates the release post item merge request, they should assign to the TW of their group for review (required). The process of the TW review is described in the release post item template.

Engineering Managers

The responsibilities of the Engineering Manager are documented in the Engineering Handbook.

Monthly release blog post sections

Introduction

The messaging lead writes the introduction for the release post.

Add the copy for the intro to the blog post file (YYYY-MM-DD-gitlab-X-Y-released.html.md), in regular markdown. This file linked at the top of the release post MR. E.g. GitLab 11.2 blog post file

Introductory paragraph

Introduction

The first paragraph is the one that catches the eyes of the reader, it should be punchy giving a summary of the most significant features. This first paragraph can then be used as a summary on the homepage and on social media. It should catch attention and cause the reader to want to read more.

The following paragraphs should highlight the business value of top 3 features and link to the feature description (link using the feature headings' anchors). It's important to highlight the pain points solved and the value the feature provides.

A final paragraph can give a shout out to additional features encouraging the reader to read the full release notes to learn about all the features have that shipped. It should also include the total number of new features being released, including bugs, performance improvements, and contributions from non-DevOps stages like Enablement. All of these should be listed in the release post, either as headers or bullet points.

@mention the PMs whose features are included the intro and ask them to review.

Examples of previous release post intros written by PMM:

CTA

Call-to-action buttons displayed at the end of the introduction. A CTA to the events page is added by default. Add webcasts, or custom buttons to this entry whenever necessary.

cta:
  - title: Join us for an upcoming event
    link: '/events/' # relative link
  - title: Lorem ipsum dolor sit amet
    link: 'https://example.com' # external link

MVP

To display the MVP of the month, use the example provided in this template, and adjust it to your case. Don't forget to link to the MR with the MVP's contribution.

mvp:
  fullname: Dosuken Shinya # full name
  gitlab: dosuken123 # gitlab.com username
  description: | # supports markdown. Please link to the MR with the MVP's contribution.
    Dosuken extended our [Pipelines API](http://docs.gitlab.com/ee/api/pipelines.html#list-project-pipelines)
    by [adding additional search attributes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9367).
    This is a huge improvement to our CI API, for example enabling queries to easily return the latest
    pipeline for a specific branch, as well as a host of other possibilities. Dosuken also made a great
    contribution last release, laying the foundation for
    [scheduled pipelines](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10133). Thanks Dosuken!

Suggestions should be ideally added along the month into the #release-post channel, as soon as you see a contribution, or a set of contributions that you think are great and should be taken into consideration for the choice. Every GitLab team-member and core team member is encouraged to add suggestions to the channel, always linking to issues and merge requests. If there are no MVP nominations by the 15th of the month, reaching out to the Core team #core in Slack for nominations is recommended.

Based on this discussion, the Release Post Manager will make a decision. They should not wait for consensus. There can only be one MVP.

The MVP will be prized with a gift from GitLab, usually a swag pack. :)

Important: the MVP section should briefly describe what the feature is about, link to the GitLab profile of the MVP, and link to the issue, MR, issue board, or epic that introduced the change that awarded by the MVP. If it is a major feature, it must be accompanied by a content block with a more detailed description linked from the MVP section. The MVP feature, as well as any other feature, regardless of who shipped it, must be documented and linked to the docs.

Important: remember to update data/mvps.yml with the new MVP.

Features

The most relevant features of the release are included in the post by product managers. Classify the feature according to its relevance and to where you want to place it in the blog post:

Top feature

The most important feature of the release, mentioned right after the MVP section. Images can be added at will in the description entry. A link to the documentation is required.

Primary features

Features with higher impact, displayed in rows after the top feature, with an image next to its text. An image accompanying the description is required. A video can also be added to replace the image.

Secondary features (other improvements)

Relevant improvements in GitLab. Image is not required, but recommended.

If the secondary feature is promoted to a primary feature, the PM or EM will be asked to supply an image on short notice.

Content blocks

Note: "Feature blocks" are now known as content blocks, as there are many that are not just features. For example, we include upgrade warnings, Omnibus installer improvements, and performance enhancements.

Use content blocks to add features or other content to the YAML data file. The layout will be applied automatically by Middleman's templating system.

Content blocks in the YAML data file contain the following entries, as exemplified below:

features:
  primary:
    - name: "Multi-Project Pipeline Graphs"
      available_in: [premium, ultimate]
      documentation_link: 'https://docs.gitlab.com/ee/ci/multi_project_pipelines.html#multi-project-pipeline-visualization-premium'
      image_url: '/images/9_3/multi-project_pipelines.png'
      reporter: bikebilly
      stage: secure
      categories:
        - "Application Security Testing"
        - "SAST"
      issue_url: 'https://gitlab.com/gitlab-org/gitlab/issues/1234'
      description: |
        Lorem ipsum dolor sit amet, [consectetur adipisicing](#link) elit.

Primary vs Secondary

The second line of the content block should indicate whether the feature is a primary or secondary feature. For primary features, use the primary key as shown in the sample content block above. For secondary features, replace the primary key with the word secondary.

Feature name

Use a short and strong name for all feature names.

Feature Availability

Use the following pattern to apply the correct badge to the feature (Core, Starter, Premium, Ultimate).

If the feature is available in GitLab.com, the badges for GitLab.com will be applied automatically according to the self-managed availability. For example, available_in: [premium, ultimate] will "turn on" the badges Premium, Ultimate, Silver, and Gold.

If the feature is not available in GitLab.com, e.g., LDAP and admin settings, use the tag gitlab_com: false to turn off the entire GitLab.com badges' row. For example, for GitLab Geo features, use:

available_in: [premium, ultimate]
gitlab_com: false

If the feature is only available in GitLab.com, e.g. subscriptions, you can use the following badges:

If, however, the feature is only available on GitLab.com because it is behind a feature flag and disabled by default, it should not be included in the release post unless you are deliberately seeking beta testers.

Documentation

Provide a link to the updated documentation for the feature. It is a required field. It can be, in this priority order:

Important: always link to the EE documentation, even if the feature is available in CE.

Note: documentation_text was deprecated by !13283 for GitLab 11.2.

Important: Every feature mentioned on the release post must link to an up-to-date document shipped in time, before the feature freeze. "Docs or it didn't happen!"

Illustration (images, videos)

Check the section Adding Content > Illustrations for more information.

Feature reporter

Stage

The stages display as an icon next to the product tiers' badges linking to the stage webpage using a regex: https://about.gitlab.com/stages-devops-lifecycle/<stage>/. We can also override it with a custom stage URL.

Although stage is a required field, if a feature doesn't belong to any of the stages at all, you can delete the stage line and it won't output anything.

Besides displaying the icon, with stage set, PMs can easily find anything that is related to their area, even if reported by other users.

Note: team was deprecated in December 2018 for GitLab 11.6 in favor of stage, with a follow-up iteration introducing their respective icons.

Custom stage URL

For stages outside of the DevOps lifecycle, such as Enablement and Growth, which don't have the same path as the other stages (/stages-devops-lifecycle/<stage>), it is necessary to add the stage_url to the content block to override the default path:

# Enablement
stage: enablement
stage_url: '/handbook/engineering/development/enablement/'

# Growth
stage: growth
stage_url: '/handbook/product/growth/'

Categories

Feature description

Cover image license

According to our Blog handbook, it's necessary to provide the source of the cover image. Fill in the entry below to display this info at the very end of the ...release.html.md blog post:

cover_img:
  image_url: '#link_to_original_image'
  licence: CC0 # which licence the image is available with
  licence_url: '#link_to_licence'

Important notes on upgrading

To be added by the Distribution Product Manager.

The "upgrade barometer" section was deprecated on GitLab 11.8 and replaced with a section called "Important notes on upgrading to GitLab X.Y".

Upgrade warnings should be added to the release post only to describe important upgrade notes, such as:

If there's no relevant info to a given release, do not add this section to the post.

Performance improvements and bug fixes

To be added by Engineering Managers and Product Managers.

The Release Post manager will create MRs, post notifications and share reminders to collect contributions for performance improvements and bugs. Engineering Managers will contribute to performance improvements and both Engineering Managers and Product Managers will contribute to bug fixes.

Omnibus improvements

To be added by the Distribution Product Manager.

This section should contain any relevant updates for packaged software, new features, and new commands relating to the administration of self-managed GitLab instances deployed using the Omnibus package e.g. (gitlab-backup).

Extras

To be added by Product Managers and merged by Engineering Managers.

If you need an extra block to convey important info, and it doesn't fit the other blog post sections, you can use the extras block, right before deprecations (in the release post YAML datafile):

extras:
  - title: "Hello World"
    description: | # supports markdown
      Lorem ipsum dolor sit amet, consectetur adipisicing elit. Consequuntur, beatae!

For more multiple blocks, use:

extras:
  - title: "Hello World"
    description: | # supports markdown
      Lorem ipsum dolor sit amet, consectetur adipisicing elit. Consequuntur, beatae!
  - title: "Lorem"
    description: | # supports markdown
      Lorem ipsum dolor sit amet, consectetur adipisicing elit. Doloremque.

Deprecations

To be added by Product Managers or Engineering Managers and merged by either.

Describe the deprecations happening in that release or in upcoming releases. Note that there are differences in deprecations and removals, so be sure to include the relevant details on when the feature will be removed from GitLab in the post. Let our community know about a future deprecation as soon as possible. When adding deprecations be sure to keep with the same structure of "XYZ feature or function will be deprecated at ABC time."

The due date is defined by the removal of that feature. The field is required, and should be set as:

If the deprecation is scheduled for an upcoming release, the content should remain in the release post until it has been completed. For example, if a deprecation is announced in the 12.9 release post and scheduled to be completed in 13.0, the same content would be included in release posts 12.9, 12.10, and 13.0.

Please set up one deprecation per MR.

deprecations:
  - feature_name: Lorem ipsum dolor
    due: May 22nd, 2017 # example
    reporter: bikebilly # item author username
    description: |  # example (supports markdown)
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
      Veritatis, quisquam.

If you need to set up multiple deprecations, notify the Release Post Manager use multiple feature deprecation blocks:

deprecations:
  - feature_name: Lorem ipsum dolor
    due: May 22nd, 2017 # example
    description: |  # example (supports markdown)
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
      Veritatis, quisquam.
  - feature_name: Lorem ipsum dolor
    due: May 22nd, 2017. # example
    description: |  # example (supports markdown)
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
      Veritatis, quisquam.

Per GitLab's Versioning Policy, non-backward compatible and breaking changes are recommended for a major release, whereas backward compatible changes can be introduced in a minor release.

Once complete, assign the MR to the technical writer assigned to the stage.

When approved, include the "Ready" label in the MR before merging.

Removals

To be added by Product Managers or Engineering Managers and merged by either.

Describe the features that are being removed in the upcoming release. Removals should be planned. If possible, set up a deprecation notice at least one minor release before removing a feature.

Note the differences between deprecations and removals, so be sure to include the relevant details on when the feature will be removed from GitLab in the post.

The date_of_removaldue date is defined by the removal of that feature. The field is required, and should be set as:

Please set up one removal per MR.

removals:
  - feature_name: Lorem ipsum dolor
    date_of_removal: May 22nd, 2017 # example
    reporter: bikebilly # item author username
    description: |  # example (supports markdown)
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
      Veritatis, quisquam.

If you need to set up multiple removals, notify the Release Post Manager and make use of multiple feature removal blocks in a single file:

removals:
  - feature_name: Lorem ipsum dolor
    date_of_removal: May 22nd, 2017 # example
    description: |  # example (supports markdown)
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
      Veritatis, quisquam.
  - feature_name: Lorem ipsum dolor
    date_of_removal: May 22nd, 2017. # example
    description: |  # example (supports markdown)
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
      Veritatis, quisquam.

Per GitLab's Versioning Policy, non-backward compatible and breaking changes are recommended for a major release, whereas backward compatible changes can be introduced in a minor release.

Once complete, assign the MR to the technical writer assigned to the stage.

When approved, include the "Ready" label in the MR before merging.

Upgrades

To be added by Product Managers or Engineering Managers and merged by Engineering Managers.

Describe any considerations administrators should have when upgrading. These could be warnings about potential data loss, recommendations for maintenance beforehand, and other similar concerns.

One notable example was in %12.10, we required administrators to migrate from Postgres 10 to Postgres 11.

upgrade:
    reporter: bikebilly # item author username
    description: |  # example (supports markdown)
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
      Veritatis, quisquam.

Once complete, assign the MR to the technical writer assigned to the stage.

When approved, include the "Ready" label in the MR before merging.

Adding content

For entries that support markdown, use regular markdown Kramdown, as we use for all blog posts and webpages on about.GitLab.com.

Illustrations

Images

Videos

You can add YouTube videos to content blocks that can either override the image or add it within the markdown description as described below.

Videos in content blocks

For content blocks, you can add a video instead of an image by using the entry video:. If both are present, the video will override the image (it won't display the image, only the video). Example:

- name: "Awesome Feature"
  available_in: [premium, ultimate]
  documentation_link: 'doc-link'
  video: "https://www.youtube.com/embed/eH-GuoqlweM"
  description: |
    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quae, provident.

Make sure to add the /embed/ video URL from YouTube. Follow the steps described on the markdown guide to find the correct path.

Videos added to the description

When added to a markdown-supported entry, every video should be wrapped into a figure tag, as shown below:

- name: "Awesome Feature"
  ...
  description: |
    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quae, provident.

    <!-- Leave a blank line above and below the code below. Do not change the code block in any ways, except for the video URL. Leave the indentation as-is and do not remove the whitespace before </iframe>. Remove this comment when ready. -->

    <figure class="video_container">
      <iframe src="https://www.youtube.com/embed/PoBaY_rqeKA" frameborder="0" allowfullscreen="true"> </iframe>
    </figure>

    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quae, provident.

The <figure> element is recommended for semantic SEO and the video_container class will assure the video is displayed responsively.

Consult the markdown guide for the correct markdown markup to apply to different sources (YouTube, Google Drive, HTML video).

Technical aspects

The release post is created from many small data files, that are rendered into the final form using templates and helpers.

The content files need to be created every release with the content unique to that release, as described by the section getting started.

The template and helper files are used to render the blog post from the many content files, and do not need to be changed in most releases.

To learn more how the template system works, read through an overview on Modern Static Site Generators.

Release post item generator

The release post item generator can help you create release post items quickly from your local command line.

To use the generator, after cloning the www-gitlab-com project to you computer:

bin/release-post-item https://gitlab.com/gitlab-org/gitlab/-/issues/20337

>> Please specify the index for the category of release post item:
1. Top feature
2. Primary feature
3. Secondary feature
4. Deprecation

?> 3

create data/release_posts/unreleased/test-feature.yml
---
features:
  secondary:
  - name: Review changes file-by-file in a merge request
    available_in:
    - core
    - starter
    - premium
    - ultimate
    gitlab_com: true
    documentation_link: https://docs.gitlab.com/ee/#amazing
    image_url: "/images/unreleased/feature-a.png"
    reporter: jramsay
    stage: create
    categories:
    - Code Review
    issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/20337
    description: |
      Lorem ipsum [dolor sit amet](#link), consectetur adipisicing elit.
      Perferendis nisi vitae quod ipsum saepe cumque quia `veritatis`.

hint add a screenshot, commit, and push your changes!
    git add data/release_posts/unreleased/test-feature.yml
    git commit -m "Review changes file-by-file in a merge request
    git push -u origin

Release post item linting

The release post item linter validates all items being merged to the data/release_posts/unreleased directory meet minimal standards. Specifically, it checks:

It does not check if:

The schema is implemented using Rx.

Release post assembly

The release post assembly script moves release post content blocks and their images to the current release directory.

It uses a simple regexp to locate content files and images. It performs no validation. In the future, it would be simple to combine the functionality with the linter to reduce the number of scripts to maintain.

Release post merge request template

The release post MR template is our checklist for every release. Let's keep it up-to-date! :)

Patch and Security release posts

The Delivery team is responsible for creating release posts for patch and security releases.

Release posts should live in source/releases/posts. For patch and security releases, please make sure to specify them in the title, add the correct category:

GIT is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license
Edit this page — open Web IDE — please contribute. Creative Commons License