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:start rake task. (pipeline configuration; rake task)features.ymlextras content typeenabled 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-X-Y branch and are subject to approval by the Release Post Manager.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 activities. 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 privileges for the https://gitlab.com/gitlab-com/www-gitlab-com/ project. 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, orThe 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:
@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 <time datetime="18:00">6 pm UTC (1 pm ET / 10 am PT)</time> 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.
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:
🎺 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 the 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.
Important: If a feature being announced involves references to external business partners, you'll need to start MR draft approvals earlier. One such example would be Cloud Seed. These types of announcements require extra reviews with Gitlab leadership, business partners and Legal team. In these cases, please reach out to Prod Ops @fseifoddini or @brhea to start MR reviews at least one milestone ahead of the milestone in which you want to make the release post announcement.
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.
If your feature release will not be generally available upon initial release, please review the alpha, beta, limited, and general availability guidelines.
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.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/.@brhea), and release post DRI (@fseifoddini). Quick action: /assign_reviewer @brhea @fseifoddini RP-manager#X-Y-release-post Slack channel that the late addition has been requested with a link to the MR.@fseifoddini or @brhea.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 announcement 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, Product Designer's and Product Design Manager'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 Product Design Managers 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.PMM lead is responsible for creating a release post highlight blurb for consumption by field and PR.
The tasks are included in the release post MR template.
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, breaking changes, 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:
title length. The title should be short and deliver an easy-to-understand message Ensure the title fits nicely with the blog post's title graphic. A general guideline for title length is about 60 to 70 characters.---
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' # required - copy URL from image title section above
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/?sort=updated_desc&state=closed&milestone_title=XX.Y&label_name%5B%5D=type%3A%3Abug&first_page_size=20 - replace XX.Y with the current milestone. For example, for GitLab 15.5, the correct link is https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=updated_desc&state=closed&milestone_title=15.5&label_name%5B%5D=type%3A%3Abug&first_page_size=20 - this links to closed issues for the 15.5 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/-/issues?sort=updated_desc&state=closed&label_name[]=bug::performance&milestone_title=XX.Y - replace XX.Y with the current milestone. For example, for GitLab 15.5, the correct link is https://gitlab.com/gitlab-org/gitlab/-/issues?sort=updated_desc&state=closed&label_name[]=bug::performance&milestone_title=15.5 - this links to merged merge requests for the 15.5 milestone with the ~bug::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&label_name%5B%5D=SUS::Impacting&milestone_title=XX.Y - replace XX.Y with the current milestone. For example, for GitLab 15.5, the correct link is https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=%E2%9C%93&state=closed&label_name%5B%5D=SUS::Impacting&milestone_title=15.5 - this links to closed issues for the 15.5 milestone with the ~SUS::Impacting 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 Technical Writer who completed the release post structural check for the previous milestone 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 announcement, 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 the #dev-escalation channel and then cross-post to the #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.
We have introduced scheduled pipeline jobs that you should familiarize yourself 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 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 an 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. That channel is then shared 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 MVP section should contain:
If it is a major feature, it must be accompanied by:
top, primary, or secondary feature content block.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.
To specify the top feature, change primary to top in the selected feature's release post item .yml file:
features:
top:
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).
For the feature availability tier, use available_in with:
[core, premium, ultimate][premium, ultimate][ultimate]Important note: The GitLab Free tier is listed as core in the data file. This is intentional and the page templates will apply the proper tier name on the frontend.
For features available on both self-managed and SaaS:
gitlab_com: true, or do not include gitlab_com in the yaml file.For features available on self-managed only:
Use gitlab_com: false. For example:
available_in: [premium, ultimate]
gitlab_com: false
This setting greys out the orange badges on the GitLab SaaS row.
For features available on GitLab.com only, use available_in: with:
[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(s) 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. 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'). Multiple links are allowed.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 Design Managers.
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. Product Design Managers and Product Designers can also contribute to usability improvements. Read more about Contributing 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 have an announcement that doesn't quite fit the other content types, you can use the extras content block. If you think your announcement does fit this type, ping the release post manager and ProdOps DRI (@fseifoddini or @brhea) in #release-post for guidance.
An example is provided in the /data/release_posts/unreleased/samples/extras.yml file.
---
extras:
- title: "Example title"
description: | # supports markdown
Description
Multiple blocks:
extras:
- title: "Example title one"
description: | # supports markdown
Description one
- title: "Example title two"
description: | # supports markdown
Description two
Deprecation, removal, and breaking change announcements appear in GitLab Docs and in the release post of the announcement's corresponding milestone.
Before making an announcement, review the breaking changes, deprecations and removals guidance to ensure you:
This video will walk you through the process of making an announcement:
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 16.0, given the following release schedule: 15.9, 15.10, 15.11, 16.0, then 15.9 is the third milestone preceding intended removal.
features.yml file until the feature has been removed from the product, or the breaking change has been implemented.gitlab-org/gitlab project.data/deprecations folder.XX-YY-feature-name.yml, where XX-YY is the milestone of the initial announcement. For example, 14-7-pseudonymizer-deprecation.yml.confidential field for a Note is deprecated."omniauth_crowd gem is deprecated."internal keyword instead of confidential."omniauth_crowd gem. It will be removed and will not be replaced."breaking_change value to true and add the ~"breaking change" label to the MR. If the deprecation or planned change will not cause a breaking change (rare, but possible), use false and do not add the label.pick into X.Y label to the MR.The deprecation template provides an option to end support for a feature prior to its removal. This option should only be used in special circumstances and is not recommended for general use. Most features should be deprecated and then removed.
An End of Support milestone must be at least 3 milestones after the deprecation announcement. For example, if the deprecation announcement is made in 15.1, the End of Support milestone must be in 15.4 at the earliest. There is no requirement for the gap between the End of Support milestone and the Removal milestone.
If an End of Support milestone is announced, it will be displayed under the title of the deprecation announcement on the Deprecations page. End of Support milestones are not currently displayed in the release post.
When to define an End of Support period
Communicating End of Support
If you decide to declare an End of Support period, tag @gitlab-com/support in the MR that adds a value to the end_of_support_milestone. Share a link to the MR in #spt_managers in Slack using the following message format:
End of Support for [feature name](MR_LINK) on YYYY-MM-DD
We are announcing in X.Y that `feature_name` will be removed in X.Y and will no longer be supported beginning in X.Y.
Please see the [Terminology section of our Deprecation guidelines](https://docs.gitlab.com/ee/development/deprecation_guidelines/#terminology) for guidance on how we define End of Support.
gitlab-org/gitlab project.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.XX-YY-feature-name.yml, where XX-YY is the milestone of the removal. For example, 15-0-unicorn.yml.confidential field for a Note is removed."omniauth_crowd gem is removed."internal keyword instead of confidential."omniauth_crowd gem. It will be removed and will not be replaced."breaking_change value to true and add the ~"breaking change" label to the MR. If the removal or change is not a breaking change (rare, but possible), use false and do not add the label.pick into X.Y label to the MR.The /data/features.yml file should be updated soon after the feature is removed.
This process is very similar to creating an announcement 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:
upgrades:
- 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 videos to release post content blocks in two ways:
video: entry in the content blockdescription: of the content blockIn either case, the video must first be uploaded to GitLab's Unfiltered YouTube channel.
When adding videos to content blocks, it is important to ensure that the correct video URL is used and that the video's visibility settings are set to "Public". Follow the steps below to properly prepare a video for inclusion in a content block.
Replace youtube.com with youtube-nocookie.com. This is the URL you will use in the content block.
For example: https://www.youtube.com/watch?v=dQw4w9WgXcQ becomes https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ
In the content block, use the entry video: followed by the video's URL
video: https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ
If both a video and an image are present, the video will override the image and only the video will be displayed
When adding videos to a content block description, it is important to use the correct markup to ensure that the video is displayed correctly.
To add a video to a description, wrap the video in a video_container. This assures that the video is displayed responsively. For example:
- 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 space prior to </iframe>. -->
<figure class="video_container">
<iframe src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quae, provident.
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 and adds the author name and handle.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:.### Release notes. If there is any additional formatting, the script will fail.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.
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. See more about setting up a Ruby environment (MacOS only). You can also validate your setup by running ./bin/doctor from the terminal.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.YYYYMMDD0001_XX_YY.yml - for example, the 13.4 entry is titled 202009300001_13_04.yml.[free, premium, ultimate] in the What's New MR instead of [free, silver, gold] or core as is used in the release post items. We will streamline this discrepancy in the future, but for now, the RPM should update the values as necessary when creating the What's New MR.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.