If the automated pipeline fails, the manual steps below can be done either locally or using the GitLab Web IDE:
gitlab.com/gitlab-com/www-gitlab-comcreate a new branch
release-X-Ybranch, 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.mdby copying the monthly release blog template.
sites/uncategorized/source/releases/posts/YYYY-MM-22-gitlab-X-Y-release.html.mdon line 36 and make sure to remove the backticks.
sites/uncategorized/source/releases/posts/YYYY-MM-22-gitlab-X-Y-release.html.mdon lines 3 and 4
YYrelease kickoff video" line replacing the
YY(including removing the backticks) to reference the next release in
sites/uncategorized/source/releases/posts/YYYY-MM-22-gitlab-X-Y-release.html.mdon line 41
release-X-Ybranch, create the release post data directory, to which features and other data will be added:
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-Yand the target branch
Draft: Release post - GitLab X.Y. Prefix the title with
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 for people adding content: 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. Make sure to immediately apply any suggestion you make to avoid race conditions where your suggestion is considered as applied if someone else has directly pushed a commit (example). The TW lead will review the changes anyway, so no need to ask for a pre-review.
gitlab.com/gitlab-com/www-gitlab-comproject, create 3 new branches from master: one for bugs, one for usability improvements, and one for performance improvements. Name the branches
Draft: release-X-Y-usability-improvements, and
Draft: release-X-Y-performance-improvements, and use the
release post item
@mentionswith the actual task owner names.
release-X-Y-bugsbranch, add a new file to the
data/release_posts/unreleased/folder called bugs.yml and populate it with the content of
release-X-Y-usability-improvementsbranch, 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-X-Y-performance-improvementsbranch, add a new file to the
data/release_posts/unreleased/folder called performance_improvements.yml and populate it with the content of
Release Post X.Y Retrospectiveas a title.
Note: After you have created the release post MR and all the related files, 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.
Important: This procedure applies until the 18th, at . After this time, anyone who wants to include a change in the upcoming release post can either coordinate updates directly on the release post branch with the Release Post Manager or submit it in a separate MR, targeting the
release-X-Y branch, and assign it to the Release Post Manager to merge. For more information, see our documentation on how to Develop on a feature branch.
When it is time to assemble the release post, this will be done by moving the
content block files from
data/release_posts/X_Y, and images from
Those block items comprise of the release post items that each PM creates for each feature.
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 status # confirm that content blocks and images have moved from `unreleased` to `X_Y` git add . git commit -m "Content assembly" git push origin release-x-y
If for some reason the content assembly bot fails, the simplest way to move forward is to move the files manually. There is also a video walking through the changes here.
|Manually move all the
||Note: Leave the
image_url:in each release post
/x_y/. The video above demonstrates that.
git pushand you should be good to go.
The release post assembly script moves release post content blocks and their images to the current release directory.
It uses a simple regexp to locate content files and images. It performs no validation. In the future, it would be simple to combine the functionality with the linter to reduce the number of scripts to maintain.
In preparation for content assembly on the 18th of the month, the Release Post Manager should ensure their local dev environment is up to date (e.g., running latest version of Ruby). Follow the steps in the "Content assembly and initial review" section of the release post MR checklist to prepare a local dev environment in advance.
The development.md contains steps to setup your local development environment.
Here are some of the common errors that a user might encounter where it may not be clear as what to do.
You are missing a required Ruby Gem
You might receive obscure error such as this:
Traceback (most recent call last): 6: from ./bin/release-post-item:5:in `<main>' 5: from ./bin/release-post-item:5:in `require_relative' 4: from /Users/chase/work/www-gitlab-com/lib/release_posts.rb:13:in `<top (required)>' 3: from /Users/chase/work/www-gitlab-com/lib/release_posts.rb:13:in `require_relative' 2: from /Users/chase/work/www-gitlab-com/lib/release_posts/post_entry.rb:6:in `<top (required)>' 1: from /Users/chase/.asdf/installs/ruby/2.6.6/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:117:in `require' /Users/chase/.asdf/installs/ruby/2.6.6/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:117:in `require': cannot load such file -- styled_yaml (LoadError)
In this case, Ruby is trying to load a file named
styled_yaml. It's not clear that this is a gem (a self-contained Ruby library), but the
require statement in the output is a clue that there is some unresolved dependency here. The action you should take in this case is to run
bundle install. You can also run
./bin/doctor and it should provide guidance on what to do. If you're uncomfortable or encounter have difficulty here, you can reach out to the release post DRI for advisement.
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
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.0
brew upgrade rbenv ruby-build && rbenv install 3.0.0
rvm install 3.0.0
If you're uncomfortable or encounter have difficulty here, you can reach out to the release post DRI for advisement.
Note that the handbook currently suggests
rvm, while engineering has adopted
asdf. You may find other references to
rbenv in this documentation too. Any of these are fine, but they all work a bit differently and you only need one Ruby version manager installed.
It is also possible that your ruby version manager is misconfigured or your settings have been altered because of an upgrade to macOS especially from earlier versions to Catalina or higher. It's difficult to suggest an action for this scenario, you may want to reach out to the release post DRI for advisement.
Gems install correctly, but you still have a missing gem error
The ruby gem package manager is called bundler. Depending on the version of bundler you have installed, it is possible to configure bundler to install gems in a location different from the usual (and required) location by passing the
--path that_other_directory are remembered between invocations and will be stored in
./.bundle/config or in
If you look in the
./bundle/config file you might see:
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.
JAMF and git-lfs conflict
In the process of trying to push your commits to gitlab.com git is trying to verify the SSL cert. If you have JAMF installed (and you should for compliance reasons), git might find a different certificate for gitlab.com and throw an error about
Post "https://gitlab.com/gitlab-com/www-gitlab-com.git/info/lfs/locks/verify": x509: certificate signed by unknown authority
error: failed to push some refs to 'gitlab.com:gitlab-com/www-gitlab-com.git'.
The action you can take here is to contact IT
More information can be found in this issue.