Releases Page MVC

The following 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.

Problem to Solve

Projects regularly publish released code, but we don't currently have a first-class way to do that within GitLab. Many teams are using artifacts to do this, but this is beyond their intention (which was primarily a way to pass dependencies between jobs/stages within a pipeline.)

MVC Solution

Backend specifications:

We need the ability to distribute project release downloads properly within GitLab. As MVC we will introduce a read-only releases page which will allow you to find and download releases, and add the ability via API to add/update them.

1. Implement dedicated read-only releases list page separate from tags located at Project > Releases
2. Releases will become a first class citizen and will have a dedicated release handling REST API similar to GH.
   • Releases will depend on a tag (required metadata), but will not be an extension of a tag as they are now
   • POST /projects/:id/repository/tags/:tag_name/release => POST /api/v4/projects/:id/releases
   • Deprecate releases as release notes upon tags: POST /projects/:id/repository/tags/:tag_name/release
   • Old release api table info will be reused in new api. This means old release info will be available in new release list
3. Users will be able to provide links to released assets

Backend API

A release

{
  "name": "Bionic Beaver",
  "tag_name": "18.04"
  "description": "## changelog\n\n* line 1\n* line2",
  "description_html": "<div><h2>changelog</h2><ul><li>line1</li<li>line 2</li></ul></div>",
  "created_at": "2012-05-28T05:00:00-07:00"
  "commit": {
    "id": "2695effb5807a22ff3d138d593fd856244e155e7",
    "short_id": "2695effb",
    "title": "Initial commit",
    "created_at": "2017-07-26T11:08:53.000+02:00",
    "parent_ids": [
      "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
    ],
    "message": "Initial commit",
    "author_name": "John Smith",
    "author_email": "john@example.com",
    "authored_date": "2012-05-28T04:42:42-07:00",
    "committer_name": "Jack Smith",
    "committer_email": "jack@example.com",
    "committed_date": "2012-05-28T04:42:42-07:00"
  },
  "author": {
    "id": 1,
    "name": "Administrator",
    "username": "root",
    "state": "active",
    "avatar_url": "http://localhost:3000/uploads/-/system/user/avatar/1/avatar.png",
    "web_url": "http://localhost:3000/root"
  },
  "assets": {
    "count": 6,
    "sources": [
      {  
        "format": "zip",
        "url": "https://gitlab.com/gitlab-org/gitlab-ce/-/archive/v11.3.12/gitlab-ce-v11.3.12.zip"
      },
      {
        "format": "tar.gz",
        "url": "https://gitlab.com/gitlab-org/gitlab-ce/-/archive/v11.3.12/gitlab-ce-v11.3.12.tar.gz"
      },
      {
        "format": "tar.bz2",
        "url": "https://gitlab.com/gitlab-org/gitlab-ce/-/archive/v11.3.12/gitlab-ce-v11.3.12.tar.bz2"
      },    
      {
        "format": "tar",
        "url": "https://gitlab.com/gitlab-org/gitlab-ce/-/archive/v11.3.12/gitlab-ce-v11.3.12.tar"
      }
    ],
    "links": [
      {
         "name": "release-18.04.dmg",
         "url": "https://my-external-hosting.example.com/scrambled-url/",
         "external": true
      },
      {
         "name": "binary-linux-amd64",
         "url": "https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/v11.6.0-rc4/download?job=rspec-mysql+41%2F50",
         "external": false
      }
    ]
  }
}

Release creation

POST /projects/:id/releases

request body

{
  "name": "Bionic Beaver",
  "tag_name": "18.04",
  "description": "## changelog\n\n* line 1\n* line2",
  "ref": "stable-18-04",
  "assets": {
    "links": [
      {
         "name": "release-18.04.dmg",
         "url": "https://my-external-hosting.example.com/scrambled-url/"
      },
      {
         "name": "binary-linux-amd64",
         "url": "https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/v11.6.0-rc4/download?job=rspec-mysql+41%2F50"
      }
    ]
  }
}

