Document and lint that trailers are case-sensitive

The changelog API treats Git trailers case-sensitively in various
places. We also do the same in templates when we use trailers such as
`EE` and `MR`. Supporting all this in a case-insensitive manner is not
feasible at this time.

Instead, we now document that trailers must match exactly what value is
set in the `trailer` setting. In addition, Danger now produces an error
when a changelog trailer is present but uses the wrong casing (e.g.
`changelog` instead of `Changelog`).

Changelog: other

doc/api/repositories.md

@@ -311,6 +311,11 @@ Supported attributes:
 | `file`    | string   | no | The file to commit the changes to, defaults to `CHANGELOG.md`. |
 | `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. |
 
+WARNING:
+GitLab treats trailers case-sensitively. If you set the `trailer` field to
+`Example`, GitLab _won't_ include commits that use the trailer `example`, 
+`eXaMpLE`, or anything else that isn't _exactly_ `Example`.
+
 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. This requires that Git tag names follow a specific format, allowing

spec/tooling/danger/changelog_spec.rb

@@ -53,6 +53,12 @@ RSpec.describe Tooling::Danger::Changelog do
       it { is_expected.to have_attributes(errors: ["Commit #{commit.sha} uses an invalid changelog category: foo"]) }
     end
 
+    context 'when a commit uses the wrong casing for a trailer' do
+      let(:commit) { double('commit', message: "Hello world\n\nchangelog: foo", sha: "abc123") }
+
+      it { is_expected.to have_attributes(errors: ["The changelog trailer for commit #{commit.sha} must be `Changelog` (starting with a capital C), not `changelog`"]) }
+    end
+
     described_class::CATEGORIES.each do |category|
       context "when commit include a changelog trailer with category set to '#{category}'" do
         let(:commit) { double('commit', message: "Hello world\n\nChangelog: #{category}", sha: "abc123") }

tooling/danger/changelog.rb

@@ -13,7 +13,7 @@ module Tooling
         'meta'
       ].freeze
       NO_CHANGELOG_CATEGORIES = %i[docs none].freeze
-      CHANGELOG_TRAILER_REGEX = /^Changelog:\s*(?<category>.+)$/.freeze
+      CHANGELOG_TRAILER_REGEX = /^(?<name>Changelog):\s*(?<category>.+)$/i.freeze
       CHANGELOG_EE_TRAILER_REGEX = /^EE: true$/.freeze
       CHANGELOG_MODIFIED_URL_TEXT = "**CHANGELOG.md was edited.** Please remove the additions and follow the [changelog guidelines](https://docs.gitlab.com/ee/development/changelog.html).\n\n"
       CHANGELOG_MISSING_URL_TEXT = "**[CHANGELOG missing](https://docs.gitlab.com/ee/development/changelog.html)**:\n\n"
@@ -124,8 +124,13 @@ module Tooling
 
       def check_changelog_trailer(commit)
         trailer = commit.message.match(CHANGELOG_TRAILER_REGEX)
+        name = trailer[:name]
         category = trailer[:category]
 
+        unless name == 'Changelog'
+          return ChangelogCheckResult.error("The changelog trailer for commit #{commit.sha} must be `Changelog` (starting with a capital C), not `#{name}`")
+        end
+
         return ChangelogCheckResult.empty if CATEGORIES.include?(category)
 
         ChangelogCheckResult.error("Commit #{commit.sha} uses an invalid changelog category: #{category}")