GitLab releases a new version every 22nd of each month, and announces it through monthly release posts.
Patch and security issues are addressed more often, whenever necessary.
To start a new release post, please choose one of these templates, and follow their instructions to insert content. Please make sure to use the most recent template available.
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:
title: "GitLab Patch Release: x.y.z and x.y.z"categories: releasestitle: "GitLab Security Release: x.y.z and x.y.z"categories: releasesMonthly releases have an exclusive layout aiming to apprise the reader with the presentation of a new release every 22nd.
Note: The new design for monthly release posts was introduced in March 2017 with the release of GitLab 9.0. The new layout was introduced in May 2017 with the release of GitLab 9.2.
To create a new monthly release post, add two files to the about.GitLab.com repository (consider the release of GitLab X.Y, released in YYYY/MM/DD):
data/release_posts/, add a new file called YYYY_MM_22_gitlab_X_Y_released.ymlsource/releases/posts/, add a new file called YYYY-MM-22-gitlab-X-Y-released.html.mdImportant! Please use the most recent templates for each of these files.
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.
Set the title to "WIP: Release post - GitLab X.Y".
Check "Remove source branch when merge request is accepted". Consider to check "Squash commits when merge request is accepted" only if there are too many commits that are useless (typos, styling, etc…).
The branch name must be release-X-Y.
Please use the release post template for your MR:
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.
Each month a Product Manager will lead the release post, as defined in the Release Post Scheduling page.
Product Managers can volunteer for any release that doesn't have someone assigned yet. Otherwise, they will be assigned using a fair scheduling principle:
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 author 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 authorship 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 author is accountable for:
data/mvps.ymlmaster into the release post often during the process and on the 21st, to make sure there are
no merge conflicts (do not rebase, please do git pull origin master, then :wq)#releases chat channel to only merge the post once deploy has completed
and the packages published)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.
Each month a Product Marketing Manager (PMM) will lead the messaging and positioning for the release post.
The messaging lead is responsible for:
features.yml in individual MRs that are collated later.features.yml can have the same or very similar content. E.g. same screen shot.
features.yml should be evergreen to appear on our website in various places.Monthly release posts are created in two stages:
To be able to finish our work in time, with no rush, each stage will have its due date.
To having the release post well written and ready in time for the release date, please set due dates for:
The review should be completed until the 2nd working day before the 22nd, so that the 1st working day before the release should be left for fixes and small improvements.
Added by the team until the 17th. Please fill all the sections.
They are mostly added by the Product Managers, each filling up the sections they are accountable for.
Starting with the 12.2 release post, feature blocks and deprecations are contributed changelog-style.
In parallel with feature development, an MR to the release post should be prepared which contains all required content: screenshots, documentation links, description, etc. It should then be reviewed by PMM and tech writing, to be merged alongside the feature itself.
master for each feature/deprecation, and open an MR targeted at the master branch. Don't forget to add the milestone and the release-post and devops::<stage> labels.data/release_posts/unreleased/. See data/release_posts/unreleased/samples/ for format and sample content. Images should be placed in /source/images/unreleased/.
features: then top:, then the feature content.You are responsible for the content you add to the blog post. Therefore, make sure that:
data/features.yml with a screenshot accompanying the feature.
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.
Once the PMs have included everything they're accountable for, they should check their item in the release post MR description: <MR link>#features:
https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/6239#features
By checking your item, you will make it clear to the author 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.
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 author.
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 feature 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.
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:
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/'
- title: Lorem ipsum dolor sit amet
- link:
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.
Based on this discussion, the release post author 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 feature 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.
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:
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.
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.
Relevant improvements in GitLab. Image is not required, but recommended.
Use feature blocks to add features to the YAML data file. The layout will be applied automatically by Middleman's templating system.
Feature blocks in the YAML data file contain the following entries, as exemplified below:
- name: "Multi-Project Pipeline Graphs"
available_in: [premium, ultimate]
documentation_link: 'https://docs.gitlab.com/ee/ci/pipelines.html#multi-project-pipelines-graphs'
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.
name: feature name, capitalizedUse a short and strong name for all feature names.
Use the following pattern to apply the correct badge to the feature (Core, Starter, Premium, Ultimate).
available_in: availability of that feature in GitLab:
[core, starter, premium, ultimate][starter, premium, ultimate][premium, ultimate][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:
available_in: availability of that feature in GitLab.com:
[free, bronze, silver, gold][bronze, silver, gold][silver, gold][gold]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.
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!"
image_url: link to the image which illustrates that feature.
Required for primary features, optional for secondary features and top feature.image_noshadow: true: if an image (image_url) already has shadow
the entry image_noshadow will remove the shadow applied with CSS by default. Optional.video: when present, overrides the image and displays the linked video instead. Use the link for embed videos.Check the section Adding Content > Illustrations for more information.
reporter: GitLab handle of the user adding the feature block to
the release post (not the feature author).
This should be the PM responsible for the feature, so in the review
phase anyone knows who they have to ping in order to get clarifications.
It is a required field.stage: the DevOps stage the feature belongs to (lowercase):
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 DevOps 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.
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 feature block to override the default path:
# Enablement
stage: enablement
stage_url: '/handbook/engineering/development/enablement/'
# Growth
stage: growth
stage_url: '/handbook/product/growth/'
category (array): Any category(ies) the feature belongs to. These are usually attached
to the feature's issue as labels. A list of categories can be found in
/data/categories.yml.
Make sure to add the category name exactly as typed on the data file.issue_url: link to the issue on GitLab.com where the feature is discussed
and developed. Using this link the reviewer can check the status of the specific
feature for consistency and additional references.
It is a required field, but can be replaced with mr_url, issueboard_url, or epic_url.
Always wrap links in single quotes ('https://example.com').issueboard_url: link to the issue board related to the feature. Not required, but available.mr_url: link to the MR that introduced the feature. Not required, but available.epic_url: link to the epic related to the feature. Not required, but available.webpage_url: link to the marketing webpage for a given feature. Not required, but available.description: |: add the feature's description in this entry.
Make sure your cursor is in the line below the pipeline symbol | intended once.
All description fields fully support markdown, the only thing you need to be worried about is respecting the indentation.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'
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.
To be added by the engineering leads, in the "general contributions" stage.
Describes relevant performance improvements individually, when present. Otherwise, you can either use this standard redaction or write a new one:
- name: Performance Improvements
available_in: [core, starter, premium, ultimate]
performance_url: https://gitlab.com/groups/gitlab-org/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name%5B%5D=performance&milestone_title=X.Y # merged MRs in the corresponding milestone
reporter: bikebilly
description: |
We are continuing to make great strides improving
the performance of GitLab in every release.
[We're committed](/handbook/product/#performance) to not only
making individual instances of GitLab even faster,
but also to greatly improving the performance of GitLab.com,
an instance that has over 1 million users!
In GitLab X.Y we are shipping performance
improvements for issues, projects, milestones, and a lot more!
Don't forget to replace X.Y above with the current release!
To be added by the Distribution Product Manager during the general contributions stage.
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).
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.
Describe the deprecations happening on that release or in upcoming releases. 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:
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.
For multiple deprecations, 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.
The review is performed after content has been added, so it's important to respect the due dates, otherwise reviews will have to be done repeatedly.
The review should be completed until the 2nd working day before the 22nd, so that the 1st working day before the release should be left for fixes and small improvements.
The due dates for each review can be found on the MR description.
The content review is performed by product manager leading the post (author), who will check if everything is in place, and if there's nothing missing. Will also make suggestions, ask questions, and make sure all the comments are solved (ping people on Slack if necessary). Also, assure all items in the "general contributions" list presented in the MR description have been checked.
Lastly, the post should be reviewed by a Marketing team member (PMM, CMM) to evaluate wording and messaging.
Follow the checklist on the MR description for every review item.
Once the post is filled with content, the technical writing team, or, in their absence, the UX or the frontend team, will check the syntax and the content structure. Please follow the checklist in the MR description to guide you through the review.
Give special attention to:
Look for each entry in the frontmatter. To prevent the page to break due to special chars:
Make sure that title is no more than 62 characters, to ensure it presents well against the blog
post's title graphic.
---
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.
A Product Marketing Manager should conduct the marketing review for checking the approach, the messaging, and anything else they find relevant. Please follow the checklist in the MR description.
For entries that support markdown, use regular markdown Kramdown, as we use for all blog posts and webpages on about.GitLab.com.
{:.shadow}{:.shadow}.image_url entry, add the image_noshadow: true entry right after image_url.Every video should wrapped into a figure tag, as in:
<figure class="video_container">
<iframe src="https://www.youtube.com/embed/PoBaY_rqeKA" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
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).
For feature blocks, you can add a video instead of an image, by using the entry video:. If present, the feature section won't display any images, only the video. Example:
- name: Awesome Feature
available_in: [premium, ultimate]
documentation_link: ''
video: "https://www.youtube.com/embed/eH-GuoqlweM"
description: |
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quae, provident.
Understand how a release post is formed:
The template files form the blog post, therefore, don't need to be changed every release. The content files are the ones to be added every release with its unique content, as described by the section getting started.
To learn more how the templating system works, read through an overview on Modern Static Site Generators.
The release post MR template is our checklist for every release. Let's keep it up-to-date! :)
To update the release post managers, edit the data file below.
