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 whom, and when those items are due.
Note: We're evolving our release post process! You can view and share feedback on the latest direction by viewing Scaling the release post.
At a high level, the Release post schedule is:
bin/rake release_post:startfeatures.ymlenabled by default to ensure inclusion into the self-managed release.Release Post Manager merges usability, performance improvements, and bug fixes MRs
Note: MRs added after the 17th should target the release-x-y branch, not master
: Release Post Manager aggregates the content blocks with bin/release-post-assemble
release-X-Y branch and are subject to approval by the Release Post Manager.Note: The 18th - 20th can fall on vacations, weekends, or holidays. PMs should designate who to respond to time-sensitive inquiries should they be unreachable. Release Post Managers are empowered to make decisions and display bias for action if they haven't received a response by EOD on the 20th.
The GitLab.org Releases page will also populate the changelog via the process outlined in gitlab!44837 |
Note: Details for all of these steps are described in the Monthly release post MR template and the Monthly release post item MR template.
Each month, a Product Manager, Technical Writer, and an Engineering Department Technical Advisor volunteer to manage the release post, as listed in the Release Post Scheduling page. Product Marketing Managers also sign up, but mostly as shadows for awareness for their related marketing activites. The Product Manager volunteer will lead the release post as the Release Post Manager and is listed as the Author of the release post when the post is published. To update the release post scheduling list, all volunteers need to edit the data file below:
It's highly recommended that all volunteers shadow the release post prior to the one they run. Volunteers can update the previously mentioned data YAML file to indicate both when they shadow and when they help run the release post.
Release Post Managers will need Maintainer access to project https://gitlab.com/gitlab-com/www-gitlab-com/. If you need access, model your request after this confidential issue.
Product Managers of any level (IC or managers) can volunteer for any release that doesn't have someone assigned yet. While we encourage IC product managers to take advantage of this opportunity to demonstrate their leadership skills, we also value that managers will bring their experience to the role.
Before committing to the date of your choice, please be sure you can perform the critical path release post manager tasks between the 15th and the 22nd of the month as defined in the monthly MR template. If you cannot perform any of the release post manager tasks between the 15th and the 22nd of the month, please sign up for a release post that better aligns with your availability.
To assign yourself as release post manager or release post manager's shadow, simply add your name on the Release Post Scheduling page by submitting an MR to update the /data/release_post_managers.yml file. Otherwise, PMs will be assigned using a fair scheduling principle leveraging this tracking doc:
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.
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.
Shadows should remain engaged with the release process by:
In order to properly onboard the shadow, the Release Post Manager should:
Remember: The goal of the shadow is to get them engaged and aware of the process so they can run one on their own. Include the shadow as much as possible so they can learn and be prepared!
We recommend that technical advisors volunteer for at least 2 or 3 release posts in a row to allow proper time for orientation with the process and the ongoing technical backlog.
Technical advisors are expected to:
www-gitlab-com source code.The responsibilities of a technical advisor can be seen in more detail in Technical advisors.
Make sure you have Maintainer access to project https://gitlab.com/gitlab-com/www-gitlab-com/. If you need access, model your request after this confidential issue.
An automated task will create the branches, MRs, and issues necessary to run the Release Post process, including making the appropriate assignments and mentions based on the Release Post Manager schedule.
If you have not been assigned to a Release Post X.Y MR by the end of the day on the 3rd:
@brhea in Slack #release-post@brhea is unavailable, work with your Technical Advisor to run bundle exec rake release_post:start to kickoff the X-Y Release Post, orNote: You should not use the default system installed Ruby but should install a Ruby version manager like RVM, Rbenv, or asdf to manage your Ruby installation. See handbook guidance on installing a Ruby version manager and other requirements. Reach out for help if needed.
Prior to running the content assembly script (described in the next section), the release post manager should confirm their local dev environment is running a current version of Ruby and its dependencies are updated. Doing this early on in the process is recommended as, sometimes, updates to the www-gitlab-com project or the content assembly script could cause your Ruby version or Ruby libraries (gems) to be outdated. If unknown errors arise during this verification, reach out to the release post DRI for advisement.
./bin/doctor and follow the prompts to resolve any errors. See also demo video of the doctor script.How do I know if I already have a Ruby Version Manager installed?
Open a terminal window, and then run one of these commands:
which asdfwhich rbenvwhich rvmIf the returned output is something other than asdf not found, rbenv not found,
or rvm not found, you probably have one of these installed. A path to one of
those tools is returned to the screen if a Ruby version manager is installed.
What if I have a different Ruby Version Manager than what is in the handbook? If something like rbenv already installed, then you likely just need to update Homebrew with brew upgrade rbenv ruby-build and install the latest with rbenv install 2.6.6 or similar.
Important: This procedure applies until the 18th, at . 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 on 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:
git checkout master
git pull
git checkout release-X-Y
git pull
git merge master
bin/release-post-assemble
git push
git push origin release-X-Y
Sometimes bin/release-post-assemble may fail if there is a Ruby version update (or updated Ruby libraries) between the time the release post manager updates their local environment by the 7th and when content assembly starts on the 18th. The script may even fail for unknown reasons at times. If for some reason bin/release-post-assemble fails, you can reach out to the release post DRI for advisement. If all else fails, you can use the following steps to manually move content and push your changes. There is also a video walking through the changes here.
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. |
/source/images/unreleased/ to /source/images/x_y/.image_url: in each release post .yml file from /unreleased/ to /x_y/. The video above demonstrates that.git commit and git push and you should be good to go.The release post manager, the Technical Advisor, the Product Operations DRI, the Technical Writer, and PMM Lead will need to communicate about topics that are related to the release post but not relevant to the broader team, these chats should occur in Slack #X-Y-release-post-prep channel in Slack, to minimize distractions and unnecessary notifications for the broader team in Slack #release-post.
The release post manager posts in Slack channels most frequently with reminders. As such, if the release post manager is seeking guidance on how to phrase certain posts, it's recommended to scroll to the approximate date that post would have been made by the previous release post manager in the relevant Slack channel. However, here are some best practices and an example:
When communicating in either Slack #release-post or #X-Y-release-post-prep, organize your announcements and requests via unique discussions threads to make it easier to track conversations. For example, avoid combining various reminders just because they fall on the same date when they address different topics. As a general rule, if there's is a unique task list item for the reminder in the MR template, that reminder should get its own separate post whether it is in Slack or the MR itself. Also, review GitLab's effective slack communication guidance.
Sample post to executive stakeholders for review:
md @Sid @david @Justin Farris The 13.6 Release Post has been generated and can be reviewed at
https://release-13-6.about.gitlab-review.app/releases/2020/11/22/gitlab-13-6-released/index.html.
Please share your feedback by on Friday November 20 (tomorrow). Thank you for your review!
Currently there are no known issues/adjustments to the content but I know of one deprecation that needs to be added and will happen with my first wave of edits. We do still need to add social links and a reminder that the YouTube videos do not load in review apps but we have verified the proper /embed/ URLs.
Here’s the 13.6 release post MR: https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/66652
Cc @Product Operations DRI @TW Lead @tech-advisor @PMM
Other samples for posts include reminders and notices on any items that the Release post manager is taking:
md 🎺 Hi team! Announcing a "last call" that no further contributions to the bugs, performance improvements, and usability improvements MRs will be taken after the 15th. Please get them in 🏃♂️ cc @Farnoosh
Hey team, reminder that there are currently XX Open and Ready MRs targeting XX.X milestone (link to open MRs). Please take a moment to ask your EMs to merge or to move out the items that won't make milestone.
Hi all, I will be completing the final merge for the release post in the next 45 minutes-1 hour! I will be coordinating any activities with team members to resolve any problems that come up. cc @Farnoosh @Tech Advisor @TW Lead
The Developer Evangelism team will reach out to the release post manager in Slack #release-post following their Release days process when they 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.
Sometimes, external PR and Marketing firms reporting on the release or managing media relations may ping the RPM directly with questions, since the RPM is the "author" of the release post. If this happens, the release post manager should coordinate reach out to Product Operation help and figure out who in Marketing can take over this communication.
The due dates for various reviews across all participants can be found on the release post MR template and the release post item MR template. PM contributors are encouraged to cease attempts to add new content blocks after the content merge deadline on the 17th, and especially after final content assembly happens on the 18th at . Exceptions can be made for highly impactful features, but it is up to the discretion of the Release Post Manager to work with the PM 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 responsibility 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 because this page is LIVE to users and should be error free.
The content review of the usability, 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, usability, performance improvements, 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 Review App for the release post has been generated, the Release Post Manager solicits additional feedback from the CEO and product leaders via Slack in the #release-post channel. Clearly communicate when they can expect to start their review 24 hours in advance; this is especially important when the review must happen over the weekend. A best practice for capturing feedback from Slack 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.
It is the Release Post Manager's responsibility to make sure all content is completed by the 20th of the month, ensuring a one day buffer is left for final error fixes and small improvements.
NOTE: To the extent possible, we strive to use GitLab's Community Code Review Guidelines when performing Release Post content review.
It is recommended for the Release Post Manager to review all content for quality, including the marketing intro. But when reviewing content blocks in each release post item MRs, the RPM should look for the following:
[, ], (, and ) to find malformed links.The introduction content of the release post (found in YYYY-MM-DD-gitlab-X-Y-released.html.md) is templated to be standard across all release posts, and should not be modified without approval from the Product Operations DRI. This file is linked at the top of the release post MR for reference and ease of editing. The release post manager will work with the VP of Product to make sure all primary items are approved and a top feature is designated.
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: The Instructions below apply up to the 18th . After content assembly on the 18th of the month, anyone who wants to include a change in the upcoming release post must coordinate with the Release Post Manager and follow detailed instructions in the Merging content blocks after the 18th section for special handling of late additions.
The release post item generator automates the creation of release post items using issues and epics. Draft your release post content under the Release notes section of the feature issue template and then follow the release post item generator instructions.
Note: The generator will not create an MR for a confidential issue. To add a release post item for work relating to a confidential issue, follow the steps below to create an MR manually and remove any confidential information or links.
master for each feature (primary, secondary, removal). Deprecations are handled differentlymaster branchdata/release_posts/unreleased/ on the master branch
data/release_posts/unreleased/samples/ for format and sample contentfeatures: then primary:, then the feature content/source/images/unreleased/data/features.yml (if applicable) to include your feature and commit the changes as part of the same merge requestReady label and assign MR to the appropriate Engineering Manager (EM) to merge when the feature is deployed and enabled.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. Either underscores _ or hyphens - can be used as long as the correct prefix is used (stagename, removal, or upgrade) as listed below.
stagename-featurename.yml (for example, create-group-wikis.yml). Do not:
removal-something-else-descriptive.ymlupgrade-another-description.ymlSome 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 nonexistent. 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 our 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 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 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 collaboration 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)primary features should have a corresponding entry in features.yml as well as a photo or video in the release post item block.PM Director/Group Manager, PMM, and Product Design reviews are highly recommended, but the Tech Writer review is the only one required for inclusion in the Release Post. Tech Writer review is required even when late additions are made to the release 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, to ensure the proper labels are 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 PMM reviews are not required, but recommended - and Product Leader and Product Design reviews are optional - 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, PMM, and Product Design counterpart to review the content block by the 16th. As the PM it is your responsibility to communicate what MRs need a review from the TWs, PMMs, Product Designers, 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 into the codebase itself. This allows all of the relevant parties (Product Managers, PMMs, Product Designers, 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. From the 22nd forward you should view the content blocks on the blog. It's important to check this page after the content block MR is merged because this page is LIVE to users and should be error free.
After the content assembly starts on the 18th of the month and before the 20th, adding any new or removing any merged release post items must be coordinated with the Release Post Manager.
This is necessary to allow them to assess the impact on the release post and coordinate any necessary adjustments with the release post team (Tech Writer, PM, etc.). Failure to do so might result in your changes not being picked into the release post.
Before pinging the release post manager, ask yourself if your content absolutely needs to be part of the current release post. At end-of-day on the 20th, no late content blocks will be accepted.
#release-post to request adding a late addition for the release post, and wait for the RPM to give confirmation to proceed. The release post manager will do their best to accommodate the request, but it is not guaranteed.release-X-Y branch./data/release_posts/unreleased to /data/release_posts/x_y/./source/images/unreleased to /source/images/x_y/image_url field in the release post yml file points to the image file under /source/images/x_y/.master.features.yml, you will need to create a second MR, branched from master to add the feature to features.yml. (features.yml should be merged to master, not the release post branch).#release-post to notify them you need to remove an item already merged onto the release X-Y branch.release X-Y branch.features.yml on master.You can make changes to the release post after it's live to make edits to any content blocks (features, bugs, usability and performance improvements, or removals).
To edit a content block:
Find and edit the relevant .yml file in the correct subdirectory. For example, to add or edit the example Widgets feature to the 14.6 release post, create or edit the data/release_posts/14_6/widgets_example.yml in an MR against master.
To remove the feature block, remove the file in your MR. Or to announce it in the next release post, move the file to the data/release_posts/unreleased folder.
@fseifoddini as a Reviewer. You can also assign the current cycle's Release Post Manager.To edit a deprecation, follow Editing a deprecation entry.
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.
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.
Please respond to comments in the MR thread as soon as possible. We have a non-negotiable due date for release posts.
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 the documentation.
Always link to the "EE" version of GitLab docs https://docs.gitlab.com/ee/ (not /ce/) in the blog post, even if it is a CE feature.
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.
Note that security fixes should be included in, and announced with, the Patch and Security release posts which is a different process than the monthly release post.
It's up to the product manager's and product designer's discretion, in partnership, to decide what usability improvements to highlight in a release post. This section will be limited to a maximum of 12 line items for consumability. We encourage PDs to make sure all items that don't make it into this section are added to the UI Polish gallery, with a link from the release post.
When evaluating what to include consider the following factors:
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 and product managers have ultimate responsibility for the style and language of their release post items, including Deprecations, Removals, and Upgrades, TW leads still have an overall responsibility to notify the release post manager, the product managers and TW reviewers if style and language don't seem reasonably consistent (things are obviously out of sync with known guidelines). But it is not the responsibility of the TW leads to fix style and language inconsistencies. However, TW leads do have the responsibility and ownership to make sure that all links in the release post point to relevant content and be fixed, if issues are found.
Consideration: When communicating with your release post team, use the release post prep channel and organize discussions into threads to make it easier to track conversations. Also, review GitLab's effective slack communication guidance.
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 for this date, 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.
Note: The introduction or other parts of the release post written may include links to external blog posts. These links may be broken until the 21st, but should still be flagged by the TW Lead during the structural check so the Release Post Manager doesn't miss coordinating with authors of these external blogs to ensure they're live before the release post blog goes live on the 22nd.
The Release Post is considered a special blog post instance, so should adhere to the Marketing editorial team's style guide.
Until 8:00 am Pacific Time on the 18th, 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
Develop on a feature branch.
In its frontmatter:
Make sure that title is no longer than 62 characters, to ensure it presents well against the blog post's title graphic. The title should be short for the following reasons:
---
release_number: "X.Y"
title: "GitLab X.Y Released with Feature A and Feature B"
author: "Name Surname"
author_gitlab: gitlab.com-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/X_Y/X_Y-cover-image.ext'
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
# release_number_image: "/images/X_Y/X_Y-release-number-image.svg" # uncomment if you want a svg image to replace the release number that normally overlays the background image
---
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 (#usability-improvements-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 the 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 the bug fixes MR associated with each release post. This MR has not been reviewed by any other TW. For this MR, ensure to check the metadata and the description, as follows:
Bugs included in the description:
YAML data:
[]() for links, URLs wrapped in single quotes, text wrapped in double quotes, code wrapped in code blocks or inline code blocks.- name: "Bug fixes"bug_fixes_url: 'https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=%E2%9C%93&state=closed&milestone_title=XX.Y&label_name[]=type::bug - replace XX.Y with the current milestone. For example, for GitLab 13.8, the correct link is https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=%E2%9C%93&state=closed&milestone_title=13.8&label_name[]=type::bug' - this links to closed issues for the 13.8 milestone with the ~"type::bug" label.As the TW Lead, you're responsible for reviewing the performance improvements MR associated with each release post. This MR has not been reviewed by any other TW. For this MR, ensure to check the metadata and the description, as follows:
Performance improvements added to the description:
YAML data:
[]() for links, URLs wrapped in single quotes, text wrapped in double quotes, code wrapped in code blocks or inline code blocks.- name: "Performance improvements"performance_improvements_url: 'https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&milestone_title=XX.Y&label_name[]=performance' - replace XX.Y with the current milestone. For example, for GitLab 13.8, the correct link is https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&milestone_title=13.8&label_name[]=performance - this links to merged merge requests for the 13.8 milestone with the ~performance label.As the TW Lead, you're responsible for reviewing the usability improvements MR associated with each release post. This MR has not been reviewed by any other TW. For this MR, ensure to check the metadata and the description, as follows:
Usability improvements included in the description:
YAML data:
[]() for links, URLs wrapped in single quotes, text wrapped in double quotes, code wrapped in code blocks or inline code blocks.- name: "Usability improvements"ux_improvements_url: 'https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=%E2%9C%93&state=closed&milestone_title=XX.Y&label_name[]=usability - replace XX.Y with the current milestone. For example, for GitLab 13.8, the correct link is https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=%E2%9C%93&state=closed&milestone_title=13.8&label_name[]=usability' - this links to closed issues for the 13.8 milestone with the ~usability label.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:
When a new GitLab version is released on the 22nd, the TW Lead also sets up the release of the published documentation for that version.
For instructions, see the GitLab docs Monthly release process.
Note: TW reviewers should not be confused with the TW lead.
Each person in the Technical Writing team is responsible for the review of each individual release post item and deprecation item that falls under their respective stage/group.
When the PM creates a release post item merge request, or creates a deprecation entry, they should assign it to the TW of their group for review (required). The process for TW reviews is described in the:
The deprecations and removals docs are generated with .yml files in gitlab/data/deprecations.
The html pages are not generated automatically. The TW assigned as the reviewer of the deprecation or removal item must run a Rake task to compile the documents. They can also run a separate task to check that the docs are up to date.
While the author of the deprecations or removal MR is responsible for creating the content, they are not responsible for updating the doc.
Updating the docs:
gitlab-org/gitlab project, and check out the MR's branch.Deprecation and removal MRs must be merged by the 17th. If merged later, they might miss the code cutoff and won't be included in the self-managed release's docs.
If an entry needs to be edited, the update process is similar.
If you run into problems running the Rake task, check the troubleshooting steps.
Note: Product Designers DRIs review the individual release post items according to the stage/group each designer is assigned to.
Each PM is responsible for pinging their Product Design counterpart when they need a review on the content or visuals within a release post.
Product Designers should collaborate on release post items and review:
The responsibilities of the Engineering Manager are documented in the Engineering Handbook.
Each month, the release post manager may need help with technical hurdles during the release post process. In order to provide the release post, which is a time-sensitive and highly visible asset for customers and users, with adequate technical advisement and support, we are piloting a partnership with the GitLab development team to leverage the Dev Escalation process via the Slack #dev-escalation channel as an extension. This ensures that at all times, if something breaks that the release post team can not resolve themselves, they have access to technical experts for resolution. It is recommended that technical advisors review the documented technical aspects of the release post for reference, and the escalation process.
Please note that unlike other monthly volunteers of the release post, the technical advisor is not expected to follow the release post process at all times. The release post manager will reach out to the technical advisor on call via Slack in #dev-escalation channel and then cross-posts to #release-post channel for transparency that issues are being worked on. It is then expected that the technical advisor will respond to the release post manager or release post DRI as soon as possible, including evenings/weekends, as the release post asks are often time sensitive, especially between the 18th and the 22nd of the month. The technical advisor is responsible for determining if further dev escalation should proceed.
The good news is that the release post technical hurdles are often reasonably easy to troubleshoot for technical experts, which is why we're excited about this partnership!
Below are the types of problems the release post managers may need help with.
Should you exhaust your ability to resolve your blocker quickly mention the Technical Advisor in #dev-escalation channel and cross-post in #release-post channel to ask for help, and make others aware that there may be a delay in assembly.
Describe your blocker in detail, screenshots, videos, etc. can assist in diagnosing the problem. Indicate whether your problem is urgent or not. If you indicate it is urgent, provide a clear date/time by which you need a response or resolution.
What we have seen with previous challenges during the Release Post Assembly stage is some difficulty is encountered by the Release Post Manager because of a problem with their local development environment (Ruby setup, permissions, gems, etc.) or git conflicts. You should be familiar with git, Ruby, and the command line. There are a few resources that you can use to diagnose and resolve the issue at hand:
Following your best judgement with the resolution of the incident, record the diagnosis and the steps taken to resolve so that we can improve the release post process and our preparedness. Deposit this info in a new issue or as part of the current release post retrospective.
Should you exhaust your ability to resolve your blocker quickly mention the Technical Advisor in #dev-escalation channel and cross-post in #release-post channel to ask for help, and make others aware that there may be a delay in release post deployment.
Describe your blocker in detail, screenshots, videos, etc. can assist in diagnosing the problem. Indicate whether your problem is urgent or not. If you indicate it is urgent, provide a clear date/time by which you need a response or resolution.
The Release Post Deployment is a critical and time-sensitive operation. Please respond thoughtfully and quickly.
Following your best judgement with the following:
Release post content assembly on the 18th and release post deployment on the 22nd are time sensitive with multiple dependencies across various departments. GitLab team members often voluntarily go out of their way to assist with blockers found during these two time-sensitive procedures, but it can be confusing as to who is doing what to resolve an active blocking incident. Some procedural detail to our response efforts is shown below.
Due to the time-sensitive nature of both key Release Post actions, assembly and deployment, the initial response time must be very quick, within 15 minutes. Incident resolution should also be as quick, within 60 minutes or less, if possible.
The introduction of the technical advisor role is meant to be a coordinating role responding to blockers that occur along the way. They may work alone or in tandem with other volunteers to resolve the blocker as they see fit. They are also responsible for clearing the blocker, assembly of others, delegating response tasks including engaging in dev escalation.
There should only be one owner of the incident at any given time. There must be clear understanding of who has control of actions to investigate and remedy the incident. Use positive exchange of control, that is pass control to another person who will now be in charge. The extreme example is from aviation where pilots exchange control in a manner like the following where you might hear "your airplane" to pass control followed by "my airplane" from the second pilot to accept control followed by the acknowledgement and release of control from the initiating pilot with "your airplane." This avoids multiple people working at cross purposes from each other. Pilots operating an airplane is an extreme example, but it shows how to use clear language in your efforts to resolve the incident as to who is doing what. Only one person should be have control at a time. Similarly, the person taking action should declare their intent, "I'm going to merge master into the 13.8 release post branch and resolve any conflicts."
#dev-escalation; mentions the Technical Advisor for this release detailing the nature of the blocker and its severity.release-post-13.8-deploy-failure. They share that channel with #release-post for others to follow along.See also: Google SRE Ch. 14
Anyone can contribute to technical issues that support the Release Post Process with the burden being mostly on the current volunteer tech advisor. The following outlines how to manage active and upcoming issues.
Use the ~Release Post::Tech Advisor labels for issues that require changes to the tools that facilitate the delivery of a release post. Create issues for lower priority challenges that arise during the milestone or as an artifact of decisions made during a retrospective. Creating an issue for immediate incident response isn't required since the delivery of the release post requires quick resolution and synchronous communication.
This board organizes these labeled issues into a familiar software development workflow. When working on an issue, assign yourself and strive to keep the issue up-to-date with the proper workflow label and weekly async updates. The backlog of this board will be maintained/prioritized by Product Operations as the DRI of the Release Post but Technical Advisors are also welcome to make recommendations and apply milestones to the issues.
It's unlikely that one technical advisor will serve in back-to-back milestones. Therefore, clearly communicating with the incoming technical advisor about the state of issues as part of release post retrospective and kickoff is a good idea. To do so:
Should you prefer to continue to contribute to an issue under active development after your volunteer rotation, that's great. In that situation, make it clear through assignments and issue updates that you will be the DRI.
The Release Post Manager will solicit MVP nominations via an MVP Issue and instructions in the Release Post MR.
The Release Post Manager will choose an MVP from the nominations and conversation. 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 top feature of the release is mentioned right after the MVP section, prior to other primary features. An image or video and documentation links are required. The TW lead will pay close attention to the content of this item, as it is the "headline" feature for the release and it's especially important to get it right.
If you would like a feature to be considered for a top feature, reach out to the VP of Product and the Release Post Manager on Slack in #release-post by the 15th of the month. Let them know which feature you want considered by linking to the release post item MR. The release post manager will provide the VPP with a list of all primary features in the current release and make a recommendation for the top feature. The VPP will make their selection, or if no feedback is provided, the release post manager will choose the top feature.
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.
All release post primary features should be reviewed by the TW reviewer.
To identify the primary features, look for primary directly beneath features in the RP .yml file:
features:
primary:
Other relevant improvements in GitLab that follow after top and primary features. Images or videos aren't required, but are recommended. All release post Secondary features should be reviewed by the TW reviewer.
If the secondary feature is promoted to a primary feature, the PM or EM will be asked to supply an image on short notice.
To identify the secondary features, look for secondary directly beneath features in the RP .yml file:
features:
secondary:
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: "Do great things with this feature"
available_in: [core, premium, ultimate]
documentation_link: 'https://docs.gitlab.com/ee/ci/multi_project_pipelines.html#multi-project-pipeline-visualization-premium'
image_url: '/images/topics/multi-project_pipelines.png'
reporter: bikebilly
stage: secure
categories:
- "Application Security Testing"
- "SAST"
issue_url: 'https://gitlab.com/gitlab-org/gitlab/issues/1234'
description: |
Use present tense, and speak about "you" instead of "the user."
Describe how the new functionality is beneficial. Use phrases that start with, "In previous versions of GitLab, you couldn't... Now you can..."
[Add another link](#link) if needed.
Content of the description should adhere to the Marketing editorial team’s style guide.
Do not include UI navigation instructions in the feature's description. These instructions should be contained in the relevant documentation.
The second line of the content block should indicate whether the feature is a top, 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 and for the top feature replace primary with top.
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 (Free, Premium, Ultimate).
available_in: availability of that feature in GitLab:
[core, premium, ultimate][premium, ultimate][ultimate]Important note: GitLab Free tier is referenced as core in the data file. This is intentional and the page templates will apply the proper tier name on the frontend.
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 and Ultimate under self-managed and SaaS.
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 SaaS 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, silver, gold][silver, gold][gold]You can also mix the GitLab.com badges with the self-managed badges; however, for this to work, the gitlab_com variable must be set to false:
available_in:
[free, silver, gold, premium, ultimate] and set gitlab_com: false[core, premium, ultimate, silver, gold] and set gitlab_com: false[premium, ultimate, gold] and set gitlab_com: falseFrom time to time a feature may be developed behind a feature flag and made available slowly to larger audiences. If this is the case, do not include the item in the release post unless you are deliberately seeking beta testers. This may result in a feature issue being closed in a milestone earlier than it is announced.
If you are deliberately seeking beta tests, include the release post as well as instructions on how to enable the feature and provide feedback.
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 top and primary features, optional for secondary features.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. Try to avoid linking to a confidential issue so the wider community can get context about the change.
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, Product Managers and Product Designers.
The Release Post manager will post notifications and share reminders to collect contributions for usability improvements, performance improvements, and bugs. Engineering Managers can contribute to performance improvements and both Engineering Managers and Product Managers can contribute to bug fixes. Both Product Managers and Product Designers can contribute to usability improvements.
For items that are feature flagged, it is recommended they are enabled by default by the 15th to ensure inclusion into the self-managed release.
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 an extras content block:
extras:
header: "GitLab SaaS Performance Improvements"
blocks:
- title: "Example performance improvement"
description: | # supports markdown
Accelerate modern DevOps. Producat velocitatem quacum fiducia, sine securitate sacrificium, et visibilis DevOps in victoria!
Multiple blocks:
extras:
header: "GitLab SaaS Performance Improvements"
blocks:
- title: "Example performance improvement"
description: | # supports markdown
Accelerate modern DevOps. Producat velocitatem quacum fiducia, sine securitate sacrificium, et visibilis DevOps in victoria!
- title: "Another performance improvement"
description: | # supports markdown
Uno fonte veritatis!
Below you'll find info on how to announce deprecations and removals in GitLab Docs. As of 14.5, deprecations are announced and maintained in Docs and linked to from the release post. Please review GitLab's overall deprecation and removal definition and policies here before announcing any deprecations or removals.
This video walkthrough will help you understand the difference between deprecations and removals (however, it refers to the previous deprecation process, see Creating a deprecation entry for up-to-date steps).
To be added by Product Managers or Engineering Managers and merged by Technical Writers at least 3 milestones ahead of the planned removal date. For example, if the intended removal milestone is 15.0, given the following release schedule: 14.8, 14.9, 14.10, 15.0 – 14.8 is the third milestone preceding intended removal.
All deprecations will be published by milestone in GitLab Docs via the workflow outlined below. Deprecations are not listed individually on the release post page.
Starting with 14.5, specific deprecations are only published to the Deprecations documentation page, which is the single source of truth.
Deprecation notices should be added to the documentation per the deprecation policy.
A deprecation must have an initial announcement in the docs, notifying the community at least two releases in advance of the planned removal. We recommend to announce deprecations, especially if it's a breaking change, as soon as the planned milestone is known.
Create deprecation MRs as soon as possible and no later than the 10th of the month.
Like all other content block MRs, they must be merged by the 17th of the month to be included in the release post.
The release post contains a link to the Deprecations page in the docs.
To add a new notice:
gitlab-org/gitlab project..yml file in the data/deprecations folder. Use data/deprecations/templates/example.yml as the template. Name the file XX-YY-feature-name.yml, where XX-YY is the milestone of the initial deprecation announcement. For example, 14-7-pseudonymizer.yml.breaking_change value from false to true.pick into X.Y label to the MR.If you have multiple deprecation notices for your category, create a separate .yml file and MR for each.
No other changes are required. Don't edit the features.yml file until the feature is removed from the product.
If you want to bundle multiple deprecations in one MR, for example if it's a group of dependent deprecations that will happen on the same date as "all or none," reach out and first discuss this with the Release Post Manager.
Per GitLab's Versioning Policy, non-backwards-compatible and breaking changes should be delayed until a major release (X.0), and backwards-compatible changes can be introduced in a minor release.
Watch the video below to better understand how to create deprecation entries:
To be added by Product Managers or Engineering Managers and merged by Technical Writers during the milestone in which the removal will happen. To reduce confusion for customers, removal announcements should not be merged into Docs until the code removal has happened in the product.
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.
All removals will be published by milestone in GitLab Docs via the workflow outlined below. A removal will also be listed on the release post page for the milestone in which it happens.
To add a new notice:
gitlab-org/gitlab project..yml file in the data/removals/XX_YY directory where XX_YY is the milestone in which the removal will take place. Create the directory if it does not yet exist.data/removals/templates/example.yml as the template. Name the file XX-YY-feature-name.yml, where XX-YY is the milestone of the removal. For example, 15-0-unicorn.yml.breaking_change value as true.pick into X.Y label to the MR.If you have multiple removal notices for your category, create a separate .yml file and MR for each.
The /data/features.yml file should be updated soon after the feature is removed.
If the removal is a breaking change, add the breaking change label to the MR.
When approved, include the "Ready" label in the MR before merging.
This process is very similar to creating an entry, with the difference being that the YAML file already exists.
To edit an existing entry:
gitlab-org/gitlab project..yml file in the data/deprecations or data/removals directory.To be added by Product Managers or Engineering Managers and merged by Engineering Managers.
Describe any considerations administrators should have when upgrading to this version. These could be warnings about potential data loss, recommendations for maintenance beforehand, and other similar concerns.
Considerations for future upgrades should be noted in the deprecations sections.
One notable example was in %12.10, we required administrators to migrate from Postgres 10 to Postgres 11.
Upgrade items go in the same directory as regular release post items. See the upgrade template to create an upgrade notice. Create one .yml file in the /data/release_posts/unreleased/ folder, using the following content block for each notice:
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.
Major releases happen once a year and start a new versioning cycle: 14.0 - 14.10 –> 15.0 and so on. Contribution to and management of content for major releases follows the same schedule as monthly releases. But for major releases, the release post manager can expect some extra coordination and communication from the Social, PR, and Marketing teams, due to extra activities and needs for a major release. Additionally, during a major release, the release post manager may need to support Product Operations or PM volunteers managing communication of removals that are breaking changes.
Product Operations will lead the communication of breaking changes for major releases as part of the release post. It is important the breaking changes be flagged for SaaS users prior to the rollout of the updates in the major version, so they are prepared and their workflow is not unexpectedly disrupted. Beginning as early as 3 milestones ahead of the major release, Product operations will start communictions/coordination for announcements and a breaking changes blog. Starting as early as 2 milestones ahead of the major release, Product Operations we will use the broadcast message feature to communicate upcoming breaking changes with SaaS users.
Product Operations initiates breaking changes communications when they're assigned an automated GitLab issue, with a task list and timeline. These communications rampup three minor releases before the major release. For example: if the major 15.0 release is planned for May 22, the communications rampup with the automated issue being generated during release 14.8.
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 select "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-nocookie.com/embed/eH-GuoqlweM"
description: |
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quae, provident.
/embed/ video URL from YouTube. Follow the steps
described on the Markdown guide to find the correct path.https://www.youtube-nocookie.com/ will allow YouTube videos to display in the review app correctly.Loading HTML videos from the source also work with no further adjustments. For example:
video: '/images/13_8/create_code_review-click-drag-multi-line-comments.mp4'
When added to an entry that supports Markdown, 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.
To run the project locally:
In the terminal, go to the www-gitlab-com project. Depending where you cloned it:
cd /path/to/www-gitlab-com
Install dependencies:
bundle install
yarn
http://127.0.0.1:4567/ instead of https://about.gitlab.com/. For example, http://127.0.0.1:4567/releases/2021/09/22/gitlab-14-3-released/.Important note: Feature order should not be changed without approval from the Release Post Manager.
Primary feature content blocks are sorted alphabetically by file name so if necessary, the ordering can be affected 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 are first grouped by stage and within each stage sorted alphabetically by title. Features with no specified stage are grouped last. In release 13.10 and prior, bug fixes, performance improvements, and usability sections were also part of this automated sort order. Starting with release 13.11, bugs, performance improvement, and usability sections were changed from secondary features to tertiary features, so they now will automatically come after the secondary features and prior to the Deprecations Removals and Upgrades sections.
Sometimes, the height of the secondary features content will be much longer in the left or right column, resulting in white space. In that case, you can force a block of content from the left to the right or vice versa by adding a force_left: true or force_right: true to an entry's yml file. (See this MR as an example.)
The release post branch and most of the related directories, files, issues, and MRs are automatically created when release:start Rake task automatically runs on the 3rd of the month.
If the script fails to run or there are pipeline issues, you can run bundle exec rake release:start yourself to make the following things happen:
release-X-Y, which is based on the version you
provided above.git branch -D release-X-Y)
if you want to re-run the script.master, and pulls from
origin (this should be the default remote pointing to the gitlab-com/www-gitlab-com repo,
you can check with git remote -v).doc/templates/blog/monthly_release_blog_template.html.md. It replaces the
stub X.Y values with the version you provided in the first step.data/release_posts/X_Y/.
If it exists, the script stops and exits. You'll need to delete this directory
if you want to re-run the script.data/release_posts/X_Y/mvp.yml).data/release_post_managers.yml:@release_post_manager: manager@tw_lead: structural_check@tech_advisor: technical_advisor@pmm_lead: messagingX-Y, X_Y, YYYY, MM, DD, _MILESTONE_ with the appropriate values based on the current date and milestone.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 element | 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 Premium 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: ) |
Important note: GitLab Free tier is referenced as core in the data file. This is intentional and the page templates will apply the proper tier name on the frontend.
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 a 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: If you find problems with the release post item generator, questions should be posted in Slack #release-post or add feedback to the release post retrospective issue, tagging the release post technical advisor.
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.
In preparation for content assembly on the 18th of the month, the Release Post Manager should ensure their local dev environment is up to date (e.g., running latest version of Ruby). Follow the steps in the "Content assembly and initial review" section of the release post MR checklist to prepare a local dev environment in advance.
The development.md contains steps to setup your local development environment.
Here are some of the common errors that a user might encounter where it may not be clear as what to do.
You are missing a required Ruby Gem
You might receive obscure error such as this:
Traceback (most recent call last):
6: from ./bin/release-post-item:5:in `<main>'
5: from ./bin/release-post-item:5:in `require_relative'
4: from /Users/chase/work/www-gitlab-com/lib/release_posts.rb:13:in `<top (required)>'
3: from /Users/chase/work/www-gitlab-com/lib/release_posts.rb:13:in `require_relative'
2: from /Users/chase/work/www-gitlab-com/lib/release_posts/post_entry.rb:6:in `<top (required)>'
1: from /Users/chase/.asdf/installs/ruby/2.6.6/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:117:in `require'
/Users/chase/.asdf/installs/ruby/2.6.6/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:117:in `require': cannot load such file -- styled_yaml (LoadError)
In this case, Ruby is trying to load a file named styled_yaml. It's not clear that this is a gem (a self-contained Ruby library), but the require statement in the output is a clue that there is some unresolved dependency here. The action you should take in this case is to run bundle install. You can also run ./bin/doctor and it should provide guidance on what to do. If you're uncomfortable or encounter have difficulty here, you can reach out to the release post DRI for advisement.
Ruby mismatch
If you have a Ruby version manager installed, you may receive an error in your terminal along the lines of ruby 3.0.0 Not installed. Run "asdf install ruby 3.0.0"
It's possible that your Ruby version is out of date with what is required to run handbook scripts. You should be able to run ./bin/doctor to compare your current Ruby version with that in the .tool-versions file.
The action you can take is to install the required Ruby version
To install Ruby in the most popular Ruby version managers, try:
asdf install ruby 3.0.0brew upgrade rbenv ruby-build && rbenv install 3.0.0rvm install 3.0.0If you're uncomfortable or encounter have difficulty here, you can reach out to the release post DRI for advisement.
Note that the handbook currently suggests rvm, while engineering has adopted asdf. You may find other references to rbenv in this documentation too. Any of these are fine, but they all work a bit differently and you only need one Ruby version manager installed.
It is also possible that your ruby version manager is misconfigured or your settings have been altered because of an upgrade to macOS especially from earlier versions to Catalina or higher. It's difficult to suggest an action for this scenario, you may want to reach out to the release post DRI for advisement.
Gems install correctly, but you still have a missing gem error
The ruby gem package manager is called bundler. Depending on the version of bundler you have installed, it is possible to configure bundler to install gems in a location different from the usual (and required) location by passing the --path that_other_directory are remembered between invocations and will be stored in ./.bundle/config or in ./bundle/config.
If you look in the ./bundle/config file you might see:
BUNDLE_PATH: "that_other_directory"
The action you can take here is to edit that file ./bundle/config and possibly ./bundle/config to remove the BUNDLE_PATH setting and re-run bundle install. You may also want to remove the that_other_directory which is often vendor. If you're uncomfortable or encounter have difficulty here, you can reach out to the release post DRI for advisement.
Locking support
You might encounter a message like this about locking support when you push a local commit to origin.
Locking support detected on remote "origin". Consider enabling it with:
$ git config lfs.https://work-gitlab/gitlab-com/www-gitlab-com.git/info/lfs.locksverify true
You can probably safely ignore this suggestion. More documentation on Git LFS file locking.
JAMF and git-lfs conflict
In the process of trying to push your commits to gitlab.com git is trying to verify the SSL cert. If you have JAMF installed (and you should for compliance reasons), git might find a different certificate for gitlab.com and throw an error about Post "https://gitlab.com/gitlab-com/www-gitlab-com.git/info/lfs/locks/verify": x509: certificate signed by unknown authority
error: failed to push some refs to 'gitlab.com:gitlab-com/www-gitlab-com.git'.
The action you can take here is to contact IT
More information can be found in this issue.
If you have trouble running the rake task, you can check the following troubleshooting steps:
gitlab-org/gitlab project's Ruby version. You can check with ruby -v.bundle install.gem install bundler:2.1.4.If you rebase the branch of a deprecations or removals MR, there might be multiple merge conflicts in the deprecations.md or removals.md. Do not resolve individual
merge conflicts from your IDE. Instead, use the removals rake task to update the file and resolve the merge conflicts.
To resolve merge conflicts:
In the branch you checked out in the gitlab-org/gitlab project, run the deprecations or removals Rake task:
# For deprecations
bin/rake gitlab:docs:compile_deprecations
# For removals
bin/rake gitlab:docs:compile_removals
Stage your changes:
git add .
Continue the rebase:
git rebase --continue
If you get merge conflicts after you continue the rebase, it's possible that deprecations.md or removals.md is still out of date with
the latest changes in the yml. If this occurs, complete the steps again until you clear the merge conflict.
The release post MR template is our checklist for every release. Let's keep it up-to-date! :)
www-gitlab-comIn order to display a list of deprecations and removals in the Release Post, an index must be generated from the gitlab project and added to data/release_posts/xx_y in the www-gitlab-com project.
gitlab projectbin/rake gitlab:docs:write_deprecationsbin/rake gitlab:docs:write_removals/data/release_posts/xx_y in the www-gitlab-com projectdeprecations: to the first line of the deprecations indexremovals: to the first line of the removals indexname: to feature_name: in both filesThe Delivery team is responsible for creating release posts for patch and security releases.
Release posts should live in sites/uncategorized/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: releasesVideo walkthrough of the process
"What's new" can be seen by clicking on the ? icon in the navigation menu of GitLab and choosing "What's new."
The What's New MR will be initiated by the Release Post Manager on the 20th, finalized on the 21st, and typically get merged by a maintainer 2 to 4 hours AFTER the release post is live on the 22nd. The exact timing of the merge depends on the availability of a maintainer to merge it**
gitlab.com/gitlab-org/gitlab project
gitlab/data/whats_new directory.YYYYMMDD00001_XX_YY.yml - for example, the 13.4 entry is titled 202009300001_13_04.yml.https://img.youtube.com/vi/[insert-youtube-video-id-here]/hqdefault.jpg. For cases where a video thumbnail doesn't look great, consider using a generic image from the source/images/growth directory.https://about.gitlab.com/images/X_Y/XXXXXXX.XXX Make sure you provide a full URL for the YAML entry. Ex: https://about.gitlab.com/images/13_7/reviewers_sidebar.png.https://about.gitlab.com/images/ci/gitlab-ci-cd-logo_2x.png) or omit the image_url.milestone (it's ok if it says "expired") and labels whats new and release post.@fseifoddni @brhea and VP Product @david as Reviewers and @mention them in the MR to complete their review by the 21st.maintainer. It is recommended to communicate directly to the maintainer that the MR is time sensitive to avoid unnecessary delays.IMPORTANT: The MR should not be merged until after the release post is live on the 22nd or the images will not display. After the release post is live, but before merging, the branch should be checked out and the content checked in GDK to make sure that all images are displaying, links are accurate, and that the What's New items are part of the final release post. Only once those are confirmed should the MR be merged. Typically this means the What's New content will be live on the 23rd or 24th, depending on maintainer reviews.