Skip to content

2019-Q2 Recommendations for Release: Create a Release and update it

Part 1: JTBD

When tracking important deliverables in my project, I want to easily create and manage release entries in GitLab, so I can provide a packaged software, notes, and files for people to use.

Part 2: Experience Recommendations

Click me to collapse/fold tasks list
  • After completing the Experience Baseline for a JTBD, create a “{{YYYY}}{{Quarter}} Recommendations for…” issue for each JTBD and include them in the Part 2: Experience Recommendations sub-epic.
  • Brainstorm opportunities to fix or improve areas of the experience.
  • Use the findings from the Emotional Grading scale to determine areas of immediate focus. For example, if parts of the experience received a “Negative” Emotional Grade, consider addressing those first.
  • Create an issue for each recommendation and link them to the corresponding JTBD recommendations issue.
  • Think iteratively, and create dependencies where appropriate, remembering that sometimes the order of what we release is just as important as what we release.
  • If you need to break recommendations into phases or over multiple milestones, create multiple epics and use the Category Maturity Definitions in the title of each epic: Minimal, Viable, Complete, or Lovable.

Why we care about Releases

Release Orchestration is the ability to coordinate complex releases, particularly across projects, in an efficient way that leverages as-code behaviours as much as possible, but also recognises that there are manual steps and coordination points involving human decisions throughout software delivery in the enterprise.

At GitLab, we want to solve for automated, continuous delivery workflows first. We’d much rather see the people doing release management work to be enabled by our tooling to focus on the hard, human problems instead of the rote administration of releases.

The Releases functionality is part of our key deliverables to achieve a viable maturity level. Currently, we are at the Minimal level: a minimal foundation so people see where we’re going and to validate customer need.

Read more on Category Vision - Release Orchestration

Personas

  • Release Managers
  • Automation engineers who are working on releases
  • Developers involved in executing releases
  • Users of a project who aren’t necessarily part of the core team. This can be people who use a project's code/binary but are not otherwise involved, and just want to be aware when a new version comes out.

Releases Page today

The Releases Page MVC https://gitlab.com/gitlab-org/gitlab-ce/issues/41766 added the ability to distribute release assets/downloads within GitLab. There is a read-only Releases page which allow users to see and download releases, but only allow their creation and management via API.

Releases are created when you add release notes to a tag. Tags that don’t have a release associated with them won’t show up on the Releases page. If you haven’t create a Release yet, but have made tags, the Releases page is displayed empty. All tags live separately in a different page that includes tags with and without release notes.

Pain points

  • Creating and managing a release is currently only possible through the Releases API.
  • Releases are created via Tags, but there’s no clear differentiation between lightweight versus annotated tags.
  • Inability to track project status at a high level within GitLab’s interface.
  • Releases in GitLab are not yet well associated with other data that exists in the single application.
  • Managing releases in GitLab from a traditional, manual or semi-automated release checklist point of view is difficult. We create manual tasks and check them off as we go. Examples: gitlab-org/release/tasks#462 (closed) and gitlab-org/release/tasks#460 (closed) .

Recommendations

We’ve started delivering on release orchestration features but can do a lot to improve. From this issue: #431 (closed), you can see there was more confusion around how Releases are created, where they live in the UI, and the relationship between Tags and Releases within GitLab.

The overall recommendation is to address the workflow to improve the use of the Releases feature, that touches different areas of the product (Releases, Tags, Documentation). Define a release-first approach, that is appropriate for the ability to coordinate complex releases, particularly across projects.

Allow users to fully manage Releases from the application UI

Creating and managing an existing release is currently only possible through the Releases API, and the Tags page. This would be better if it was available as a front-end feature built in for Releases in a single place.

Make better distinction between Tags and Releases

The use of tags between Releases and Tags pages is confusing. The workflow can become unclear once the user promotes a tag to release (and vice versa).

Adopt the Release-first approach: update communication UI to display Release Title, release message, and Tag version. Mention in the helper text the relationship between tag-release, but make clear to users they are creating a Release.

Allow user to create a Tag, and to add Annotated tags that will turn the tag into a Release. Typically, people use tags functionality to mark points (v1.0,v2.0and so on) that correspond to software release cycles. Annotated tags store extra metadata such as author name, release notes, tag-message, and date as full objects in the Git database. All this data is important for a public release of your project.

Improve discoverability of Releases

At the project main page we have a bar that summarizes some information about the project. Update the project the homepage: the Tags option will be swapped out with Releases. This change was a ux-debt skipped during the Releases Page MVC.

We can also direct links to Releases and their assets.

Improve the UI of the Releases page

The current design of the Releases page makes it hard to distinguish releases and provide high quality download links. Improve and clean-up the UI: Improve headers, spacing, and responsiveness.

Display the Releases page automatically organised based on Git tags. Display latest Release first. Display Upcoming Release based on git date.

Provide a link to the latest version of the software, without having to edit the url reference each time I push a new version to modify the link.

Improve empty state message for releases

The current empty state describes releases but link the user to the Tags documentation. Change the target link and update content to:

Releases are based on Git tags and mark specific points in a project's development history. They communicate information about the type of change, and deliver on prepared, often compiled, versions of the software to be reused elsewhere.

Make Release artefacts easier to find and download

The assets download options are hidden in a dropdown menu styled as text. Improve it to be more visible (button-dropdown, or inline list of download options).

Once #56022 is completed, we have a way to generate releases directly in the .gitlab-ci.yml and point to a URL as artifact. Be mindful that more artefact types will be available in the future.

Improve communication UI for naming a Tag for Release

While creating a new tag, there's no indication of what's the best way to name my tag (best practices, formating, etc). The Release notes text in the create tag field is confusing. A helper text is displayed and reads Optionally, add release notes to the tag. They will be stored in the GitLab database and displayed on the tags page. Does this mean the tag will create a new release?

Add formatting examples and include reference to any documentation or more information the user can follow.

Improve the UI of the Tags page

The current design of the tags page makes it hard to distinguish releases vs tags, and to provide high quality download links. Improve and clean-up the UI to differentiate Tags vs. Releases. Improve headers, spacing, and responsiveness.

Improve the Tags and Releases documentation

The documentation is scattered across different pages, and focus on the creation of Tags with release notes added to it. Improve our documentation to include a clear path to how users can create and manage Tags, making the relationship tag/release more clear. It simply starts saying that I can Start by giving a description to the Release and including its assets.

Align language between docs and application UI:

  • The docs stated that There are several ways to add release note
  • The empty state in the application UI, in the tags page, reads At the moment, you can create Release entries via the Releases API

We should remove the legacy page https://docs.gitlab.com/ee/workflow/releases.html, and redirect to the new Releases CURD page.

Inconsistent empty states

The empty state message style in the Tags page is different from the one I in Releases. It is missing an illustration, and the overall layout does not comply with the Pajamas guidelines.

Clean-up the empty state for Tags to be consistent with the other empty state messages across the application.

Allow users to filter and search for releases

Same as with tags, allow users to search and filter the list for specific releases.

Edited by Rayana Verissimo