diff options
Diffstat (limited to 'doc/api/repositories.md')
| -rw-r--r-- | doc/api/repositories.md | 78 |
1 files changed, 70 insertions, 8 deletions
diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 50dc0803646..857cd3883c8 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -157,12 +157,13 @@ GET /projects/:id/repository/compare Supported attributes: -| Attribute | Type | Required | Description | -| :--------- | :------------- | :------- | :---------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `from` | string | yes | The commit SHA or branch name. | -| `to` | string | yes | The commit SHA or branch name. | -| `straight` | boolean | no | Comparison method, `true` for direct comparison between `from` and `to` (`from`..`to`), `false` to compare using merge base (`from`...`to`)'. Default is `false`. | +| Attribute | Type | Required | Description | +| :--------- | :------------- | :------- | :---------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `from` | string | yes | The commit SHA or branch name. | +| `to` | string | yes | The commit SHA or branch name. | +| `from_project_id` | integer | no | The ID to compare from | +| `straight` | boolean | no | Comparison method, `true` for direct comparison between `from` and `to` (`from`..`to`), `false` to compare using merge base (`from`...`to`)'. Default is `false`. | ```plaintext GET /projects/:id/repository/compare?from=master&to=feature @@ -312,8 +313,9 @@ Supported attributes: If the `from` attribute is unspecified, GitLab uses the Git tag of the last 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: +attribute. This requires that Git tag names follow a specific format, allowing +GitLab to extract a version from the tag names. By default, GitLab considers +tags using these formats: - `vX.Y.Z` - `X.Y.Z` @@ -395,6 +397,18 @@ 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. +Trailers can be manually added while editing a commit message. To include a commit +using the default trailer of `Changelog` and categorize it as a feature, the +trailer could be added to a commit message like so: + +```plaintext +<Commit message subject> + +<Commit message description> + +Changelog: feature +``` + ### Reverted commits > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. @@ -622,3 +636,51 @@ In an entry, the following variables are available (here `foo.bar` means that The `author` and `merge_request` objects might not be present if the data couldn't be determined. For example, when a commit is created without a corresponding merge request, no merge request is displayed. + +### Customize the tag format when extracting versions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56889) in GitLab 13.11. + +GitLab uses a regular expression (using the +[re2](https://github.com/google/re2/) engine and syntax) to extract a semantic +version from tag names. The default regular expression is: + +```plaintext +^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +``` + +This regular expression is based on the official +[semantic versioning](https://semver.org/) regular expression, and also includes +support for tag names that start with the letter `v`. + +If your project uses a different format for tags, you can specify a different +regular expression. The regular expression used _must_ produce the following +capture groups. If any of these capture groups are missing, the tag is ignored: + +- `major` +- `minor` +- `patch` + +The following capture groups are optional: + +- `pre`: If set, the tag is ignored. Ignoring `pre` tags ensures release candidate + tags and other pre-release tags are not considered when determining the range of + commits to generate a changelog for. +- `meta`: (Optional) Specifies build metadata. + +Using this information, GitLab builds a map of Git tags and their release +versions. It then determines what the latest tag is, based on the version +extracted from each tag. + +To specify a custom regular expression, use the `tag_regex` setting in your +changelog configuration YAML file. For example, this pattern matches tag names +such as `version-1.2.3` but not `version-1.2`. + +```yaml +--- +tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$' +``` + +To test if your regular expression is working, you can use websites such as +[regex101](https://regex101.com/). If the regular expression syntax is invalid, +an error is produced when generating a changelog. |