Better UX for releases and release files
Current Behavior
GitLab supports releases. Releases are basically a markdown appendix to a git tag. This allows one to make a pretty styled release page using markdown support. The markdown release description supports attachments like any other markdown field (issues, merge requests, or notes). The uploaded files are rendered directly in the markdown document. Images are embedded and other, non-renderable files are linked in the markdown page.
Problem
A lot of people use an automatic workflow to create releases, which means they are using the API. However, adding release files to the API is not straightforward. A release including a file attachment requires at least two steps:
- Upload a file via
POST /projects/:id/uploads
, which returns an URL to the uploaded file (also in markdown) - Create the release by appending or inserting the URL of the uploaded file in the release description markdown body.
Actually, one of the most popular feature issues on gitlab.com also acknowledges this. Basically, the issue asked to support releases attachments in the API although this was already inbuilt in GitLab.
On the other hand, automatically retrieving a release file is crippled. The user needs to get the release notes and then parse it to retrieve the URLs. Then, the user can query again to get the actual file(s).
Proposed Changes
I propose the following change. Let's split the markdown description and release attachments. This means a user can create a release with a description (markdown enabled) and can upload release files to it (but not via the markdown upload). These uploads are done via a dedicated upload button as part of the release create page.
This makes multiple parts in GitLab easier.
- It directly shows what are release files
- It makes the automatic creation of releases much easier, as this is only one API call
- It makes it easier to get all related files to a release
@jramsay Maybe you can chime in and tell your thoughts?