Proposal to resolve body/footer ambiguity and support Git trailers #74

New Issue

GiteaMirror · 2026-02-17T11:42:36-06:00

GiteaMirror commented

2026-02-17 11:42:36 -06:00

Originally created by @JeanMertz on GitHub (Aug 17, 2019).

There is some ongoing confusion (and an ongoing discussion) about the spec when it comes to both the body of a commit message, and the footer.

Here is what the spec says:

A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.

A footer of one or more lines MAY be provided one blank line after the body. The footer MUST contain meta-information about the commit, e.g., related pull-requests, reviewers, breaking changes, with one piece of meta-information per-line.

Breaking changes MUST be indicated at the very beginning of the body section, or at the beginning of a line in the footer section. A breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon and a space.

A description MUST be provided after the BREAKING CHANGE:, describing what has changed about the API, e.g., BREAKING CHANGE: environment variables now take precedence over config files.

I've highlighted the parts that I wanted to discuss in this issue, and hopefully find consensus on.

Reading the current spec, there are a few problems that arise from it:

A body can only contain a single paragraph, anything more is considered to be part of the footer.
OR, a footer can only be one paragraph, the last one of the body (this is currently ambiguous)
BREAKING CHANGE can be in multiple positions, which can cause confusion.
It isn't mentioned if a breaking change description can be multiple paragraphs or not.
While a footer is described to contain metadata, there is no definition of the format of this metadata, making it impossible to automate metadata parsing (which is usually what metadata is good for).

Given the above points, I would like to propose to change the definition of the footer as follows:

A commit CAN contain a footer which MUST consist of one or more Git trailers.
The footer MUST start at the first occurrence of a blank line, followed by a Git trailer.
Each trailer MUST start on its own line, using the format <key><sep><value>.
The trailer <key> MUST be either BREAKING CHANGE¹ or be one or more words, grouped by hyphens (e.g. Co-Authored-By, fixes, etc.).
The trailer <sep> MUST be one of :<space> or <space>#, supporting both Co-Authored-By: Lisa Simpson <lisa@simpsons.com> and Fixes #999.
The trailer <value> MUST be present, and can contain any characters, either on a single line, split over multiple lines, or split over multiple paragraphs.

¹: This one is for backward compatibility with the current spec, or we could change it to be breaking-change (case insensitive).

I think the above description is preferred, because:

