diff options
Diffstat (limited to 'doc/api/repositories.md')
| -rw-r--r-- | doc/api/repositories.md | 88 |
1 files changed, 76 insertions, 12 deletions
diff --git a/doc/api/repositories.md b/doc/api/repositories.md index b0b3160e075..50dc0803646 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -285,8 +285,8 @@ Example response: Generate changelog data based on commits in a repository. -Given a version (using semantic versioning) and a range of commits, -GitLab generates a changelog for all commits that use a particular +Given a version (using [semantic versioning](https://semver.org/)) and a range +of commits, GitLab generates a changelog for all commits that use a particular [Git trailer](https://git-scm.com/docs/git-interpret-trailers). The output of this process is a new section in a changelog file in the Git @@ -303,7 +303,7 @@ Supported attributes: | :-------- | :------- | :--------- | :---------- | | `version` | string | yes | The version to generate the changelog for. The format must follow [semantic versioning](https://semver.org/). | | `from` | string | no | The start of the range of commits (as a SHA) to use for generating the changelog. This commit itself isn't included in the list. | -| `to` | string | yes | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. | +| `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the branch specified in the `branch` attribute. | | `date` | datetime | no | The date and time of the release, defaults to the current time. | | `branch` | string | no | The branch to commit the changelog changes to, defaults to the project's default branch. | | `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. | @@ -311,28 +311,72 @@ Supported attributes: | `message` | string | no | The commit message to produce when committing the changes, defaults to `Add changelog for version X` where X is the value of the `version` argument. | If the `from` attribute is unspecified, GitLab uses the Git tag of the last -version that came before the version specified in the `version` attribute. For -this to work, your project must create Git tags for versions using the -following format: +stable version that came before the version specified in the `version` +attribute. For this to work, your project must create Git tags for versions +using one of the following formats: -```plaintext -vX.Y.Z -``` +- `vX.Y.Z` +- `X.Y.Z` -Where `X.Y.Z` is a version that follows semantic versioning. For example, -consider a project with the following tags: +Where `X.Y.Z` is a version that follows [semantic +versioning](https://semver.org/). For example, consider a project with the +following tags: +- v1.0.0-pre1 - v1.0.0 - v1.1.0 - v2.0.0 If the `version` attribute is `2.1.0`, GitLab uses tag v2.0.0. And when the -version is `1.1.1`, or `1.2.0`, GitLab uses tag v1.1.0. +version is `1.1.1`, or `1.2.0`, GitLab uses tag v1.1.0. The tag `v1.0.0-pre1` is +never used, because pre-release tags are ignored. If `from` is unspecified and no tag to use is found, the API produces an error. To solve such an error, you must explicitly specify a value for the `from` attribute. +### Examples + +These examples use [cURL](https://curl.se/) to perform HTTP requests. +The example commands use these values: + +- **Project ID**: 42 +- **Location**: hosted on GitLab.com +- **Example API token**: `token` + +This command generates a changelog for version `1.0.0`. + +The commit range: + +- Starts with the tag of the last release. +- Ends with the last commit on the target branch. The default target branch is the project's default branch. + +If the last tag is `v0.9.0` and the default branch is `main`, the range of commits +included in this example is `v0.9.0..main`: + +```shell +curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0" "https://gitlab.com/api/v4/projects/42/repository/changelog" +``` + +To generate the data on a different branch, specify the `branch` parameter. This +command generates data from the `foo` branch: + +```shell +curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&branch=foo" "https://gitlab.com/api/v4/projects/42/repository/changelog" +``` + +To use a different trailer, use the `trailer` parameter: + +```shell +curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&trailer=Type" "https://gitlab.com/api/v4/projects/42/repository/changelog" +``` + +To store the results in a different file, use the `file` parameter: + +```shell +curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&file=NEWS" "https://gitlab.com/api/v4/projects/42/repository/changelog" +``` + ### How it works Changelogs are generated based on commit titles. Commits are only included if @@ -351,6 +395,26 @@ these as the changelog entries. You can enrich entries with additional data, such as a link to the merge request or details about the commit author. You can [customize the format of a changelog](#customize-the-changelog-output) section with a template. +### Reverted commits + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. + +When generating a changelog for a range, GitLab ignores commits both added and +reverted in that range. Revert commits themselves _are_ included if they use the +Git trailer used for generating changelogs. + +Imagine the following scenario: you have three commits: A, B, and C. To generate +changelogs, you use the default trailer `Changelog`. Both A and B use this +trailer. Commit C is a commit that reverts commit B. When generating a changelog +for this range, GitLab only includes commit A. + +Revert commits are detected by looking for commits where the message contains +the pattern `This reverts commit SHA`, where `SHA` is the SHA of the commit that +is reverted. + +If a revert commit includes the trailer used for generating changelogs +(`Changelog` in the above example), the revert commit itself _is_ included. + ### Customize the changelog output The output is customized using a YAML configuration file stored in your |