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.
- Implement dedicated read-only releases list page separate from tags located at
Project > Releases
- 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
- 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 - iftag_name
doesn't exists in the repository then it will be created onref
. 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 bycreated_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:This is considered out of scope for now https://gitlab.com/gitlab-org/gitlab-ce/issues/41766#note_124034247time
) - 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
- commit (anchor + Ttooltip:
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
Change towards project homepage:
Changes:
-
Tags
will be swapped out withReleases
Empty state
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
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.