Merge branch 'ignore-unstable-changelog-tags' into 'master'

Ignore prerelease tags when generating changelogs, and add some changelog API examples

See merge request gitlab-org/gitlab!55065

app/finders/repositories/previous_tag_finder.rb

@@ -37,6 +37,11 @@ module Repositories
 
         next unless matches
 
+        # When using this class for generating changelog data for a range of
+        # commits, we want to compare against the tag of the last _stable_
+        # release; not some random RC that came after that.
+        next if matches[:prerelease]
+
         version = matches[:version]
         tags[version] = tag
         versions << version

changelogs/unreleased/ignore-unstable-changelog-tags.yml

+---
+title: Ignore prerelease tags when generating changelogs
+merge_request: 55065
+author:
+type: changed

doc/api/repositories.md

@@ -311,9 +311,9 @@ 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 one of the
-following formats:
+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:
 
 - `vX.Y.Z`
 - `X.Y.Z`
@@ -322,17 +322,58 @@ 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
+
+For these examples we use the project ID 42, and assume the project is hosted on
+GitLab.com. The example API token we use is `token`. We use
+[curl](https://curl.se/) to perform the HTTP requests.
+
+Let's start with a basic example:
+
+```shell
+curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0" "https://gitlab.com/api/v4/projects/42/repository/changelog"
+```
+
+This generates a changelog for version `1.0.0`. The start of the range of
+commits to include is the tag of the last release. The end of the range is the
+last commit on the target branch, which defaults to the project's default
+branch. So if the last tag is `v0.9.0`, and the default branch is `main`, this
+means the range of commits is `v0.9.0..main`.
+
+If you want to generate the data on a different branch, you can do so as
+follows:
+
+```shell
+curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&branch=foo" "https://gitlab.com/api/v4/projects/42/repository/changelog"
+```
+
+This generates the data on the `foo` branch.
+
+A different trailer to use is specified as follows:
+
+```shell
+curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&trailer=Type" "https://gitlab.com/api/v4/projects/42/repository/changelog"
+```
+
+Or perhaps you want to store the results in a different file:
+
+```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

spec/finders/repositories/previous_tag_finder_spec.rb

@@ -13,18 +13,19 @@ RSpec.describe Repositories::PreviousTagFinder do
         tag2 = double(:tag2, name: 'v1.1.0')
         tag3 = double(:tag3, name: 'v2.0.0')
         tag4 = double(:tag4, name: '0.9.0')
-        tag5 = double(:tag4, name: 'v0.8.0-pre1')
+        tag5 = double(:tag5, name: 'v0.8.0-pre1')
+        tag6 = double(:tag6, name: 'v0.7.0')
 
         allow(project.repository)
           .to receive(:tags)
-          .and_return([tag1, tag3, tag2, tag4, tag5])
+          .and_return([tag1, tag3, tag2, tag4, tag5, tag6])
 
         expect(finder.execute('2.1.0')).to eq(tag3)
         expect(finder.execute('2.0.0')).to eq(tag2)
         expect(finder.execute('1.5.0')).to eq(tag2)
         expect(finder.execute('1.0.1')).to eq(tag1)
         expect(finder.execute('1.0.0')).to eq(tag4)
-        expect(finder.execute('0.9.0')).to eq(tag5)
+        expect(finder.execute('0.9.0')).to eq(tag6)
       end
     end