It removes any ambiguous language. (see https://github.com/conventional-commits/conventionalcommits.org/issues/170)
It makes it easy for parsers to know what's what (see https://github.com/rustic-games/conventional-commit/issues/9)
It ties in with the existing Git ecosystem and its support for trailers (see GitHub, GitLab and the Git wiki itself)
It makes it more natural to write commit messages with multi-paragraph bodies, and multi-paragraph trailers (specifically for the BREAKING CHANGE trailer, which sometimes requires more than a single line or paragraph to explain things)

I hope this all makes sense. I like using conventional commits, first for its informative and readable nature, second for the possibilities it brings in terms of automating auxiliary tasks related to Git projects. I think this proposal improves both use-cases.

Originally created by @JeanMertz on GitHub (Aug 17, 2019). There is some ongoing confusion (and an ongoing discussion) about the spec when it comes to both the _body_ of a commit message, and the _footer_. Here is what the spec says: > A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. **The body MUST begin one blank line after the description**. > **A footer of one or more lines MAY be provided one blank line after the body**. The footer **MUST contain meta-information about the commit**, e.g., related pull-requests, reviewers, breaking changes, with one piece of meta-information per-line. > **Breaking changes MUST be indicated at the very beginning of the body section, or at the beginning of a line in the footer section**. A breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon and a space. > **A description MUST be provided after the BREAKING CHANGE:**, describing what has changed about the API, e.g., BREAKING CHANGE: environment variables now take precedence over config files. I've highlighted the parts that I wanted to discuss in this issue, and hopefully find consensus on. Reading the current spec, there are a few problems that arise from it: * A body can only contain a single paragraph, anything more is considered to be part of the footer. * OR, a footer can only be one paragraph, the last one of the body (this is currently ambiguous) * `BREAKING CHANGE` can be in multiple positions, which can cause confusion. * It isn't mentioned if a breaking change description can be multiple paragraphs or not. * While a footer is described to contain metadata, there is no definition of the format of this metadata, making it impossible to automate metadata parsing (which is usually what metadata is good for). Given the above points, I would like to propose to change the definition of the footer as follows: * A commit CAN contain a footer which MUST consist of one or more [Git trailers](https://git-scm.com/docs/git-interpret-trailers). * The footer MUST start at the first occurrence of a blank line, followed by a Git trailer. * Each trailer MUST start on its own line, using the format `<key><sep><value>`. * The trailer `<key>` MUST be either `BREAKING CHANGE`<sup>1</sup> or be one or more words, grouped by hyphens (e.g. `Co-Authored-By`, `fixes`, etc.). * The trailer `<sep>` MUST be one of `:<space>` or `<space>#`, supporting both `Co-Authored-By: Lisa Simpson <lisa@simpsons.com>` _and_ `Fixes #999`. * The trailer `<value>` MUST be present, and can contain any characters, either on a single line, split over multiple lines, or split over multiple paragraphs. <sup>1</sup>: This one is for backward compatibility with the current spec, or we could change it to be `breaking-change` (case insensitive). I think the above description is preferred, because: 1. It removes any ambiguous language. (see https://github.com/conventional-commits/conventionalcommits.org/issues/170) 2. It makes it easy for parsers to know what's what (see https://github.com/rustic-games/conventional-commit/issues/9) 3. It ties in with the existing Git ecosystem and its support for trailers (see [GitHub](https://help.github.com/en/articles/creating-a-commit-with-multiple-authors), [GitLab](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17919) and the [Git wiki itself](https://git.wiki.kernel.org/index.php/CommitMessageConventions)) 4. It makes it more natural to write commit messages with multi-paragraph bodies, and multi-paragraph trailers (specifically for the BREAKING CHANGE trailer, which sometimes requires more than a single line or paragraph to explain things) I hope this all makes sense. I like using conventional commits, first for its informative and readable nature, second for the possibilities it brings in terms of automating auxiliary tasks related to Git projects. I think this proposal improves both use-cases.

GiteaMirror closed this issue

2026-02-17 11:42:36 -06:00

GiteaMirror commented

2026-02-17 11:42:38 -06:00

@JeanMertz commented on GitHub (Aug 19, 2019):

I made a proof of concept implementation of a parser for this change in the specification.

It supports a commit like this:

docs(example)!: add tested usage example

This example is tested using Rust's doctest capabilities. Having this
example helps people understand how to use the parser.

BREAKING CHANGE: Going from nothing to something, meaning anyone doing
nothing before suddenly has something to do. That sounds like a change
in your break.

Co-Authored-By: Lisa Simpson <lisa@simpsons.fam>
Closes #12

With BREAKING CHANGE, Co-Authored-By and Closes each their own trailer.

You can check out the example here:

https://docs.rs/conventional/0.4.1/conventional/#example

@JeanMertz commented on GitHub (Aug 19, 2019): I made a proof of concept implementation of a parser for this change in the specification. It supports a commit like this: ``` docs(example)!: add tested usage example This example is tested using Rust's doctest capabilities. Having this example helps people understand how to use the parser. BREAKING CHANGE: Going from nothing to something, meaning anyone doing nothing before suddenly has something to do. That sounds like a change in your break. Co-Authored-By: Lisa Simpson <lisa@simpsons.fam> Closes #12 ``` With `BREAKING CHANGE`, `Co-Authored-By` and `Closes` each their own trailer. You can check out the example here: https://docs.rs/conventional/0.4.1/conventional/#example

GiteaMirror commented

2026-02-17 11:42:39 -06:00

@bcoe commented on GitHub (Aug 20, 2019):

@JeanMertz this is great work, I was leaning towards git trailers as well (I didn't realize they had a name) I think this is a great way to eliminate ambiguity even though it adds a bit more complexity to the spec.

My only concern would be weird edge-cases where someone has a : after the first word in a paragraph, e.g., perhaps they're listing something: features: apple, banana, orange.

@bcoe commented on GitHub (Aug 20, 2019): @JeanMertz this is great work, I was leaning towards git trailers as well (I didn't realize they had a name) I think this is a great way to eliminate ambiguity even though it adds a bit more complexity to the spec. My only concern would be weird edge-cases where someone has a `:` after the first word in a paragraph, e.g., perhaps they're listing something: `features: apple, banana, orange`.

GiteaMirror commented

2026-02-17 11:42:40 -06:00

@blowmage commented on GitHub (Aug 20, 2019):

A body can only contain a single paragraph, anything more is considered to be part of the footer.

My concern here is that there are times when having more time to describe a change is incredibly useful. Now that the footer is defined as one or more trailers, why not parse out the trailers and leave what is left as the body? How would a footer use a non-trailer paragraph anyway?

@blowmage commented on GitHub (Aug 20, 2019): > A body can only contain a single paragraph, anything more is considered to be part of the footer. My concern here is that there are times when having more time to describe a change is incredibly useful. Now that the footer is defined as one or more trailers, why not parse out the trailers and leave what is left as the body? How would a footer use a non-trailer paragraph anyway?

GiteaMirror commented

2026-02-17 11:42:41 -06:00

@bcoe commented on GitHub (Aug 20, 2019):

@blowmage, @JeanMertz is listing:

A body can only contain a single paragraph, anything more is considered to be part of the footer.

as a shortcoming of the current specification, his proposal would allow for multi paragraph bodies, I think he basically describes exactly the format used by Node.js:

tools: make code cache and snapshot deterministic

Use a fixed random seed to ensure that the generated sources are
identical across runs.

The final node binary still reseeds itself on start-up so there should
be no security implications caused by predictable random numbers (e.g.,
`Math.random()`, ASLR, the hash seed, etc.)

Fixes: #29108

PR-URL: #29142
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

I think it's great that this addition to the conventional commit specification puts us in the position to support Node's commit format.

@bcoe commented on GitHub (Aug 20, 2019): @blowmage, @JeanMertz is listing: > A body can only contain a single paragraph, anything more is considered to be part of the footer. as a shortcoming of the current specification, his proposal would allow for multi paragraph bodies, I think he basically describes exactly the format used by Node.js: ``` tools: make code cache and snapshot deterministic Use a fixed random seed to ensure that the generated sources are identical across runs. The final node binary still reseeds itself on start-up so there should be no security implications caused by predictable random numbers (e.g., `Math.random()`, ASLR, the hash seed, etc.) Fixes: #29108 PR-URL: #29142 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> ``` I think it's great that this addition to the conventional commit specification puts us in the position to support Node's commit format.

GiteaMirror commented

2026-02-17 11:42:42 -06:00

@blowmage commented on GitHub (Aug 20, 2019):

as a shortcoming of the current specification, his proposal would allow for multi paragraph bodies

Ah, this is what tripped me up:

The footer MUST start at the first occurrence of a blank line, followed by a Git trailer.

As long as the footer doesn't start at the first blank line, and instead of a collection of all trailers, then I think it is a good change.

@blowmage commented on GitHub (Aug 20, 2019): > as a shortcoming of the current specification, his proposal would allow for multi paragraph bodies Ah, this is what tripped me up: > The footer MUST start at the first occurrence of a blank line, followed by a Git trailer. As long as the footer doesn't start at the first blank line, and instead of a collection of all trailers, then I think it is a good change.

GiteaMirror commented

2026-02-17 11:42:43 -06:00

@epage commented on GitHub (Aug 20, 2019):

The trailer MUST be either BREAKING CHANGE1 or be one or more words, grouped by hyphens (e.g. Co-Authored-By, fixes, etc.).

Sounds like this is more strict than git's definition of a trailer. Do we need to be so strict that BREAKING CHANGE is a special case?

@epage commented on GitHub (Aug 20, 2019): > The trailer <key> MUST be either BREAKING CHANGE1 or be one or more words, grouped by hyphens (e.g. Co-Authored-By, fixes, etc.). Sounds like this is more strict than git's definition of a trailer. Do we need to be so strict that `BREAKING CHANGE` is a special case?

GiteaMirror commented

2026-02-17 11:42:44 -06:00

@JeanMertz commented on GitHub (Aug 20, 2019):

Sounds like this is more strict than git's definition of a trailer. Do we need to be so strict that BREAKING CHANG

The reason for being a bit more strict is exactly to minimize the risk that @bcoe mentions in their comment:

My only concern would be weird edge-cases where someone has a : after the first word in a paragraph, e.g., perhaps they're listing something: features: apple, banana, orange.

By only supporting single words or words with hyphens or BREAKING CHANGE, followed by exactly “: “ or " #“, we minimize the number of false positives.

Also, looking at the Git wiki itself all of the trailers there would match the spec I defined. The contributions guide also talks about trailers only in their singular word or hyphenated words form.

Perhaps one of you can think of another way, or an additional way to make this less ambiguous?

@JeanMertz commented on GitHub (Aug 20, 2019): > Sounds like this is more strict than git's definition of a trailer. Do we need to be so strict that BREAKING CHANG The reason for being a bit more strict is exactly to minimize the risk that @bcoe mentions in their comment: > My only concern would be weird edge-cases where someone has a : after the first word in a paragraph, e.g., perhaps they're listing something: features: apple, banana, orange. By only supporting single words or words with hyphens or BREAKING CHANGE, followed by exactly “: “ or " #“, we minimize the number of false positives. Also, looking at the [Git wiki itself](https://git.wiki.kernel.org/index.php/CommitMessageConventions) all of the trailers there would match the spec I defined. The [contributions guide](https://github.com/git/git/blob/5fa0f5238b0cd46cfe7f6fa76c3f526ea98148d9/Documentation/SubmittingPatches#L353-L368) also talks about trailers only in their singular word or hyphenated words form. Perhaps one of you can think of another way, or an additional way to make this less ambiguous?

GiteaMirror commented

2026-02-17 11:42:46 -06:00

@JeanMertz commented on GitHub (Aug 20, 2019):

My thinking was that requiring a blank line directly followed by a valid trailer does limit the chances of false positives even further. But indeed, it does not completely eliminate it.

Perhaps we want to require two blank lines before the footer? That would make it very unlikely to trigger this accidentally, at the cost of a bit more complexity.

Still though, I feel like that goes against what most people already do naturally by adding “Fixes #12” at the bottom of a message, which my proposal would pick up, but requiring two blank lines would probably mean most people forget and their trailers aren’t registered because of the missing extra blank line.

Thinking about this, I feel like what I proposed strikes the best balance between simplicity and accuracy, but I welcome any addition that increases the accuracy without decreasing the simplicity.

@JeanMertz commented on GitHub (Aug 20, 2019): My thinking was that requiring a blank line directly followed by a valid trailer does limit the chances of false positives even further. But indeed, it does not completely eliminate it. Perhaps we want to require _two_ blank lines before the footer? That would make it very unlikely to trigger this accidentally, at the cost of a bit more complexity. Still though, I feel like that goes against what most people already do naturally by adding “Fixes #12” at the bottom of a message, which my proposal would pick up, but requiring two blank lines would probably mean most people forget and their trailers aren’t registered because of the missing extra blank line. Thinking about this, I feel like what I proposed strikes the best balance between simplicity and accuracy, but I welcome any addition that increases the accuracy without decreasing the simplicity.

GiteaMirror commented

2026-02-17 11:42:47 -06:00

@epage commented on GitHub (Aug 21, 2019):

So in my mind, the inputs to this discussion are

Git conventions (trailers)
Tooling relying on git conventions
Common platform conventions (github's handling of Fixes #10)

and I'm assuming defining traits we are aiming for include:

Helpful
Low overhead
Easy to use

So from that, some questions about the spec and example

Note: I try to use "trailer" when talking about git conventions and "footer" when talking about Conventional to try to keep the different definitions straight.

The trailer MUST be one of : or #, supporting both Co-Authored-By: Lisa Simpson lisa@simpsons.com and Fixes #999.

Will git tools that parse trailers misidentify sections with <space># as not trailer? Should we instead require footers to at minimum have : which github at least seems to support (Fixes: #10 works)

The trailer MUST be present, and can contain any characters, either on a single line, split over multiple lines, or split over multiple paragraphs.

This does not specify how multi-line footers are handled. Git says multi-line trailers have their 2+ lines indented. Do we need these to be recognized by git trailer tools? Should we conform to git's rules on multi-line trailers?

I am confused at the need for multi-paragraph footers. The intention of trailers is metadata and I assume the intention for footers is the same. What is the use case for multiple paragraphs? Can we simplify things by removing this? If we use git's rules for multi-line, can we even support this?

docs(example)!: add tested usage example

This example is tested using Rust's doctest capabilities. Having this
example helps people understand how to use the parser.

BREAKING CHANGE: Going from nothing to something, meaning anyone doing
nothing before suddenly has something to do. That sounds like a change
in your break.

Co-Authored-By: Lisa Simpson <lisa@simpsons.fam>
Closes #12

For this example, I'm assuming BREAKING CHANGE is a footer? I'm assuming this works because you can have multiple footer sections? I didn't see this in the spec, is it just implied? Should we be more explicit?

Do git trailer tools understand multiple trailer sections? Do we care?

@epage commented on GitHub (Aug 21, 2019): So in my mind, the inputs to this discussion are - Git conventions (trailers) - Tooling relying on git conventions - Common platform conventions (github's handling of `Fixes #10`) and I'm assuming defining traits we are aiming for include: - Helpful - Low overhead - Easy to use So from that, some questions about the spec and example **Note**: I try to use "trailer" when talking about git conventions and "footer" when talking about Conventional to try to keep the different definitions straight. > The trailer <sep> MUST be one of :<space> or <space>#, supporting both Co-Authored-By: Lisa Simpson <lisa@simpsons.com> and Fixes #999. Will git tools that parse trailers misidentify sections with `<space>#` as not trailer? Should we instead require footers to at minimum have `: ` which github at least seems to support (`Fixes: #10` works) > The trailer <value> MUST be present, and can contain any characters, either on a single line, split over multiple lines, or split over multiple paragraphs. This does not specify how multi-line footers are handled. Git says multi-line trailers have their 2+ lines indented. Do we need these to be recognized by git trailer tools? Should we conform to git's rules on multi-line trailers? I am confused at the need for multi-paragraph footers. The intention of trailers is metadata and I assume the intention for footers is the same. What is the use case for multiple paragraphs? Can we simplify things by removing this? If we use git's rules for multi-line, can we even support this? Related: ``` docs(example)!: add tested usage example This example is tested using Rust's doctest capabilities. Having this example helps people understand how to use the parser. BREAKING CHANGE: Going from nothing to something, meaning anyone doing nothing before suddenly has something to do. That sounds like a change in your break. Co-Authored-By: Lisa Simpson <lisa@simpsons.fam> Closes #12 ``` For this example, I'm assuming `BREAKING CHANGE` is a footer? I'm assuming this works because you can have multiple footer sections? I didn't see this in the spec, is it just implied? Should we be more explicit? Do git trailer tools understand multiple trailer sections? Do we care?

GiteaMirror commented

2026-02-17 11:42:48 -06:00

@epage commented on GitHub (Aug 21, 2019):

By only supporting single words or words with hyphens or BREAKING CHANGE, followed by exactly “: “ or " #“, we minimize the number of false positives.

If the goal is to be as restrictive as possible while still being compatible with most people, I think I prefer being a bit more consistent and adopting your recommendation for Breaking-Change instead.

Speaking of, case sensitivity, before we didn't have a way to identify keys from values. Currently, the type and scope are case insensitive. Are footer keys? Do we need to include that?

@epage commented on GitHub (Aug 21, 2019): > By only supporting single words or words with hyphens or BREAKING CHANGE, followed by exactly “: “ or " #“, we minimize the number of false positives. If the goal is to be as restrictive as possible while still being compatible with most people, I think I prefer being a bit more consistent and adopting your recommendation for `Breaking-Change` instead. Speaking of, case sensitivity, before we didn't have a way to identify keys from values. Currently, the `type` and `scope` are case insensitive. Are footer keys? Do we need to include that?

GiteaMirror commented

2026-02-17 11:42:49 -06:00

@tunnckoCore commented on GitHub (Aug 21, 2019):

Hm. Really like that one. But the text of the spec may be a bit more simpler and not confusing for beginners. As @blowmage said: parse out the trailers and leave what is left as the body. Everything before the first trailer is considered body, everything after (including the first trailer) is considered footer. So, we never will have footer if there are no trailers. Which is a pretty clean thing.

@JeanMertz: at the bottom of a message, which my proposal would pick up, but requiring two blank lines would probably mean most people forget and their trailers aren’t registered because of the missing extra blank line.

This easily can be handled as "most common case". The following still will be valid:

docs(www): update website foo section

fixes: #12

Otherwise, require 2 blank lines

docs(www): update website foo section

This example is tested using Rust's doctest capabilities. Having this
example helps people understand how to use the parser.

The final node binary still reseeds itself on start-up so there should
be no security implications caused by predictable random numbers (e.g.,
`Math.random()`, ASLR, the hash seed, etc.)


Fixes: #12
Signed-off-by: Charlike Mike Reagent <opensource@tunnckocore.com>

Btw, the first line of commit message I like to call "header" and that's why in parse-commit-message above in future can return something like this

{
  header: {
    type: 'docs',
    scope: 'www',
    subject: 'update website foo section'
  },
  body: "This example is tested using Rust's doctest capabilities. Having this example helps people understand how to use the parser.\n\nThe final node binary still reseeds itself on start-up so there should
be no security implications caused by predictable random numbers (e.g.,
`Math.random()`, ASLR, the hash seed, etc.)"
  footer: {
    text: 'Fixes: #12\nSigned-off-by: Charlike Mike Reagent <opensource@tunnckocore.com>'
    trailers: [...]
  }
}

Where the footer.trailers can be array or object, still not sure, but would be cool to have all the trailers parsed too. Anyway, that's for the future.

Overall, I like the idea and also with the ! for breaking change, the things get even prettier.

edit: Kind of off-topic a bit. But, is it better the ! to be required to always be after the type, no matter there is scope or not.

So

feat!(lang): add polish language

and

fix!: correct minor typos in code

So... <type>[optional breaking change][optional scope]: <description>

I missed the discussion there and initially, I was against it but... I think this way it looks better and probably a bit easier to parse. Also, looks like Rust function call (and other languages?).

@tunnckoCore commented on GitHub (Aug 21, 2019): Hm. Really like that one. But the text of the spec may be a bit more simpler and not confusing for beginners. As @blowmage said: parse out the trailers and leave what is left as the body. Everything before the first trailer is considered `body`, everything after (including the first trailer) is considered `footer`. So, we never will have footer if there are no trailers. Which is a pretty clean thing. > @JeanMertz: at the bottom of a message, which my proposal would pick up, but requiring two blank lines would probably mean most people forget and their trailers aren’t registered because of the missing extra blank line. This easily can be handled as "most common case". The following still will be valid: ``` docs(www): update website foo section fixes: #12 ``` Otherwise, require 2 blank lines ``` docs(www): update website foo section This example is tested using Rust's doctest capabilities. Having this example helps people understand how to use the parser. The final node binary still reseeds itself on start-up so there should be no security implications caused by predictable random numbers (e.g., `Math.random()`, ASLR, the hash seed, etc.) Fixes: #12 Signed-off-by: Charlike Mike Reagent <opensource@tunnckocore.com> ``` Btw, the first line of commit message I like to call "header" and that's why in `parse-commit-message` above in future can return something like this ``` { header: { type: 'docs', scope: 'www', subject: 'update website foo section' }, body: "This example is tested using Rust's doctest capabilities. Having this example helps people understand how to use the parser.\n\nThe final node binary still reseeds itself on start-up so there should be no security implications caused by predictable random numbers (e.g., `Math.random()`, ASLR, the hash seed, etc.)" footer: { text: 'Fixes: #12\nSigned-off-by: Charlike Mike Reagent <opensource@tunnckocore.com>' trailers: [...] } } ``` Where the `footer.trailers` can be array or object, still not sure, but would be cool to have all the trailers parsed too. Anyway, that's for the future. Overall, I like the idea and also with the `!` for breaking change, the things get even prettier. --- edit: Kind of off-topic a bit. But, is it better the `!` to be required to always be after the type, no matter there is scope or not. So ``` feat!(lang): add polish language ``` and ``` fix!: correct minor typos in code ``` So... `<type>[optional breaking change][optional scope]: <description>` I missed the discussion there and initially, I was against it but... I think this way it looks better and probably a bit easier to parse. Also, looks like Rust function call (and other languages?).

GiteaMirror commented

2026-02-17 11:42:50 -06:00

@JeanMertz commented on GitHub (Aug 22, 2019):

Will git tools that parse trailers misidentify sections with <space># as not trailer?

Git supports configuring the separator. I went with :<space> and <space># because it covers most common use-cases without over-generalising things.

Should we instead require footers to at minimum have : which github at least seems to support (Fixes: #10 works)

I don't think we should, because brain muscle has thought people to use closes #x in their commit messages, and this fits with the fact that Git actually supports custom trailer separators.

This does not specify how multi-line footers are handled. Git says multi-line trailers have their 2+ lines indented. Do we need these to be recognized by git trailer tools? Should we conform to git's rules on multi-line trailers?

This is a valid point that I left out of my reasoning. Basically, I wanted to keep things a bit simpler. Git is a bit vague on their formatting, but from what I can tell, if you start the next line of a trailer with at least one space, it's part of the trailer.

Since that again is not how most people write their commit messages, I figured it would be best to also support multi-line trailers without the preceding whitespace. It basically trades correctness for convenience, which I thought was the correct trade-off in this case.

I am confused at the need for multi-paragraph footers. The intention of trailers is metadata and I assume the intention for footers is the same. What is the use case for multiple paragraphs? Can we simplify things by removing this?

I think I've explained this before, but breaking changes very often require more than one paragraph. For example, I like to include specific code examples in my breaking change messages to let people know what they need to update in their code to make it work again. I do this by using markdown code block fences which requires separate paragraphs.

For me this is a big deal, without multi-paragraph trailer support, the support for properly parsing breaking changes falls flat.

For this example, I'm assuming BREAKING CHANGE is a footer? I'm assuming this works because you can have multiple footer sections? I didn't see this in the spec, is it just implied? Should we be more explicit?

I'm not quite sure what you mean. In the spec I wrote a footer isn't really a thing (we could even omit it from the spec wording). Whenever the first trailer is detected, anything below that is either 1) a paragraph part of the "active trailer" (the last trailer key+sep found), or the start of a new trailer.

So in the example, BREAKING CHANGE is simply the first trailer the parser encounters, and any text/whitespace/... after that is part of that first trailer. until it finds the start of a second trailer.

If the goal is to be as restrictive as possible while still being compatible with most people, I think I prefer being a bit more consistent and adopting your recommendation for Breaking-Change instead.

I don't have a strong opinion on that, I'm fine either way, but figured people are already using BREAKING CHANGE, so there's little harm in keep support for that.

Speaking of, case sensitivity, before we didn't have a way to identify keys from values. Currently, the type and scope are case insensitive. Are footer keys? Do we need to include that?

We probably should mention it 👍 and they shouldn't be case sensitive, it's just a convention used by people using git trailers, so we could at least add it to the FAQ.

Everything before the first trailer is considered body, everything after (including the first trailer) is considered footer. So, we never will have footer if there are no trailers. Which is a pretty clean thing.

This is indeed exactly how the parser I wrote currently does this, and is how I intended to write the spec, but maybe my wording isn't clear enough?

The following still will be valid

Correct, and the parser currently takes that into account. So basically, after the header, there should be blank line, then EITHER the body, or the first trailer, if a body is present, then after that should be another blank line before the first trailer starts.

I'll take some time this weekend to create a PR with my proposal and the suggestions made in this issue, so we have something concrete to further discuss, and can use inline comments to the relevant sections, instead of having to quote everyone all the time while replying 😅.

@JeanMertz commented on GitHub (Aug 22, 2019): > Will git tools that parse trailers misidentify sections with `<space>#` as not trailer? Git [supports configuring the separator](https://git-scm.com/docs/git-interpret-trailers#Documentation/git-interpret-trailers.txt-trailerseparators). I went with `:<space>` and `<space>#` because it covers most common use-cases without over-generalising things. > Should we instead require footers to at minimum have `: ` which github at least seems to support (`Fixes: #10` works) I don't think we should, because brain muscle has thought people to use `closes #x` in their commit messages, and this fits with the fact that Git actually supports custom trailer separators. > This does not specify how multi-line footers are handled. Git says multi-line trailers have their 2+ lines indented. Do we need these to be recognized by git trailer tools? Should we conform to git's rules on multi-line trailers? This is a valid point that I left out of my reasoning. Basically, I wanted to keep things a bit simpler. Git is a bit vague on their formatting, but from what I can tell, if you start the next line of a trailer with _at least_ one space, it's part of the trailer. Since that again is not how most people write their commit messages, I figured it would be best to also support multi-line trailers without the preceding whitespace. It basically trades correctness for convenience, which I thought was the correct trade-off in this case. > I am confused at the need for multi-paragraph footers. The intention of trailers is metadata and I assume the intention for footers is the same. What is the use case for multiple paragraphs? Can we simplify things by removing this? I think I've explained this before, but breaking changes _very often_ require more than one paragraph. For example, I like to include specific code examples in my breaking change messages to let people know what they need to update in their code to make it work again. I do this by using markdown code block fences which requires separate paragraphs. For me this is a big deal, without multi-paragraph trailer support, the support for properly parsing breaking changes falls flat. > For this example, I'm assuming `BREAKING CHANGE` is a footer? I'm assuming this works because you can have multiple footer sections? I didn't see this in the spec, is it just implied? Should we be more explicit? I'm not quite sure what you mean. In the spec I wrote a _footer_ isn't really a thing (we could even omit it from the spec wording). Whenever the first _trailer_ is detected, anything below that is either 1) a paragraph part of the "active trailer" (the last trailer key+sep found), or the start of a new trailer. So in the example, `BREAKING CHANGE` is simply the first trailer the parser encounters, and any text/whitespace/... after that is part of that first trailer. until it finds the start of a second trailer. > If the goal is to be as restrictive as possible while still being compatible with most people, I think I prefer being a bit more consistent and adopting your recommendation for `Breaking-Change` instead. I don't have a strong opinion on that, I'm fine either way, but figured people are already using `BREAKING CHANGE`, so there's little harm in keep support for that. > Speaking of, case sensitivity, before we didn't have a way to identify keys from values. Currently, the `type` and `scope` are case insensitive. Are footer keys? Do we need to include that? We probably should mention it 👍 and they shouldn't be case sensitive, it's just a convention used by people using git trailers, so we could at least add it to the FAQ. --- > Everything before the first trailer is considered `body`, everything after (including the first trailer) is considered `footer`. So, we never will have footer if there are no trailers. Which is a pretty clean thing. This is indeed exactly how the parser I wrote currently does this, and is how I intended to write the spec, but maybe my wording isn't clear enough? > The following still will be valid Correct, and the parser currently takes that into account. So basically, after the header, there should be blank line, then EITHER the body, or the first trailer, if a body is present, then after that should be another blank line before the first trailer starts. --- I'll take some time this weekend to create a PR with my proposal and the suggestions made in this issue, so we have something concrete to further discuss, and can use inline comments to the relevant sections, instead of having to quote everyone all the time while replying 😅.

GiteaMirror commented

2026-02-17 11:42:51 -06:00

@epage commented on GitHub (Aug 23, 2019):

Since that again is not how most people write their commit messages, I figured it would be best to also support multi-line trailers without the preceding whitespace. It basically trades correctness for convenience, which I thought was the correct trade-off in this case.

I'm all for people writing commit bodies as naturally as possible. The part I'd question is how much of a habit people have formed for footers/trailers.

I think I've explained this before, but breaking changes very often require more than one paragraph. For example, I like to include specific code examples in my breaking change messages to let people know what they need to update in their code to make it work again. I do this by using markdown code block fences which requires separate paragraphs.

Does this belong in the trailer though or should this be in the body? In my mind, long descriptions belong in the body while trailers should be succinct metadata.

@epage commented on GitHub (Aug 23, 2019): > Since that again is not how most people write their commit messages, I figured it would be best to also support multi-line trailers without the preceding whitespace. It basically trades correctness for convenience, which I thought was the correct trade-off in this case. I'm all for people writing commit bodies as naturally as possible. The part I'd question is how much of a habit people have formed for footers/trailers. > I think I've explained this before, but breaking changes very often require more than one paragraph. For example, I like to include specific code examples in my breaking change messages to let people know what they need to update in their code to make it work again. I do this by using markdown code block fences which requires separate paragraphs. Does this belong in the trailer though or should this be in the body? In my mind, long descriptions belong in the body while trailers should be succinct metadata.

GiteaMirror commented

2026-02-17 11:42:52 -06:00

@bcoe commented on GitHub (Aug 26, 2019):

@tommywo convince you to chime in on this topic, promises to have a real influence on the future of the conventional commit parsers we've been working on.

@bcoe commented on GitHub (Aug 26, 2019): @tommywo convince you to chime in on this topic, promises to have a real influence on the future of the conventional commit parsers we've been working on.

GiteaMirror commented

2026-02-17 11:42:53 -06:00

@bcoe commented on GitHub (Sep 7, 2019):

addressed in https://github.com/conventional-commits/conventionalcommits.org/pull/185

@bcoe commented on GitHub (Sep 7, 2019): addressed in https://github.com/conventional-commits/conventionalcommits.org/pull/185

GiteaMirror commented

2026-02-17 11:42:54 -06:00

@LemmingAvalanche commented on GitHub (Mar 20, 2024):

The current specification seems pretty compatible with trailers if you use the correct optional features. So here’s what I would have done (years back).

Use trailers syntax with mandatory :<space> separator since that comes out of the box without configuration
Now whatever implementation can be validated with git interpret-trailers
Demand (or recommend) BREAKING-CHANGE variant (hyphen) if used in trailers section because BREAKING CHANGE (space) forces git intepret-trailers to ignore the rest of the trailers (it’s no longer a trailers block)

Allow multi-paragraph BREAKING-CHANGE (since that is not supported by trailers) with the special rule that . on an empty line is the same as a blank line (paragraph break)

feat!: foo

Robot: 4554
BREAKING-CHANGE: Fusce sagittis, libero non molestie mollis, magna orci ultrices
  dolor, at vulputate neque nulla lacinia eros.
  .
  Nullam eu ante vel est convallis dignissim.  Fusce suscipit, wisi nec
  facilisis facilisis, est dui fermentum leo, quis tempor ligula erat
  quis odio.  Nunc porta vulputate tellus.  Nunc rutrum turpis sed pede.
  Sed bibendum.  Aliquam posuere.  Nunc aliquet, augue nec adipiscing
  interdum, lacus tellus malesuada massa, quis varius mi purus non odio.
  Pellentesque condimentum, magna ut suscipit hendrerit, ipsum augue
  ornare nulla, non luctus diam neque sit amet urna.  Curabitur
  vulputate vestibulum lorem.  Fusce sagittis, libero non molestie
  mollis, magna orci ultrices dolor, at vulputate neque nulla lacinia
  eros.  Sed id ligula quis est convallis tempor.  Curabitur lacinia
  pulvinar nibh.  Nam a sapien.

This looks compatible with the current specification.

@LemmingAvalanche commented on GitHub (Mar 20, 2024): The current specification seems pretty compatible with _trailers_ if you use the correct optional features. So here’s what I would have done (years back). 1. Use trailers syntax with mandatory `:<space>` separator since that comes out of the box without configuration 2. Now whatever implementation can be validated with `git interpret-trailers` 3. Demand (or recommend) `BREAKING-CHANGE` variant (hyphen) if used in trailers section because `BREAKING CHANGE` (space) forces `git intepret-trailers` to ignore the rest of the trailers (it’s no longer a trailers block) 4. Allow multi-paragraph `BREAKING-CHANGE` (since that is not supported by _trailers_) with the special rule that `.` on an empty line is the same as a blank line (paragraph break) ``` feat!: foo Robot: 4554 BREAKING-CHANGE: Fusce sagittis, libero non molestie mollis, magna orci ultrices dolor, at vulputate neque nulla lacinia eros. . Nullam eu ante vel est convallis dignissim. Fusce suscipit, wisi nec facilisis facilisis, est dui fermentum leo, quis tempor ligula erat quis odio. Nunc porta vulputate tellus. Nunc rutrum turpis sed pede. Sed bibendum. Aliquam posuere. Nunc aliquet, augue nec adipiscing interdum, lacus tellus malesuada massa, quis varius mi purus non odio. Pellentesque condimentum, magna ut suscipit hendrerit, ipsum augue ornare nulla, non luctus diam neque sit amet urna. Curabitur vulputate vestibulum lorem. Fusce sagittis, libero non molestie mollis, magna orci ultrices dolor, at vulputate neque nulla lacinia eros. Sed id ligula quis est convallis tempor. Curabitur lacinia pulvinar nibh. Nam a sapien. ``` This looks compatible with the current specification.

GiteaMirror commented

2026-02-17 11:42:54 -06:00

@LemmingAvalanche commented on GitHub (Dec 11, 2024):

@JeanMertz Perhaps we want to require two blank lines before the footer? That would make it very unlikely to trigger this accidentally, at the cost of a bit more complexity.

This wouldn’t have worked. git(1) normalizes commit messages by default (default commit.cleanup config) by (among other things) collapsing runs of blank lines to single blank lines.

See git-stripspace(1).

@LemmingAvalanche commented on GitHub (Dec 11, 2024): > @JeanMertz Perhaps we want to require two blank lines before the footer? That would make it very unlikely to trigger this accidentally, at the cost of a bit more complexity. This wouldn’t have worked. git(1) normalizes commit messages by default (default `commit.cleanup` config) by (among other things) collapsing runs of blank lines to single blank lines. See git-stripspace(1).

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/conventionalcommits.org#74