GitLab Release Posts


Release Blog Posts Handbook


On this page


Release posts

GitLab releases a new version every 22nd of each month, and announces it through monthly release posts.

Patch and security issues are addressed more often, whenever necessary.

Templates

To start a new release post, please choose one of these templates, and follow their instructions to insert content. Please make sure to use the most recent template available.

For patch and security releases, please make sure to specify them in the title, add the correct category:


Monthly releases

Monthly releases have an exclusive layout aiming to appraise the reader with the presentation of a new release every 2nd.

Note: The new design for monthly release posts was introduced in March 2017 with the release of GitLab 9.0. The new layout was introduced in May 2017 with the release of GitLab 9.2.

Getting started

To create a new monthly release post, add two files to the about.GitLab.com repository (consider the release of GitLab X.Y, released in YYYY/MM/DD):

Important! Please use the most recent templates for each of these files.

Merge Request

Create a merge request with the introductory changes before the kick off call to make the post available to receive contributions from the team.

Please use the release post template for your MR:

release post MR template

Authorship

Each month a Product Manager will lead the release post, being accountable for:

Stages of contribution

Monthly release posts are created in two stages:

To be able to finish our work in time, with no rush, each stage will have its due date.

Due dates

To having the release post well written and ready in time for the release date, please set due dates for:

Ideally, the review should be completed until the 4th working day before the 22nd, so that the 3rd and the 2nd working day before the release could be left for fixes and small improvements.

General contributions

Added by the team until the 6th working day before the 22nd. Please fill all the sections.

Accountability

You are responsible for the content you add to the blog post. Therefore, make sure that:

Write the description of every feature as you do to regular blog posts. Please write according to the markdown guide.

Monthly release blog post sections

Introduction

Add the introduction to the blog post file (YYYY-MM-DD-gitlab-X-Y-released.html.md), in regular markdown.

Add a short paragraph before the <!-- more --> separator, and conclude the intro below it.

Introductory paragraph (regular markdown)

<!-- more -->

Introduction (regular markdown)

CTA

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/'
  - title: Lorem ipsum dolor sit amet
  - link:

MVP

To display the MVP of the month, use the information provided in this template, and adjust it to your case. Don't forget to link to the MR with the MPV'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/ce/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!

To choose the MVP, the PM responsible for the blog post will request suggestions from colleagues and the core team. Based on that, the PM will make a decision. They should not wait for consensus. There can only be one MVP.

Features

The most relevant features of the release are included in the post by team members. Classify the feature according to its relevance and to where you want to place it in the blog post:

Top feature

The most important feature of the release, mentioned right after the MVP section. Images can be added at will in the description entry. A link to the documentation is required.

Primary features

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.

Secondary features (other improvements)

Relevant improvements in GitLab. Image is not required, but recommended.

Feature blocks

Use feature blocks to add features to the YAML data file. The layout will be applied automatically by Middleman's templating system.

Feature blocks in the YAML data file contain the following entries, as exemplified below:

- name: Pipeline Graphs
  available_in: [ce, ees, eep]
  documentation_link: 'https://docs.gitlab.com/ce/ci/pipelines.html#pipeline-graphs'
  documentation_text: "Learn more about Pipeline Graphs"
  image_url: 'https://about.gitlab.com/images/8_11/pipeline_graph2.png'
  image_noshadow: true
  description: |
    Lorem ipsum dolor sit amet, [consectetur adipisicing](#link) elit.

Feature Name

Use a short and strong name for all feature names.

Feature Availability

Use the following pattern to apply the correct badge to the feature (CE, EES, EEP).

Provide a reference link to the feature whenever possible. It can be, in this priority order:

Important: always link to the EE documentation, even if the feature is available in CE.

As follows:

Illustration (images, videos)

Check the section Adding Content > Illustrations for more information.

Feature Description

Cover image license

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 blog post:

cover_img:
  image_url: '#link_to_original_image'
  licence: CC0 # which licence the image is available with
  licence_url: '#link_to_licence'

Upgrade barometer

Describes the information about upgrading GitLab to the new version.

barometer:
  description: |
    Lorem ipsum dolor sit amet, consectetur adipisicing elit.
    Dignissimos blanditiis reprehenderit voluptate ea quidem
    eveniet similique tempore [quibusdam fugiat](#link) magni, eius,
    quasi aperiam corrupti `tempora` rerum amet totam maiores.
    Reiciendis.

Extras

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.

Deprecations

Describe the deprecations happening on that release or in upcoming releases. Let our community know about a future deprecation as soon as possible.

deprecations:
  - feature_name: Lorem ipsum dolor
    due: May 22nd, 2017. # example
    description: |  # example (supports markdown)
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
      Veritatis, quisquam.

For multiple deprecations, use multiple feature deprecation blocks:

deprecations:
  - feature_name: Lorem ipsum dolor
    due: May 22nd, 2017. # example
    description: |  # example (supports markdown)
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
      Veritatis, quisquam.
  - feature_name: Lorem ipsum dolor
    due: May 22nd, 2017. # example
    description: |  # example (supports markdown)
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
      Veritatis, quisquam.

Review

The review is performed after content has been added, so it's important to respect the due dates, otherwise reviews will have to be done repeatedly.

Ideally, the review should be completed by the 4th working day before the 22nd, so that the 3rd and the 2nd working day before the release can be left for fixes and small improvements.

Content review

The content review is performed by product managers (PMs), who will check if everything is in place, and if there's nothing missing.

Technical writers/editors will follow with copyedit and check for grammar, spelling, and typos. Please follow the checklist in the MR description to guide you through the review.

Lastly, on the 2nd day before the 22nd (or as soon as the content is ready), the post should be reviewed by a Marketing team member (PMM, CMM) to evaluate wording and messaging.

Structural Check

Once the post is filled with content, the technical writing, UX, or frontend team, will check the syntax and the content structure:

Frontmatter

Look for each entry in the frontmatter. Wrap text with double quotes and paths with single quotes to prevent the page to break due to special chars.

---
release_number: "X.X"
title: "GitLab X.X Released with Feature A and Feature B"
author: Name Surname
author_gitlab: gitlab.com-username
author_twitter: twitter-username
categories: release
image_title: '/images/X_X/X_X-cover-image.ext'
description: "GitLab 9.0 Released with XXX, YYY, ZZZ, KKK, and much more!"
twitter_image: '/images/tweets/gitlab-X-X-released.jpg'
layout: release
---

Adding content

Markdown

For entries that support markdown, use regular markdown Kramdown, as we use for all blog posts and webpages on about.GitLab.com.

Illustrations

Images

Videos

Every video should wrapped into a figure tag, as in:

<figure class="video_container">
  <iframe src="https://www.youtube.com/embed/PoBaY_rqeKA" frameborder="0" allowfullscreen="true"> </iframe>
</figure>

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).

For primary_features, you can add a video instead of an image, by using the entry video:. If present, the feature section won't display any images, only the video. Example:

# PRIMARY FEATURES
  primary:
    - name: Awesome Feature
      available_in: [ce, ees, eep]
      documentation_link: ''
      documentation_text: "Learn more"
      video: "https://www.youtube.com/embed/eH-GuoqlweM"
      description: |
        Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quae, provident.

Technical aspects

Understand how a release post is formed:

The template files form the blog post, therefore, don't need to be changed every release. The content files are the ones to be added every release with its unique content, as described by the section getting started.

To learn more how the templating system works, read through an overview on Modern Static Site Generators.