Merge branch 'improving-releases-page' into 'master'

First pass at improving releases page

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/181048



Merged-by: Phillip Wells <pwells@gitlab.com>
Reviewed-by: Phillip Wells <pwells@gitlab.com>
Co-authored-by: Duncan <drharris@gitlab.com>
Co-authored-by: Marcin Sedlak-Jakubowski <msedlakjakubowski@gitlab.com>

doc/user/project/releases/_index.md

@@ -9,26 +9,21 @@ DETAILS:
 **Tier:** Free, Premium, Ultimate
 **Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
 
-In GitLab, a release enables you to create a snapshot of your project for your users, including
-installation packages and release notes. You can create a GitLab release on any branch. Creating a
-release also creates a [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to mark the
-release point in the source code.
+Create a release to capture a snapshot of your project that combines release notes, installation packages, and other assets for your users. Releases serve as a complete package of your project at a specific point in time, so your users can:
 
-WARNING:
-Deleting a Git tag associated with a release also deletes the release.
-
-A release can include:
+- Download the latest stable version of your software.
+- Access release notes about new features and changes.
+- Get any additional assets like installation packages, binaries, or documentation.
+- See the history of major updates to your project.
 
-- A snapshot of the source code of your repository.
-- [Generic packages](../../packages/generic_packages/_index.md) created from job artifacts.
-- Other metadata associated with a released version of your code.
-- Release notes.
+When you [create a release](#create-a-release), GitLab automatically:
 
-When you [create a release](#create-a-release):
+- Creates a Git tag to mark this specific version in the codebase.
+- Archives a snapshot of your code.
+- Generates release evidence (a JSON file for auditing and comparing releases).
 
-- GitLab automatically archives source code and associates it with the release.
-- GitLab automatically creates a JSON file that lists everything in the release,
-  so you can compare and audit releases. This file is called [release evidence](release_evidence.md).
+WARNING:
+Deleting a Git tag associated with a release also deletes the release.
 
 When you create a release, or after, you can:
 
@@ -206,6 +201,72 @@ You can use [Generic packages](../../packages/generic_packages/_index.md) to hos
 For a complete example, see the [Release assets as Generic packages](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/)
 project.
 
+Here's how to create a release with packaged assets:
+
+1. Build the package files in the pipeline
+1. Upload the package files to the [generic package repository](../../packages/generic_packages/_index.md):
+
+     ```yaml
+     Upload Package:
+       stage: deploy
+     script:
+       - |
+         curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
+          --upload-file path/to/your/file \
+          ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/${PACKAGE_NAME}/${VERSION}/filename
+     ```
+
+1. Create release with `release-cli` job:
+
+      ```yaml
+      Create Release:
+        stage: release
+        iamge: registry.gitlab.com/gitlab-org/release-cli:latest
+        rules:
+          - if: $CI_COMMIT_TAG
+        script:
+          - |
+            release-cli create \
+            --name "Release ${VERSION}" \
+            --tag-name $CI_COMMIT_TAG \
+            --description "Your release notes here" \
+            --assets-link "{\"name\":\"Asset Name\",\"url\":\"${PACKAGE_REGISTRY_URL}/filename\"}"
+      ```
+
+To create a release with packaged assets:
+
+1. From a CI/CD pipeline, build your package files.
+1. Upload the package files to the [generic package repository](../../packages/generic_packages/_index.md):
+
+   ```yaml
+   Upload Package:
+     stage: deploy
+   script:
+     - |
+       curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
+        --upload-file path/to/your/file \
+        ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/${PACKAGE_NAME}/${VERSION}/filename
+   ```
+
+1. Create a release with the `release-cli` job:
+
+   ```yaml
+   Create Release:
+     stage: release
+     iamge: registry.gitlab.com/gitlab-org/release-cli:latest
+     rules:
+       - if: $CI_COMMIT_TAG
+     script:
+       - |
+         release-cli create \
+         --name "Release ${VERSION}" \
+         --tag-name $CI_COMMIT_TAG \
+         --description "Your release notes here" \
+         --assets-link "{\"name\":\"Asset Name\",\"url\":\"${PACKAGE_REGISTRY_URL}/filename\"}"
+   ```
+
+   For every asset you want to include, add an additional `--assets-link` link.
+
 ## Upcoming releases
 
 You can create a release ahead of time by using the [Releases API](../../../api/releases/_index.md#upcoming-releases).