• name: mandatory - release name
• tag_name: mandatory - the tag where we must create a release
• description: optional - a markdown description of the release
• ref: optional - if tag_name doesn't exists in the repository then it will be created on ref. It can be a commit SHA, another tag name, or branch name
• assets: mandatory
  • links: mandatory - an array of asset links
    • name: mandatory - the name of the asset
    • url: mandatory - the url of the asset

response

a release object

Other API endpoints:

• GET /projects/:id/releases => paginated list of relases, sorted by created_at
• GET /projects/:id/release/:tag_name => a release for the given tag
• DELETE /projects/:id/release/:tag_name => delete a release
• PUT /projects/:id/release/:tag_name => update a release

note: Deleting a release will not delete the associated tag.

How to edit and update asset links

• Users cannot edit nor delete asset links in PUT /projects/:id/release/:tag_name. Instead, we're going to introduce explicit API calls for it
  • GET /projects/:id/release/:tag_name/links ... Get asset links of a release
  • POST /projects/:id/release/:tag_name/links ... Create an asset link of a release
  • PUT /projects/:id/release/:tag_name/links/:link_id ... Update an asset link of a release
  • DELETE /projects/:id/release/:tag_name/links/:link_id ... Remove an asset link from a release

Frontend

Frontend will make a GET request using REST API

API Response

See above Backend API > A release

Plan

We (@nolith and @filipa) will be splitting the work in several iterations (MRs):

• Create an MR with the route + index page + menu entry behind a feature flag: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23687
• Create an MR with the project's page change behind the same feature flag
• Backend:
  • expand current relese data structure https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23763
  • prepare new API endpoints behind the same feature flag gitlab-org/gitlab-ce!23795
  • implements assets (both links and source archives(read-only)) https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24056
  • Support CURD operation for individual asset links in Release API https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24100
• Frontend
  • Create a Vue component to render the release block - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23697
  • Create the Vuex store with REST API request: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23796
• Remove the feature flag
• Add feature spec for Release page
• Write ~Documentation gitlab-org/gitlab-ce!23901

Mockups

Releases page (read-only):

Features:

• Release list (ordered by creation date, newest at the top)
  • commit (anchor + Ttooltip: commit title)
  • tag (anchor + Tooltip: tag)
  • creation data (Tooltip: time)
  • release author (anchor + Tooltip stating name)
  • edited date (Tooltip: time) This is considered out of scope for now https://gitlab.com/gitlab-org/gitlab-ce/issues/41766#note_124034247
  • release name
  • Asset source archives expandable anchor (Dropdown: zip, tar.gz, tar.bz2, tar download options, Icon: package)
  • Asset packages anchors (Tooltip: Download asset, Icon: doc-code)
    • Links can be provided to outside sources as a type of asset other than packages (packages can be done in a separate iteration this way)
    • If the link is not of the same base URL as the GitLab instance, (external source) is appended to the anchor
  • Markdown description
  • Loading will for now happen with a centered spinner => follow up Skeleton loading https://gitlab.com/gitlab-org/gitlab-ce/issues/55242
  • When the page is empty we will have an empty state detailed below

FE Specs

desktop-big-descriptiom

mobile

mobile-big-description

Tooltips + dropdowns

external link

Note: Only sources have a dropdown because is the same content in different archives, links should point to different resources (i.e. a linux binary, a windows installer, a macOS package). So in that sense links will be listed individually, while sources are rendered as a dropdown.

• Link assets should have the same distance towards each other as towards "source code" expandable anchor

multiple links example

Change towards project homepage:

Changes:

• Tags will be swapped out with Releases

Empty state

Empty state mockup

• Getting started with releases
• Releases mark specific points in a project's development history, communicate information about the type of change, and deliver on prepared, often compiled, versions of the software to be reused elsewhere. Currently, releases can only be created through the API.
• Open documentation
• Illustration through gitlab-svgs!181 (merged)
• Illustration: releases

Links / references

• #23553 (moved)
• #25533 (closed)
• #5894 (closed)
• #41083 (moved)
• #40368 (moved)
• #39457 (closed)

There is open source, self-hosted, forge-like software that also offers this kind of feature:

• https://github.com/shumatech/BOSSA/releases
• FusionForge : https://fusionforge.org/
• Tuleap : https://tuleap.net/

Success Measures

We should measure the number of created releases over time to ensure we're seeing this feature used.