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.
The sections below also link to these templates, but they're provided here for quick reference.
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.
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 assign yourself as release post manager or release post manager's shadow, simply add your name on the Release Post Scheduling page page by submitting an MR to update the /data/release_post_managers.yml file. Otherwise, PMs 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 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:
release-X-Y/www-gitlab-com/data/mvps.yml and data/release_posts/X_Y/mvp.ymlgit pull origin master, then :wq)#releases Slack channel and only merge once they've pinged you in Slack to confirm the packages are released, which will be sometime around 14:10 - 14:20)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.
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.
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.
The manual way can be done either locally or using the GitLab Web IDE:
release-X-Y from masterrelease-X-Y branch, create the blog post file, containing the introduction and the blog post frontmatter information:
sites/marketing/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.release-X-Y branch, create the release post data directory, to which features and other data will be added:
X_Y in the data/release_posts directory.data/release_posts/unreleased/samples/mvp.yml into data/release_posts/X_Y/mvp.yml.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 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:
release-X-Y and the target branch master.Draft: Release post - GitLab X.Y.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 sites/marketing/source/includes/home/ten-oh-announcement.html.haml must be committed in this MR.
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.
release-X-Y-bugs and release-X-Y-performance-improvementsDraft: release-X-Y-bugs and Draft: release-X-Y-performance-improvements and use the Release-Post-Bug-PerformanceImprovement-Block templaterelease post release post item Technical Writingbugs.yml and performance_improvements.yml to the corresponding release-X-Y-bugs and release-X-Y-performance-improvements branches to data/release_posts/13_1Important: 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
If for some reason bin/release-post-assemble fails use the following steps to manually move content and push your changes. There is also a video walking through the changes here.
1) Verify you've completed steps 1-3 above
2) Manually move all the .yml files from /data/releases_posts/unreleased/ to /data/release_posts/x_y/ (x_y being the release post directory e.g. 13_2) | note: leave the /samples directory in the same location, don't move it
3) Manually move all the images in /source/images/unreleased/ to /source/images/x_y/
4) Using a text editor like VS Code find and replace all the image paths under image_url: in each release post .yml file from /unreleased/ to /x_y/. The video above demonstrates that.
5) git commit0 and git push and you should be good to go
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.
The Community Advocates team will reach out to the release post manager in Slack #release-post when they are using the Involving Experts workflow and need help responding to inquiries about content in the release post blog. These needs will primarily arise within the first week of going live with the blog. However, as Author for a specific release post, you may get pinged to help coordinate a response some weeks later as issues arise. You will usually just need to find the best DRI to handle the issue, often the PM of the release post item in question.
The due dates for various reviews across all participants can be found on the release post MR and release post item MR 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. It's also important to do this becuase this page is LIVE to users and should be error free.
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 and any needed adjustment to the ordering of secondary features due to stakeholder feedback is the responsibility of the release post manager. Secondary features, bug fixes, performance improvements, deprecations, removals, and upgrade notes are all sorted alphabetically by title, grouped by stage. To affect the sort order of the secondary features, a change to the content block's title is required. The release post manager should work with the product managers of the content blocks to make these changes, to ensure accuracy and alignment.
After the release post MR has been generated, additional feedback is solicited from the CEO and product leaders via Slack. A best practice for capturing feedback from slack is is to copy the feedback into the MR comments with checkboxes to ensure each item is addressed. PMs can be tagged there also for easier tracking and follow up. Refer to this 13.0 MR comment thread for reference.
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.
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.
To update the release post managers list, edit the data file below.
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.
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.
After the 18th of the month, late additions should be added only in coordination with the Release Post Manager. Please see late additions to the release post for more details.
master for each feature/deprecationmaster branchdata/release_posts/unreleased/ on the master branch
data/release_posts/unreleased/samples/ for format and sample contentfeatures: then top:, then the feature content/source/images/unreleased/release-X-Y branch.release-X-Y branch and move the YAML and image files into the release-specific folder.data/release_posts/X_Y/ on the release-X-Y branch. For help, see the documentation for this use case
data/release_posts/unreleased/samples/ for format and sample contentfeatures: then top:, then the feature content/source/images/X_Y/data/features.yml as part of the same merge requestOnce all content is reviewed and complete, add the Ready label and assign
this issue to the appropriate Engineering Manager (EM) so they can merge it
when the feature itself is merged.
Important note on naming files: PMs should create file names that are descriptive and have reasonable overlap with the title of the content block itself. This makes it easier to related content blocks to yml file by different participants in the review process.
Feature file names: feature-something-descriptive.yml (don't designate primary vs secondary as that can change)
Deprecation file names: dep-something-descriptive.yml
Removal file names: removal-something-else-descriptive.yml
Upgrade file names: upgrade-another-description.yml
Some troubleshooting hints:
git merge, don't use git rebase. Rebase is a powerful tool that makes for a clean commit history, but due to the volume of commits by the number of collaborators on the www-gitlab-com repo, it will typically have a lot of conflicts you'll have to manually work through. Since your content MRs should only contain changes relevant to your own content block and a single addition to features.yml, merge conflicts should be minimal, and typically nonexistant. If you start a rebase and run in to issues, you can always back out with git rebase --abort.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. For example, we avoid formal phrases such as "we are pleased to announce" and generally speak directly to our users by saying "you can now do x" rather than "the user can now do x". Checking out the links to these guidelines will help you align hour tone/voice as you write, ensuring 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 should 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.
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…
category maturity for the category your feature lives within)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. Tech Writer reivew is required even when late additions are made to the relaese post after the 18th of the month. 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).
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.
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.
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. It's important to check this page after the content block MR is merged becuase this page is LIVE to users and should be error free.
After the 18th of month, and before the 20th, including new release post items should be coordinated with the Release Post Manager so that they are aware and can anticipate how the late additions may impact the rest of the release post. Before pinging the release post manager, ask yourself if your content absolutely needs to be part of the current release post. After the EOD on the 19th, no late content blocks will be accepted.
The process for merging late additions is:
unreleased folder to the appropriate release post folder and make edits as needed.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 (if the feature is visible in the UI).
features.yml is the SSOT for displaying features across about.gitlab.com.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.
Once the PMs have included everything they're accountable for, they should check their item in the release post MR description:
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.
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.
Each month a Product Marketing Manager (PMM) will lead the messaging and positioning for the release post. Use the handbook guidance below for messaging lead release post preparation and planning. This handbook section is your source of truth from the 18th of the previous month - 11th of the release month. After the 11th of the month, your source of truth to prepare and deliver the release post is in the monthly release post blog template.
The messaging lead is responsible for:
This section provides guidance on how to decide on top 3 features or themes and timelines:
Use the handbook guidance below for messaging lead release post preparation and planning. This handbook section is your source of truth from the 18th of the previous month - 11th of the release month.
On the 11th of the release month, take inventory to make sure you are ready for next steps
- You should have already started identifying theme/features based on the various parameters outlined above and [Merge requests](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=all) with Milestone 'Release Number' and Label 'release-post' which give the indicator of all the features that could be released
- Ideally, you've identified more than 4-5 features or themes - as even at this stage, a few features may move to the next release, making a theme irrelevant. Watch the release post [preview page](https://about.gitlab.com/releases/gitlab-com/). Features posted there have been introduced on GitLab.com and are less likely to slip.
- Remember to leverage your [Release Feature Story Planning spreadsheet](https://docs.google.com/spreadsheets/d/1sU3x6uR5wNTwsYroikdHpToi9tRVlZ4n83vjceXjp9A/edit?usp=sharing) and to update the optional [messaging lead story planning doc](https://docs.google.com/document/d/1XoRWJXjWmwdeSE8_bSBcVvBnLhhYdzPW5T8JLYvYVmE/edit?usp=sharing) if you chose to use it, as it will be very handy in the next several days leading up to release post content reviews
From the 11th until the release launch on the 22nd, your source of truth for remaining messaging lead tasks is the detailed PMM checklist included in each month's release post MR description entitled "Messaging content and positioning (Messaging Lead)."
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. Primary feature content blocks are sorted alphabetically by file name so the messaging lead can affect the order of these items by adding a 2-digit numerical prefix to the file name of each individual content block. For example, 01_filename.yml, 02_another_file.yml, etc.
Secondary features, bug fixes, performance improvements, deprecations, removals, and upgrade notes are all sorted alphabetically by title, grouped by stage. In cases where the messaging lead wants to manually affect the sort order of the secondary features, a change to the content block's title is required. It is recommended this be coordinated with the release post manager so the PM and the PMM of the content block are involved as needed.
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.
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.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.
A technical writer, once assigned to the release post merge request, will check the syntax and the content structure.
The Structural check 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:
auth-server, raise questions if there's also an entry that removes an item referred to as auth_server.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.
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.
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:
Each TW reviewer retains prime responsibility for each RP, Deprecations, Removals, and Upgrades.
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:
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:
Images or videos are not required for secondary features.
In its frontmatter:
title is no longer 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.
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.
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:
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:
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:
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.
The responsibilities of the Engineering Manager are documented in the Engineering Handbook.
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/' # relative link
- title: Lorem ipsum dolor sit amet
link: 'https://example.com' # external 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. 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.
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.
If the secondary feature is promoted to a primary feature, the PM or EM will be asked to supply an image on short notice.
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.
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.
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. See the Videos
section for more information.Check the section Adding Content > Illustrations for more information.
reporter: GitLab handle of the user adding the content 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 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 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 content 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'
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.
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.
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).
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.
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.
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.
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.
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.
For entries that support markdown, use regular markdown Kramdown, as we use for all blog posts and webpages on about.GitLab.com.
<div class="cover" style="background-image: url();">url() replace the string with the URL of the upsplash image (the actual URL of the image, you may need to right-click the image and slect "copy image address"){:.shadow}{:.shadow}.image_url entry, add the image_noshadow: true entry right after image_url.You can add YouTube videos to content blocks that can either override the image or add it within the markdown description as described below.
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.
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).
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.
The release post item generator automates the creation of release post items using issues and epics. Issues and epics are the source of truth for what problems are being solved and how, and should have a clear description, and be well labeled. The script uses this information to pre-fill release post item MRs:
| Issue/Epic Elemen | Release Post Item Attribute (yml) or MR element |
|---|---|
| Issue Title | title: |
Label devops:: |
stage: |
Label group:: |
assigns group product manager as reporter, and tags relevant team members in the MR |
label category: |
categories: |
Label release post item:: (primary/secondary) |
content block type primary: or secondary: |
Label tier (e.g. GitLab Core GitLab Ultimate) |
available_in: |
Issue web url (i.e. /gitlab-org/gitlab/-/issues/####) |
issue_url: |
Issue description under ### Release notes |
description: will contain all text except for the documentation_link and image_url documentation_link: is the first URL in the ### Release notes section containing https://docs.gitlab.com* image_url: is the first image added to the ### Release notes section. (e.g. Image: ) |
To ensure the generator script runs correctly follow the process below:
### Release notes (including a docs link and image, although those can always be added/updated in the MR later) specifically having it contain both a Description: then a Documentation:.devops::, group::, category: and tier (e.g. GitLab Core) labels are appliedrelease post item:: scoped labels. This will make the generator script pick up your issue next time it runs (once per hour)Once the script runs an draft MR in the /gitlab-com/www-gitlab-com project will be opened and assigned to the group PM. You can continue editing and reviewing that MR from there.
If you'd like to check to see when the last pipeline ran (and if it picked up your issue) you can inspect the scheduled pipeline here.
You can also watch this overview video demonstrating how to use the release post item generator.
note: The release post item generator is still in beta. If you find issues or have questions post them in Slack #release-post-iteration or add them to the current cycle release post retrospective issue.
The generator script can also be run on your computer.
www-gitlab-com project, and install dependencies using bundle installRun the script, providing your GitLab private access token, and the issue URL:
PRIVATE_TOKEN=<token> bin/release-post-item --no-local <issue_url>
Refer to bin/release-post-item --help for complete documentation.
The release post item linter
validates all items being merged to the data/release_posts/unreleased directory meet minimal
standards. Specifically, it checks:
stage filed maps to a valid stage key in data/stages.ymlcategories list only contains valid category names from data/categories.ymlIt does not check if:
top and primary items have an image or videoissue_url is supplied, since there are other alternativesThe schema is implemented using Rx.
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.
The release post MR template is our checklist for every release. Let's keep it up-to-date! :)
The Delivery team is responsible for creating release posts for patch and security releases.
Release posts should live in sites/marketing/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: releases