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.
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 TWs and Messaging Leads: to avoid potential merge conflicts later during content assembly, please do not merge updates from master 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 in the /data/release_posts/unreleased directory. For primary items, PMs will also add the item to features.yml.EMs can also contribute individual MRs for deprecations, removals, and upgrades as release post items in the /data/release_posts/unreleased directory.PMs add recurring content blocks for Omnibus improvements, deprecation warnings, and more |
| by the 15th | EMs, PMs and PDs contribute to MRs for Usability, Performance Improvements and Bug Fixes |
| by the 16th | TWs (with optional PMMs, Product Designers, and PM Leader) review individual release post item MRs TW Lead reviews usability, bugs and performance improvement MRs |
| by the 17th | EMs merge 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 content blocks for usability, performance improvements and bug fixes. Any MRs added after the 17th should be submitted against the Release Post branch, not Master. |
| on the 18th | At 8 AM PT, (3 PM UTC) the Release Post Manager aggregates all the content blocks by updating the release post branch from the master branch, and moving all the "unreleased" items into the release post branch for final content assembly.The Release Post Manager adds the MVP for the release and selects a cover image The Messaging lead picks a top features and/or themes to highlight and finalizes the introduction content |
| 18th - 20th | The Release post manager, Messaging Lead, and TW Lead perform final reviews/revisions to ensure everything is ready to publish. Any changes after 8 AM PT (3 PM UTC) on the 18th will be done via the release-X-Y branch, not master branch, and is subject to approval by the Release post manager. |
| 22nd of Month | The Release post manager publishes the blog post to master on the morning of the 22nd, immediately following the package itself being published by the Release team The GitLab.org Releases page will also populate the changelog via the process outlined in gitlab!44837 |
Note: The specific steps that should be followed, when they are due, and the order they should be followed in are described in the Monthly release post MR template and the Monthly release post item MR template.
Each month a Product Manager, Product Marketing Manager, Technical Writer, and an Engineering Department Technical Advisor volunteer to manage the release post, as listed in the Release Post Scheduling page. 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.
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:
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!
release-X-Y/www-gitlab-com/data/mvps.yml and data/release_posts/X_Y/mvp.ymlgit pull origin master, then :wq)#releases Slack channel and only merge once they've pinged you in Slack to confirm the packages are released, which will be sometime around 14:10 - 14:20)The initial steps of creating a release post branch and the release post merge request are explained below. All subsequent steps for Release Post Manager are documented as checklist items in the merge request that gets created below.
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 Messaging lead, Technical writing lead 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 merge rights to the www project. If you don't, submit an issue to request access and inform the release post DRI as well as the Messaging and TW leads as 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.
Locally, in a terminal, run the task:
bundle exec rake "release:monthly"
You will be asked to submit the release post date (in ISO format)
and the GitLab version (in major.minor format). If any of the two are
wrongly submitted or the release branch already exists, the task will
abort.
The manual way can be done either locally or using the GitLab Web IDE:
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/marketing/source/releases/posts/ directory, add a new file called YYYY-MM-22-gitlab-X-Y-released.html.md by copying the
monthly release blog template.release-X-Y branch, create the release post data directory, to which features and other data will be added:
X_Y in the data/release_posts directory.data/release_posts/unreleased/samples/mvp.yml into data/release_posts/X_Y/mvp.yml.data/release_posts/unreleased/samples/cta.yml into data/release_posts/X_Y/cta.yml.sites/marketing/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, it will be changed by the Messaging Lead 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.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 bugs.yml
to the data/release_posts/unreleased/ folder.release-X-Y-usability-improvements branch, add
release-post-ux-improvements.ymlrelease-X-Y-performance-improvements branch, add
performance_improvements.yml
to the data/release_posts/unreleased/ folder.Note: 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 Messaging lead and the TW lead will need to communicate about topics that are related to the release post but not relevant to all participants in the main Slack release post channel. The Release Post Manager will create a Slack channel called "X-Y-release-post-prep to facilitate communication specific to the release post leads, which will be utilized till the 21st to minimize noise in the main release post Slack channel. On the 22nd, this channel will be abandoned and all communication will default to the main release post Slack channel for the final day of collaboration.
The 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 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.
Sample post to executive stakehlders 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
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.
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 and Messaging lead to add more content blocks up until the 21st.
Keeping an eye on the various content reviews (TW, PMM and Director) for the individual release post items (content block MRs) is the 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, deprecations, removals, and upgrade notes are all sorted alphabetically by title, grouped by stage. To affect the sort order of the secondary features, a change to the content block's title is required. The release post manager should work with the product managers of the content blocks to make these changes, to ensure accuracy and alignment.
After the 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.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/deprecationmaster branchdata/release_posts/unreleased/ on the master branch
data/release_posts/unreleased/samples/ for format and sample contentfeatures: then top:, then the feature content/source/images/unreleased/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.
stagename-featurename.yml (for example, create-group-wikis.yml). Do not:
dep-something-descriptive.ymlremoval-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 and Messaging lead to add more content blocks up until the 21st.
When creating your content for a Release Post item you'll need to determine if it's a primary or secondary feature. Do this in 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, so 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. 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 (Messaging Lead, Tech Writer, 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 masterYou 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.
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 month a Product Marketing Manager (PMM) will lead the messaging and positioning for the release post. Use the handbook guidance below for messaging lead release post preparation and planning. This handbook section is your source of truth from the 18th of the previous month - 11th of the release month. After the 11th of the month, your source of truth to prepare and deliver the release post is in the monthly release post blog template.
The messaging lead is responsible for:
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.
Follow the timeline below to help you do peliminary reserach in identifying the features behign shipped in the next release, categorizing them into themes, and prioritizing the themes you'd like to focus on for the release post intro.
www-gitlab-com project
After the 11th of the month, your list of tasks to prepare and deliver the release post is in the release post MR. The latest MR can be found linked in the description of the #release-post slack channel. You can see the tasks that will appear in the MR in the monthly release post blog template.
The messaging lead orders the primary features in the release post to align with the themes they've identified and incorporated into their introduction for the release post. Primary feature content blocks are sorted alphabetically by file name so the messaging lead can affect the order of these items by adding a 2-digit numerical prefix to the file name of each individual content block. For example, 01_filename.yml, 02_another_file.yml, etc.
Secondary features 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.
In cases where the messaging lead wants to manually affect the sort order of the secondary features, a change to the content block's title is required. It is recommended this be coordinated with the release post manager so the PM and the PMM of the content block are involved as needed.
The messaging lead shares the selected theme for review from the EVP and VP of product between the 15th and 17th. You can use this template to share on the #release_post slack channel
Hi PM Team! I wanted to get some feedback on the release post themes. I see that the biggest focus of 13.6 is to make GitLab easier to use. With that, I believe we can align it to our Efficiency value driver - improving developer productivity & satisfaction. Would love your thoughts on this. Please provide your feedback by EOD 16th. Thanks! cc: @sfwgitlab @adawar
Theme 1
- Feature 1.1
- Feature 1.2
- Feature 1.3
Theme 2
- Feature 2.1
- Feature 2.2
- Feature 2.3
Theme 3
- Feature 3.1
- Feature 3.2
- Feature 3.3
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, 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 and Messaging lead don'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
author_twitter: twitter-username
categories: releases
image_title: '/images/X_Y/X_Y-cover-image.ext'
description: "GitLab X.Y Released with XXX, YYY, ZZZ, KKK, and much more!"
twitter_image: '/images/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
---
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[]=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[]=bug' - this links to closed issues for the 13.8 milestone with the ~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 that falls under their respective stage/group.
When the PM creates the release post item merge request, they should assign to the TW of their group for review (required). The process of the TW review is described in the release post item template.
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
The messaging lead writes the introduction for the release post.
Add the copy for the intro to the blog post file (YYYY-MM-DD-gitlab-X-Y-released.html.md), in regular Markdown. This file linked at the top of the release post MR. E.g. GitLab 11.2 blog post file
Introductory paragraph
Introduction
The first paragraph is the one that catches the eyes of the reader, it should be punchy giving a summary of the most significant features. This first paragraph can then be used as a summary on the homepage and on social media. It should catch attention and cause the reader to want to read more.
The following paragraphs should highlight the business value of top 3 features and link to the feature description (link using the feature headings' anchors). It's important to highlight the pain points solved and the value the feature provides.
A final paragraph can give a shout out to additional features encouraging the reader to read the full release notes to learn about all the features have that shipped. It should include the total number of new features being released, including bugs, usability improvements, performance improvements, and contributions from non-DevOps stages like Enablement. All of these should be listed in the release post, either as headers or bullet points.
@mention the PMs whose features are included the intro and ask them to review.
Examples of previous release post intros written by PMM:
The introduction or other parts of the release post written by the Messaging lead may include links to external blogs posts. It is important that the Messaging lead coordinates with authors of these external blogs to make sure they're live before the release post manager pushes the release post blog live on the 22nd.
Call-to-action buttons displayed at the end of the introduction. A CTA to the events page is added by default. Add webcasts, or custom buttons to this entry whenever necessary.
cta:
- title: Join us for an upcoming event
link: '/events/' # relative link
- title: Lorem ipsum dolor sit amet
link: 'https://example.com' # external link
To display the MVP of the month, use the example provided in this template, and adjust it to your case. Don't forget to link to the MR with the MVP's contribution.
mvp:
fullname: Dosuken Shinya # full name
gitlab: dosuken123 # gitlab.com username
description: | # supports markdown. Please link to the MR with the MVP's contribution.
Dosuken extended our [Pipelines API](http://docs.gitlab.com/ee/api/pipelines.html#list-project-pipelines)
by [adding additional search attributes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9367).
This is a huge improvement to our CI API, for example enabling queries to easily return the latest
pipeline for a specific branch, as well as a host of other possibilities. Dosuken also made a great
contribution last release, laying the foundation for
[scheduled pipelines](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10133). Thanks Dosuken!
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 messaging lead on Slack at #release-post to let them know you would like your feature to be considered. The messaging lead 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:
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: "Multi-Project Pipeline Graphs"
available_in: [premium, ultimate]
documentation_link: 'https://docs.gitlab.com/ee/ci/multi_project_pipelines.html#multi-project-pipeline-visualization-premium'
image_url: '/images/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: |
Lorem ipsum dolor sit amet, [consectetur adipisicing](#link) elit.
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]From 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:
- title: "Hello World"
description: | # supports markdown
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Consequuntur, beatae!
For more multiple blocks, use:
extras:
- title: "Hello World"
description: | # supports markdown
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Consequuntur, beatae!
- title: "Lorem"
description: | # supports markdown
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Doloremque.
To be added by Product Managers or Engineering Managers and merged by either. Deprecation notices should be added to the release post per the deprecation policy.
A deprecation is an annoucement in the release post notifying the community of a future removal. Deprecations should be included in the release post as far in advance as possible or for at least 2 releases prior to the final removal. Check out the differences between deprecations and removals.
Create a deprecation notice by creating one .yml file in the /data/release_posts/unreleased/ folder, utilizing the following content block for each notice:
deprecations:
- feature_name: Lorem ipsum dolor
due: May 22nd, 2017 # example
reporter: bikebilly # item author username
description: | # example (supports markdown)
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Veritatis, quisquam.
feature_name should follow the structure of "XYZ feature or function will be deprecated at ABC time."
The due field is defined by the future removal of that feature. The field is required, and should be set as:
description should contain a brief description of the feature or functionality being removed. It is recommended that you link to the documentation.
If the deprecation is scheduled for an upcoming release, the content should remain in the release post until it has been completed. For example, if a deprecation is announced in the 12.9 release post and scheduled to be completed in 13.0, the same content would be included in release posts 12.9, 12.10, and 13.0. Product Managers are the DRI for re-adding the deprecation to release posts until the item is completed.
If you have multiple deprecation notices for your category, then you can choose to create one MR. The MR should still consist of a deprecate_category_feature.yml file for each feature that you are deprecating.
No other changes are required and the features.yml file should not be edited until the feature is removed from the product.
Per GitLab's Versioning Policy, non-backward compatible and breaking changes are recommended for a major release, whereas backward compatible changes can be introduced in a minor release.
Once complete, assign the MR to the technical writer assigned to the stage.
When approved, include the "Ready" label in the MR before merging.
Deprecations are announced for at least 2 releases in advance of the final removal. Since the content remains the same each month, it is not necessary to get the content reviewed each time by TW and PMM. When Product Managers OR Engineering Managers are preparing the subsequent instances of a deprecation, follow these steps:
Ready label and proceed as normal for a RPITo be added by Product Managers or Engineering Managers and merged by either.
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.
Create a removal notice by creating one .yml file in the /data/release_posts/unreleased/ folder, utilizing the following content block for each notice:
removals:
- feature_name: Lorem ipsum dolor
date_of_removal: May 22nd, 2017 # example
reporter: bikebilly # item author username
description: | # example (supports markdown)
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Veritatis, quisquam.
If you need to set up multiple removals, notify the Release Post Manager and make use of multiple feature removal blocks in a single file:
removals:
- feature_name: Lorem ipsum dolor
date_of_removal: May 22nd, 2017 # example
description: | # example (supports markdown)
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Veritatis, quisquam.
- feature_name: Lorem ipsum dolor
date_of_removal: May 22nd, 2017. # example
description: | # example (supports markdown)
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Veritatis, quisquam.
feature_name should follow the structure of "XYZ feature or function has been removed."
date_of_removal should be the day the removal was releaed, e.g. May 22nd, 2021.
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.
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:
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.com/embed/eH-GuoqlweM"
description: |
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quae, provident.
Make sure to add the /embed/ video URL from YouTube. Follow the steps
described on the Markdown guide to find the correct path.
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.
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: The release post item generator is still in beta. If you find issues or have questions post them in Slack #release-post-iteration or add them to the current cycle release post retrospective issue.
The generator script can also be run on your computer.
www-gitlab-com project, and install dependencies using bundle installRun the script, providing your GitLab private access token, and the issue URL:
PRIVATE_TOKEN=<token> bin/release-post-item --no-local <issue_url>
Refer to bin/release-post-item --help for complete documentation.
The release post item linter
validates all items being merged to the data/release_posts/unreleased directory meet minimal
standards. Specifically, it checks:
stage filed maps to a valid stage key in data/stages.ymlcategories list only contains valid category names from data/categories.ymlIt does not check if:
top and primary items have an image or videoissue_url is supplied, since there are other alternativesThe schema is implemented using Rx.
The release post assembly script moves release post content blocks and their images to the current release directory.
It uses a simple regexp to locate content files and images. It performs no validation. In the future, it would be simple to combine the functionality with the linter to reduce the number of scripts to maintain.
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
The release post MR template is our checklist for every release. Let's keep it up-to-date! :)
The Delivery team is responsible for creating release posts for patch and security releases.
Release posts should live in sites/marketing/source/releases/posts. For patch and security releases,
please make sure to specify them in the title, add the correct category:
title: "GitLab Patch Release: x.y.z and x.y.z"categories: releasestitle: "GitLab Security Release: x.y.z and x.y.z"categories: releasesVideo walkthrough of the process
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.png