Documentation for Release page MVC

changelogs/unreleased/docs-releases-api.yml

+---
+title: Adds API documentation for releases
+merge_request: 23901
+author:
+type: added

doc/user/project/releases.md

@@ -2,11 +2,58 @@
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7.
 
-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.
+It's typical to create a [Git tag](../../university/training/topics/tags.md) at
+the moment of release to introduce a checkpoint in your source code
+history, but in most cases your users will need compiled objects or other
+assets output by your CI system to use them, not just the raw source
+code.
 
-Navigate to **Project > Releases** in order to see the list of releases of a project.
+GitLab's **Releases** are a way to track deliverables in your project. Consider them
+a snapshot in time of the source, build output, and other metadata or artifacts
+associated with a released version of your code.
+
+At the moment, you can create Release entries via the [Releases API](../../api/releases.md);
+we recommend doing this as one of the last steps in your CI/CD release pipeline.
+
+## Getting started with Releases
+
+Start by giving a [description](#release-description) to the Release and
+including its [assets](#release-assets), as follows.
+
+### Release description
+
+Every Release has a description. You can add any text you like, but we recommend
+including a changelog to describe the content of your release. This will allow
+your users to quickly scan the differences between each one you publish.
+
+NOTE: **Note:**
+[Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) and
+Release descriptions are unrelated. Description supports [markdown](../markdown.md).
+
+### Release assets
+
+You can currently add the following types of assets to each Release:
+
+- [Source code](#source-code): state of the repo at the time of the Release
+- [Links](#links): to content such as built binaries or documentation
+
+GitLab will support more asset types in the future, including objects such
+as pre-built packages, compliance/security evidence, or container images.
+
+#### Source code
+
+GitLab automatically generate `zip`, `tar.gz`, `tar.bz2` and `tar`
+archived source code from the given Git tag. These are read-only assets.
+
+#### Links
+
+A link is any URL which can point to whatever you like; documentation, built
+binaries, or other related materials. These can be both internal or external
+links from your GitLab instance.
+
+## Releases list
+
+Navigate to **Project > Releases** in order to see the list of releases for a given
+project.
 
 ![Releases list](img/releases.png)

doc/workflow/releases.md

 # Releases
 
-You can turn any git tag into a release, by adding a note to it.
-Release notes behave like any other markdown form in GitLab so you can write text and drag-n-drop files to it.
-Release notes are stored in the database of GitLab. 
+NOTE: In GitLab 11.7, we introduced the full fledged [releases](../user/project/releases.md) feature. You can still create release notes on this page, but the new method is preferred.
+
+You can add release notes to any git tag using the notes feature. Release notes 
+behave like any other markdown form in GitLab so you can write text and 
+drag-n-drop files to it. Release notes are stored in GitLab's database.
 
 There are several ways to add release notes: 
 
-* In the interface, when you create a new git tag with GitLab
+* In the interface, when you create a new git tag
 * In the interface, by adding a note to an existing git tag
-* with the GitLab API
+* Using the GitLab API
 
 ## New tag page with release notes text area