Skip to content

Automatically create Release Notes from annotated tags

Release notes

When creating Releases in the UI based on a tag, you now have the ability to easily include that tag's message in the Release Notes. You can select the checkbox option in the UI and the tag's message will be appended to the Release notes section of the Release.

Problem to solve

As a user, I want to incorporate information from an annotated tag into my release notes, so that I can communicate information associated with the tag when releasing a new version of my application.

Intended users

User experience goal

The user should be able to use the create release form with the GitLab UI to add meta-data from annotated tages into the body of a release notes.

Proposal

  • In the Create release page (/-/releases/new), user sees a checkbox for adding the message of an annotated tag to the release notes.
  • Checking the checkbox will add the information to the release notes. The content won't be displayed in the Write view of the release notes box, but the user can preview the changes by clicking the Preview tab.
    • Unchecking the checkbox should remove the information from the release notes.
  • Clicking the Create release button will create a new release.
  • The user is taken to the Releases page (/-/releases) where the annotated tag comment will be displayed under a new header Tag message.
  • Clicking the Edit release button takes the user to the edit view of a given release.
    • The checkbox should not be displayed on the page anymore.
    • Instead, the Tag message is displayed as markdown in the release notes. The user can edit the content freely as plain text.

Further details

In our projects, we use a tag's annotation to provide release information like a changelog for that version.

The tag page of GitLab visualizes this message as plain text, even without line breaks. When clicking on a tag, the message has a simple, but quite nice formatting. Currently we need to create the release notes manually to get a nice formatting also on the tag list page. Unfortunately, this leads to duplicated content in a tag's detail page.

If tag's message is available, the release notes field will be pre-populate with the tag's message by default. The user will be able to edit, or remove this message, add their notes, and so on.

In the future, we could consider annotating the start and end message like this example:

<!-- tag message begin -->
This is the annotated tag's message.
<!-- tag message end -->

Permissions and Security

Follow same permission model for Releases. Only users with at least the Developer role can edit releases.

  • Add expected impact to members with no access (0)
  • Add expected impact to Guest (10) members
  • Add expected impact to Reporter (20) members
  • Add expected impact to Developer (30) members
  • Add expected impact to Maintainer (40) members
  • Add expected impact to Owner (50) members

Documentation

Yes, this change will require a documentation update to the following pages:

Availability & Testing

Available Tier

GitLab Free

Feature Usage Metrics

We can measure it by the number of releases created including the annotated tags in the release notes.

What does success look like, and how can we measure that?

What is the type of buyer?

Casey - the Release and Change Management Director

Is this a cross-stage feature?

Yes, with devopscreate.

What is the competitive advantage or differentiation for this feature?

Links / references

This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

Edited by Chris Balane