Release posts are blog posts that announce changes to the GitLab application. This includes our regular cadence of monthly releases which happen on the 22nd of each month, and patch/security releases whenever necessary.
Release posts follow a process outlined here, and the templates that are used to create them also highlight what needs to be done, by who, and when those items are due.
Note: We're evolving our release post process! You can view and share feedback on the latest direction by viewing Scaling the release post.
The sections below also link to these templates, but they're provided here for quick reference.
Monthly releases are blog posts with an exclusive layout aiming to apprise the reader of the changes, new features, and other considerations for the new release that comes out on the 22nd of every month. They follow a process that involves collaboration across many different roles, and each persona's responsibilities are outlined on this page.
Note: Unless specifically noted otherwise, for all due dates below the exact cutoff time is the end of the day at 11:59 PM in Pacific Time.
At a high level, the process is:
| Date | Step |
|---|---|
| By the 7th | The Release Post Manager creates a branch on www-gitlab-com and MR in that project that will collect all the release post items in to a single blog entry Note for Technical Writers: to avoid potential merge conflicts later during content assembly, please do not merge updates from main to the release post branch even if you notice it falling behind. The Release Post Manager has sole responsibility of the release post branch and will take care of merging from master as part of the content assembly process on the 18th. |
| 1st - 10th | PMs contribute individual MRs for all of their content blocks (top/primary/secondary features, Deprecations, Removals, and Upgrades) as release post items. For primary items, PMs will also add the item to features.yml.EMs can also contribute individual MRs for Deprecations, Removals, and Upgrades as release post items. PMs add recurring content blocks for Omnibus improvements, deprecation warnings, and more |
| by the 15th | EMs, PMs and PDs contribute to MRs for Usability, Performance Improvements and Bug Fixes. Note: For items that are feature flagged, it is recommended they are enabled by default by this date to ensure inclusion into self-managed release. Deprecations MRs are assigned to TWs for final review/merge. |
| by the 16th | TWs (with optional PMMs, Product Designers, and PM Leader) finish review of all release post item MRs (inclusive of deprecations, removals and upgrades) TW Lead reviews usability, bugs and performance improvement MRs |
| by the 17th | EMs merge feature release post item MRs if the underlying code was merged before the 17th or manually verified to be in the release (check the release stable branch). Be aware: "Merging [code] by the 17th does not guarantee that the feature will be in the [milestone] release." Release Post Manager merges recurring MRs for usability, performance improvements and bug fixes. TW Reviewers merge deprecation MRs. Any MRs added after the 17th should be submitted against the Release Post branch, not Master. |
| on the 18th | At 8 AM PT, (3 PM UTC) the Release Post Manager aggregates all the content blocks by updating the release post branch from the master branch, and moving all the "unreleased" items into the release post branch for final content assembly.The Release Post Manager adds the MVP for the release and selects a cover image The Release post manager works with VP of Product Management to pick features highlighted and finalizes the introduction content |
| 18th - 20th | The Release Post Manager and Technical Writer perform final reviews/revisions to ensure everything is ready to publish. Any changes after 8 AM PT (3 PM UTC) on the 18th will be done via the release-X-Y branch, not master branch, and is subject to approval by the Release Post Manager. The TW Lead checks that any deprecations in the release post are also in the deprecations doc. |
The 18th - 20th can also fall on vacations or holidays. It is important for Product Managers to designate, ahead of time, who to respond to time-sensitive inquiries should they be unreachable. Release Post Managers are also empowered to make decisions and take actions after not hearing back from the product manager before the EOD on the 20th.
|
| 22nd of Month | The Release Post Manager publishes the blog post to master on the morning of the 22nd, immediately following the package itself being published by the Release team The GitLab.org Releases page will also populate the changelog via the process outlined in gitlab!44837|
Note: The specific steps that should be followed, when they are due, and the order they should be followed in are described in the Monthly release post MR template and the Monthly release post item MR template.
Each month a Product Manager, 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.
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 can not 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.
Critical path tasks:
Other key tasks:
The initial steps of creating a release post branch and the release post merge request are explained below. All subsequent steps for Release Post Manager are documented as checklist items in the merge request that gets created below.
If you have any technical problems while doing any of your release post manager duties that you can't resolve with the help of the Technical Writer or release post DRI, you can reach out for technical advisement to the Technical Advisors via the dev escalation process. When you communicate with tech advisors, always 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.
Important: Please check beforehand if you have Maintainer merge rights to the www project.
If you don't, submit an issue to request access asking for Maintainer access to project https://gitlab.com/gitlab-com/www-gitlab-com/. If you need access, model your request after this confidential issue. You will also need to inform the release post DRI as well as the Technical Writer as an FYI that it's in progress but you may need merge support.
Note: In the following sections we refer to the GitLab version as X.Y and the date of the release as YYYY/MM/22. You should replace those values with the current version and date. The day will always be the 22nd, so no need to change that.
There are two ways to create the initial monthly release post in the about.GitLab.com repository: a) using a script and b) manually. The script does exactly what you would manually, but automates the process.
In a terminal (locally), run the task:
bundle exec rake "release:monthly"
You will be asked to submit the release post date (in ISO format)
and the GitLab version (in major.minor format). If any of the two are
wrongly submitted or the release branch already exists, the task will
abort.
You can find this by going to the www-gitlab.com project and selecting Merge requests. You will be prompted to create the merge request.
The manual way can be done either locally or using the GitLab Web IDE:
gitlab.com/gitlab-com/www-gitlab-com create a new branch release-X-Y from masterrelease-X-Y branch, create the blog post file, containing the introduction and the blog post frontmatter information:
sites/uncategorized/source/releases/posts/ directory, add a new file called YYYY-MM-22-gitlab-X-Y-released.html.md by copying the
monthly release blog template.release-X-Y branch, create the release post data directory, to which features and other data will be added:
X_Y in the data/release_posts directory.data/release_posts/unreleased/samples/mvp.yml into data/release_posts/X_Y/mvp.yml.data/release_posts/unreleased/samples/cta.yml into data/release_posts/X_Y/cta.yml.sites/uncategorized/source/includes/home/ten-oh-announcement.html.haml changing all the GitLab version numbers and URLs referencing the release post to reflect the current one. Leave the announcement description as is, as you (the Release Post Manager) will change this later in the process.Important! Please be sure to use the most recent templates on master for the mvp and cta files you create, by clicking on the links provided in instructions. They can also be found when browsing the repository in the master branch.
Create a merge request with the introductory changes after the previous post has been merged and before the feature freeze date to make the post available to receive contributions from the team:
release-X-Y and the target branch master.Draft: Release post - GitLab X.Y. Prefix the title with Draft:.Use the release post template for your MR.
Now that you have created the release post MR, refer to the checklist in the MR for each action that you need to take and the due dates of each action. Keep in mind the MRs for Usability improvements, Bugs, and Performance improvements have their own checklists to be completed, including a task for the Release Post Manager to merge these MR by the 17th prior to final content assembly.
Create dedicated MRs from the sample templates for these content blocks (Usability improvements, Bugs, Performance improvements). This separation from the main Release Post MR simplifies the contribution and discussion process.
Note: The MRs for Usability improvements, Bugs, and Performance improvements provide a place for others to add their content. While the Release Post Manager isn't responsible for creating the content, they are responsible for completing the tasks assigned to them in the checklist of the templates for these MRs, on schedule.
gitlab.com/gitlab-com/www-gitlab-com project, create 3 new
branches from master: one for bugs, one for usability improvements and one for performance improvements.
Name the branches release-X-Y-bugs release-X-Y-usability-improvements and release-X-Y-performance-improvements.Draft: release-X-Y-bugs Draft: release-X-Y-usability-improvementsand
Draft: release-X-Y-performance-improvements, and use the
Release-Post-Bug-Usability-PerformanceImprovement-Block
template.release postrelease post itemTechnical Writing@mentions with the actual task owner names.release-X-Y-bugs branch, add a new file to the data/release_posts/unreleased/ folder called bugs.yml and populate it with the content of bugs.ymlrelease-X-Y-usability-improvements branch, add
a new file to the data/release_posts/unreleased/ folder called release-post-ux-improvements.yml and populate it with the content of
release-post-ux-improvements.ymlrelease-X-Y-performance-improvements branch, add
a new file to the data/release_posts/unreleased/ folder called performance_improvements.yml and populate it with the content of performance_improvements.ymlNote: 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 verifcation, reach out to the release post DRI for advisment.
./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 17th, at 11:59 PM PT (6:59 AM UTC). After this time, anyone who wants to include a change in the upcoming release post can either coordinate updates directly on the release post branch with the Release Post Manager or submit it in a separate MR, targeting the release-X-Y branch, and assign it to the Release Post Manager to merge. For more information, see our documentation 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 goThe 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 requently 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 appropximate 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 @Scott Williamson @Anoop Dawar 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 10am PT 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 @Farnoosh @axil @Saumya Upadhyaya @Michael Karampalas
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 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.
Sometiemes, 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 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 8 AM PT (3 PM UTC). 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. Deprecations are sorted by planned removal date. 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. The ordering of deprecations should not be changed.
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 Guidlines 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 tag in the VP of Product Management to choose features to highlight in the introduction and to also designate a top feature.
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 17th, at 11:59 PM PT (6:59 AM UTC). 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.
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 top:, 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. PM notifies release post manager to review.Take note of the following:
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.)/data/release_posts/x_y/ on the release X-Y branch/source/images/x_y/ on the release X-Y branchimage_url field in the release post yml file points to the image file under /source/images/x_y/#release-post to notify them you need to remove an item already merged onto the release X-Y branch.release X-Y branchfeatures.yml on masterAfter the release post is live to make edits to any content blocks (features, bugs, usability and performance improvements, deprecations, removals etc.) click "Edit in Web IDE " at the bottom of the blog post you wish to edit. You will need to make your adjustment in the correct sub-directory, for example, to add or edit the Secure example feature you would add or edit the file data/release_posts/13_10/secure_feature_example.yml in an MR against master. To remove the feature, simply remove the file as your MR. In the case of a deprecation before 14.4 you would need to make one edit to the file in each sub-directory (release) that it appeared in. For example, if a deprecation appeared in 13.10 and was removed in 14.0 you could need to edit 13.10, 13.11, and possibly the removal in 14.0.
For review and/or approval, assign to Release Post DRI, Product Operations, @fseifoddini. You can also add the current cycle's Release Post Manager, as they can Review, Approve and Merge as well.
The instructions above apply for deprecations PRIOR to 14.3. Starting in 14.3, we started adding deprecations to Docs. Therefore, to make an edit to a deprecation in 14.3 or later you need to follow the instructions above and also locate the correct .yml file to the /data/deprecations folder of the gitlab-org/gitlab project. Once complete, assign the MR to the technical writer assigned to the stage to merge it into the documentation. The next time the release post manager runs /bin/release-post-assemble it will automatically correct all previous deprecations to match with the true content from the Single Source of Truth file.
You are responsible for the content you add to the blog post. Therefore, make sure that:
data/features.yml with a screenshot accompanying the feature (if the feature is visible in the UI).
features.yml is the SSOT for displaying features across about.gitlab.com.As noted in the Release Post Item template:
Write the description of every feature as you do to regular blog posts. Please write according to the Markdown guide.
Important! Make sure to merge master into the release post branch before
pushing changes to any existing file to avoid merge conflicts. Do not rebase,
do git pull origin master then :wq.
Once the PMs have included everything they're accountable for, they should check their item in the release post MR description:
By checking your item, you will make it clear to the Release Post Manager that you have done your part in time (during the general contributions stage) and you're waiting for review. If you don't check it, it's implicit that you didn't finish your part in time, despite that's the case or not.
Once all content is reviewed and complete, add the Ready label and assign this issue to the Engineering Manager (EM). The EM is responsible for merging as soon as the implementing issue is deployed to GitLab.com, after which this content will appear on the GitLab.com Release page
and can be included in the next release post. All release post items must be merged on or before the 17th of the month. If a feature is not ready by the 17th deadline, the EM should push the release post item to the next milestone.
Vacations:
If you are on vacation before/during the release, fill all your items and create placeholders in the release post Yaml file for all the items you cannot add for whatever reason. To complete them, and to follow up with all the content you are responsible for, assign someone to take over for you and notify the Release Post Manager.
Replies:
Please respond to comments in the MR thread as soon as possible. We have a non-negotiable due date for release posts.
Documentation:
Please add the documentation_link at the same time you add a content block to the release post. When you leave it to add it later, you will probably forget it, the reviewer will ping you later on during the review stage, and you will have little time to write, get your MR reviewed, approved, merged, and available in 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:
title is no longer than 62 characters, to ensure it presents well against the blog post's title graphic.---
release_number: "X.Y"
title: "GitLab X.Y Released with Feature A and Feature B"
author: "Name Surname"
author_gitlab: gitlab.com-username
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 an MR created for bug fixes. 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 an MR created for performance improvements. 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 an MR created for usablity improvements. 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"usability_improvement_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 doc (source file at https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/update/deprecations.md#L7) is generated from the deprecations entries in https://gitlab.com/gitlab-org/gitlab/-/tree/master/data/deprecations. This is not an automatic process, so the TW assigned as the reviewer of the deprecation item must locally run a Rake task that updates the doc to include the latest deprecation entries.
While the author of the deprecations MR is responsible for creating the content, they are not responsible for updating the doc. When the deprecation entry is ready to be merged by the TW, they must:
gitlab-org/gitlab project.bin/rake gitlab:docs:compile_deprecations. If you want to double check that it worked, you can run bin/rake gitlab:docs:check_deprecations to verify that the doc is up to date.The deprecation MRs should be merged by the 17th. If merged later, it might miss the code cutoff and won't be included in the self-managed release's docs.
If a deprecation entry needs to be updated, you can use the same process. The PM updates the deprecation YAML file, and the TW reviewer runs the Rake task to update the doc before merge.
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 insures 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 trouble shoot for technical experts, which is why we're excited about this partnership!
Below are the types of problems the release post mangers may need help with.
Release Post Manager
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.
Technical Advisor
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 incdient, 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.
Release Post Manager
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.
Technical Advisor
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.
Response and Resolution SLOs 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 Role of the Technical Advisor 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 tadem 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.
Ownership, Positive Control, and Intent 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."
Timeline
#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.
To display the MVP of the month, use the example provided in this template, and adjust it to your case. Don't forget to link to the MR with the MVP's contribution.
mvp:
fullname: Dosuken Shinya # full name
gitlab: dosuken123 # gitlab.com username
description: | # supports markdown. Please link to the MR with the MVP's contribution.
Dosuken extended our [Pipelines API](http://docs.gitlab.com/ee/api/pipelines.html#list-project-pipelines)
by [adding additional search attributes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9367).
This is a huge improvement to our CI API, for example enabling queries to easily return the latest
pipeline for a specific branch, as well as a host of other possibilities. Dosuken also made a great
contribution last release, laying the foundation for
[scheduled pipelines](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10133). Thanks Dosuken!
Solicit MVP nominations in the #release-post Slack channel by sharing a link to an issue for collaboration (example: Release Post 13.6 MVP Nominations). Cross-link the message from #release-post to Slack #community-relations, #mr-coaching and #core channels. Add candidates to the MVP Nominations issue as soon as you see a contribution or a set of contributions that you think are great and should be taken into consideration for selection. Every GitLab team-member and core team member is encouraged to add suggestions to the MVP Nominations issue with a link to the contributor's issue and merge request.
Based on this discussion, the Release Post Manager will make a decision. They should not wait for consensus. There can only be one MVP.
The MVP will be prized with a gift from GitLab, usually a swag pack. :)
Important: the MVP section should briefly describe what the feature is about, link to the GitLab profile of the MVP, and link to the issue, MR, issue board, or epic that introduced the change that awarded by the MVP. If it is a major feature, it must be accompanied by a content block with a more detailed description linked from the MVP section. The MVP feature, as well as any other feature, regardless of who shipped it, must be documented and linked to the docs.
Important: remember to update data/mvps.yml with the new MVP.
The most relevant features of the release are included in the post by product managers. Classify the feature according to its relevance and to where you want to place it in the blog post:
Note: If you would like a feature to be considered for a top feature, create the release post MR with the feature as primary and reach out to the VP of Product Management and the Release Post Manager on Slack at #release-post to let them know you would like your feature to be considered. The VP of PM is the DRI for selecting the top feature and will make their choice from all primary features in the release.
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.
To identify the Top feature, look for top directly beneath features in the RP .yml file:
features:
top:
If you wish to promote a primary feature to a top feature. Edit the features .yml file and change the word primary to top. In the MR where you have edited the file, ping the release post manager to let them know about this change.
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 primary features, optional for secondary features and top feature.image_noshadow: true: if an image (image_url) already has shadow
the entry image_noshadow will remove the shadow applied with CSS by default. Optional.video: when present, overrides the image and displays the linked video instead. See the Videos
section for more information.Check the section Adding Content > Illustrations for more information.
reporter: GitLab handle of the user adding the content block to
the release post (not the feature author).
This should be the PM responsible for the feature, so in the review
phase anyone knows who they have to ping in order to get clarifications.
It is a required field.stage: the stage the feature belongs to (lowercase):
The stages display as an icon next to the product tiers' badges linking
to the stage webpage using a regex:
https://about.gitlab.com/stages-devops-lifecycle/<stage>/. We can
also override it with a custom stage URL.
Although stage is a required field, if a feature doesn't
belong to any of the stages at all, you can delete the stage
line and it won't output anything.
Besides displaying the icon, with stage set, PMs can easily
find anything that is related to their area, even if reported by
other users.
Note: team was deprecated
in December 2018 for GitLab 11.6 in favor of stage, with a follow-up iteration
introducing their respective icons.
For stages outside of the DevOps lifecycle, such as Enablement
and Growth, which don't have the same path as the other stages
(/stages-devops-lifecycle/<stage>), it is necessary to add
the stage_url to the content block to override the default path:
# Enablement
stage: enablement
stage_url: '/handbook/engineering/development/enablement/'
# Growth
stage: growth
stage_url: '/handbook/product/growth/'
category (array): Any category(ies) the feature belongs to. These are usually attached
to the feature's issue as labels. A list of categories can be found in
/data/categories.yml.
Make sure to add the category name exactly as typed on the data file.issue_url: link to the issue on GitLab.com where the feature is discussed
and developed. Using this link the reviewer can check the status of the specific
feature for consistency and additional references.
It is a required field, but can be replaced with mr_url, issueboard_url, or epic_url.
Always wrap links in single quotes ('https://example.com').issueboard_url: link to the issue board related to the feature. Not required, but available.mr_url: link to the MR that introduced the feature. Not required, but available.epic_url: link to the epic related to the feature. Not required, but available.webpage_url: link to the marketing webpage for a given feature. Not required, but available.description: |: add the feature's description in this entry.
Make sure your cursor is in the line below the pipeline symbol | intended once.
All description fields fully support Markdown, the only thing you need to be worried about is respecting the indentation.According to our Blog handbook, it's necessary to provide the source of the cover image. Fill in the entry below to display this info at the very end of the ...release.html.md blog post:
cover_img:
image_url: '#link_to_original_image'
licence: CC0 # which licence the image is available with
licence_url: '#link_to_licence'
To be added by the Distribution Product Manager.
The "upgrade barometer" section was deprecated on GitLab 11.8 and replaced with a section called "Important notes on upgrading to GitLab X.Y".
Upgrade warnings should be added to the release post only to describe important upgrade notes, such as:
If there's no relevant info to a given release, do not add this section to the post.
To be added by Engineering Managers, Product Managers and Product Designers.
The Release Post manager will create MRs, 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.
To be added by the Distribution Product Manager.
This section should contain any relevant updates for packaged software, new features, and new commands relating to the administration of self-managed GitLab instances deployed using the Omnibus package e.g. (gitlab-backup).
To be added by Product Managers and merged by Engineering Managers.
If you need an extra block to convey important info, and it doesn't fit the other blog post sections, you can use the extras block, right before deprecations (in the release post YAML datafile):
extras:
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!
For more multiple blocks, use:
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 the release post and documentation. Please also review GitLab's overall deprecation and removal definition and policies here before announcing any deprecations or removals.
To be added by Product Managers or Engineering Managers and merged in by Technical Writers. Deprecation notices should be added to the documentation per the deprecation policy.
Please watch the videos below as well as reading the info below to help clarify how to handle deprecations and removals in the release post.
A deprecation needs to have an initial announcement in the release post notifying the community at least two releases in advance of the date of planned removal. Deprecations should also be included in the documentation for at least 2 releases prior to the final removal.
Deprecation entry MRs, need to be drafted and under review by the 10th of the month and merged by the 17th of the month (just like all other content block MRs), so that self-managed customers receive notice in a timely fashion. There is no requirement to wait until the 10th to create the MR, or merge on the 17th. Deprecations can be added to the documentation, reviewed and merged as soon as they are confirmed.
Please be sure to review and understand the differences between deprecations and removals.
To create a deprecation notice:
gitlab-org/gitlab project..yml file to the data/deprecations folder, using data/deprecations/templates/example.yml as the template:
name should follow the structure of "XYZ feature or function will be deprecated at ABC time."announcement_milestone field should match the milestone when the feature was first deprecated (e.g. "14.3"). This field determines which release post will announce the deprecated feature.announcement_date field should match the date of the release when this feature was first announced as deprecated (e.g. "2021-09-22").removal_milestone field should match the milestone when the feature is planned to be removed from the product (e.g. "15.0").body should contain a brief description of the feature or functionality being removed. It is recommended that you link to the documentation. The description of the deprecation should state what actions the user should take to rectify the behavior.If you have multiple deprecation notices for your category, then you should create one .yml file and one MR per deprecation. No other changes are required and the features.yml file should not be edited until the feature is removed from the product. There are sometimes cases in which it makes sense to bundle multiple .yml files into one deprecation MR, such as if it's a group of dependent deprecations that will happen on the same date as "all or none." However, before bundling deprecations into one MR, you should reach out and first discuss with the Release Post Manager to confirm.
Per GitLab's Versioning Policy, non-backwards compatible and breaking changes are recommended for a major release, whereas backwards-compatible changes can be introduced in a minor release.
When the Release Post Manager runs the content assembly step on the 18th, all the new deprecations (meaning the deprecation files where the announcement milestone matches the current release post milestone) are included in the release post, but older ones are not. A link to the documentation page is included so a user can see the full list at any time.
To be added by Product Managers or Engineering Managers and merged by either.
Please watch this helpful video as well as reading the info below to help clarify this process for you.
A removal is an announcement in the release post notifying the community that a feature has officially been removed. Do not use the removal template until the feature is actually getting removed. Removals are announced in the release post as a deprecation at least 2 releases prior to the actual release when feature is removed. Note the differences between deprecations and removals.
When creating your removal please review the deprecation announcement to be sure that it is still accurate and the date is reflective of the most current planned removal date.
Removal items go in the same directory as regular release post items. See the removal template to create a removal notice. Create one .yml file in the /data/release_posts/unreleased/ folder, using the following content block for each notice:
removals:
- feature_name: XYZ feature or function has been removed
date_of_removal: May 22nd, 2017 # day the removal was released
reporter: bikebilly # GitLab username of the person reporting the removal
description: | # example (supports markdown)
Describe the feature that was removed. Use past tense ("feature X was removed") because the removal has already happened.
[Add another link](#link) if needed.
Don't forget to edit /data/features.yml.
If you need to set up multiple removals, notify the Release Post Manager and make use of multiple feature removal blocks in a single file:
removals:
- feature_name: XYZ feature or function has been removed
date_of_removal: May 22nd, 2017 # day the removal was released
reporter: bikebilly # GitLab username of the person reporting the removal
description: | # example (supports markdown)
Describe the feature that was removed. Use past tense ("feature X was removed") because the removal has already happened.
[Add another link](#link) if needed.
Don't forget to edit /data/features.yml.
- feature_name: ABC feature or function has been removed
date_of_removal: May 22nd, 2017. # day the removal was released
reporter: bikebilly # GitLab username of the person reporting the removal
description: | # example (supports markdown)
Describe the feature that was removed. Use past tense ("feature X was removed") because the removal has already happened.
[Add another link](#link) if needed.
Don't forget to edit /data/features.yml.
feature_name should follow the structure of "XYZ feature or function has been removed."date_of_removal should be the day the removal was released, e.g. May 22nd, 2021.reporter should be the GitLab username of the person reporting the removal.description should contain a brief description of the feature or functionality being removed.The /data/features.yml file should also be edited with the removed features deleted from the file.
Per GitLab's Versioning Policy, non-backward compatible and breaking changes are recommended for a major release, whereas backward compatible changes can be introduced in a minor release.
Once complete, assign the MR to the technical writer assigned to the stage.
If the removal is a breaking change, apply label breaking changeto the MR.
When approved, include the "Ready" label in the MR before merging.
To be added by Product Managers or Engineering Managers and merged by Engineering Managers.
Describe any considerations administrators should have when upgrading 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.
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.
It is not recommended but possible to manually affect the sort order of the secondary features. To do so a change to the content block's title is required.
The release post branch can be created with the
release:monthly Rake task
that automates most of the things that are needed for the release post merge request.
When you run bundle exec rake release:monthly, 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_posts/X_Y/cta.yml).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 an draft MR in the /gitlab-com/www-gitlab-com project will be opened and assigned to the group PM. You can continue editing and reviewing that MR from there.
If you'd like to check to see when the last pipeline ran (and if it picked up your issue) you can inspect the scheduled pipeline here.
You can also watch this overview video demonstrating how to use the release post item generator.
*Note: 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 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.
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.
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.
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.
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 the following issue: https://gitlab.com/gitlab-com/business-ops/team-member-enablement/issue-tracker/-/issues/1263#note_491341250
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.The release post MR template is our checklist for every release. Let's keep it up-to-date! :)
The Delivery team is responsible for creating release posts for patch and security releases.
Release posts should live in sites/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 will be initiated on the 20th, finalized on the 21st, and typically merged 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/data/whats_new directory of the gitlab.com/gitlab-org/gitlab project
YYYYMMDD00001_XX_YY.yml - for example, the 13.4 entry is titled 202009300001_13_04.ymlhttps://img.youtube.com/vi/[insert-youtube-video-id-here]/hqdefault.jpghttps://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.pngmaintainer.milestone (it's ok if it says "expired") and labels whats new and release post.maintainer you assigned to MR to for the merge, letting them know it's ready.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.