After v1: About footer(s), git trailers and "multiple footers" #84

New Issue

GiteaMirror · 2026-02-17T11:43:59-06:00

GiteaMirror commented

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

Originally created by @tunnckoCore on GitHub (Oct 1, 2019).

The 3rd bullet in this list https://github.com/conventional-commits/conventionalcommits.org/pull/175#issuecomment-536398716 and the following comments after it.

I don't see any difference with git trailers, as @bcoe said in one of the comments. Each token/value pair is a trailer. What's the difference between "multiple footers" and "git trailers"? In abstract world, they are children of the footer.

                  CommitMessage
              /          |        \
           /             |           \
       Header           Body           Footer
     /   |   \           |               |  
type  scope  subject   paragraphs      trailers

* "subject" is officially called description

I see and always have seen it that way. Associations are a good thing. Such little details make difference. For the same reason I like more feat!(cli): foo instead of feat(cli)!: foo - it might be a bit easier to parse, it's more consitent when there is no scope (feat!: foo), and feels similar to function invocation of some languages. But that's a different topic.

Example commit message:

feat: meow meow, yawn

foo qux

bar
var

zero barry
deal

Reviewed-by: Zzz oops
Some-thing: Multiline important

trailer woohoo
meow meow

Why not?
yup!

Signed-off-by: Foo <bar@qux.com>

It could get parsed to the following object:

const commit = {
  header: {
    type: 'feat',
    scope: null,
    subject: 'meow meow, yawn'
  },
  body: 'foo qux\n\nbar\nvar\n\nzero barry\ndeal',
  footer: {
    trailers: [
      'Reviewed-by: Zzz oops',
      'Some-thing: Multiline important\n\ntrailer woohoo\nmeow meow\n\nWhy not?\nyup!',
      'Signed-off-by: Foo <bar@qux.com>'
    ],
    trailer: {
      'Reviewed-by': 'Zzz ooops',
      'Some-thing': 'Multiline important\n\ntrailer woohoo\nmeow meow\n\nWhy not?\nyup!',
      'Signed-off-by': 'Foo <bar@qux.com>',
    },
    raw: `Reviewed-by: Zzz oops
Some-thing: Multiline important

trailer woohoo
meow meow

Why not?
yup!

Signed-off-by: Foo <bar@qux.com>`,
  },
};

In the commit.footer object, some more advanced parser, could add more things such as mentions, references (based on trailers), and etc.

Originally created by @tunnckoCore on GitHub (Oct 1, 2019). The 3rd bullet in this list https://github.com/conventional-commits/conventionalcommits.org/pull/175#issuecomment-536398716 and the following comments after it. I don't see any difference with git trailers, as @bcoe said in one of the comments. Each token/value pair is a trailer. What's the difference between _"multiple footer**s**"_ and _"git trailer**s**"_? In abstract world, they are children of the footer. ``` CommitMessage / | \ / | \ Header Body Footer / | \ | | type scope subject paragraphs trailers ``` __*__ "subject" is officially called `description` I see and always have seen it that way. Associations are a good thing. Such little details make difference. For the same reason I like more `feat!(cli): foo` instead of `feat(cli)!: foo` - it might be a bit easier to parse, it's more consitent when there is no scope (`feat!: foo`), and feels similar to function invocation of some languages. But that's a different topic. --- Example commit message: ``` feat: meow meow, yawn foo qux bar var zero barry deal Reviewed-by: Zzz oops Some-thing: Multiline important trailer woohoo meow meow Why not? yup! Signed-off-by: Foo <bar@qux.com> ``` It could get parsed to the following object: ```js const commit = { header: { type: 'feat', scope: null, subject: 'meow meow, yawn' }, body: 'foo qux\n\nbar\nvar\n\nzero barry\ndeal', footer: { trailers: [ 'Reviewed-by: Zzz oops', 'Some-thing: Multiline important\n\ntrailer woohoo\nmeow meow\n\nWhy not?\nyup!', 'Signed-off-by: Foo <bar@qux.com>' ], trailer: { 'Reviewed-by': 'Zzz ooops', 'Some-thing': 'Multiline important\n\ntrailer woohoo\nmeow meow\n\nWhy not?\nyup!', 'Signed-off-by': 'Foo <bar@qux.com>', }, raw: `Reviewed-by: Zzz oops Some-thing: Multiline important trailer woohoo meow meow Why not? yup! Signed-off-by: Foo <bar@qux.com>`, }, }; ``` In the `commit.footer` object, some more advanced parser, could add more things such as `mentions`, references (based on trailers), and etc.

GiteaMirror commented

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

@JeanMertz commented on GitHub (Oct 1, 2019):

The two differences are:

Only :<space> and <space># are supported as separators
No spacing is required before a line belonging to a trailer that is not on the same line as the trailer key

That, and the fact that a footer doesn’t really exist in the sense that there can only be trailers in a footer, nothing else, is why I suggested the new wording.

Having said that, I don’t have too strong an opinion on this, using existing terminology is definitely a goal worth perusing, as long as it doesn’t cause too much confusion when the implementation itself deviates too much from what people expect to see when they read that terminology.

@JeanMertz commented on GitHub (Oct 1, 2019): The two differences are: * Only `:<space>` and `<space>#` are supported as separators * No spacing is required before a line belonging to a trailer that is not on the same line as the trailer key That, and the fact that a footer doesn’t really exist in the sense that there can only be trailers in a footer, nothing else, is why I suggested the new wording. Having said that, I don’t have too strong an opinion on this, using existing terminology is definitely a goal worth perusing, as long as it doesn’t cause too much confusion when the implementation itself deviates too much from what people expect to see when they read that terminology.

GiteaMirror commented

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

@bcoe commented on GitHub (Dec 24, 2020):

@JeanMertz @tunnckoCore we've been working to formalize the Conventional Commit grammar:

https://github.com/conventional-commits/parser#the-grammar

Perhaps we could move this conversation there? my hope is that we can formally define the grammar, with a reference implementation, and then map this back into v2.0.0 of the spec.

@bcoe commented on GitHub (Dec 24, 2020): @JeanMertz @tunnckoCore we've been working to formalize the Conventional Commit grammar: https://github.com/conventional-commits/parser#the-grammar Perhaps we could move this conversation there? my hope is that we can formally define the grammar, with a reference implementation, and then map this back into `v2.0.0` of the spec.

GiteaMirror commented

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

@abitrolly commented on GitHub (Jan 5, 2024):

I think human terminology should come before formal grammar. Specification should specify all details sufficiently for implementation. At the current state Conventional Commit specification doesn't exhibit this property.

As a result, tools like commitlint have to invent their own terminology. Here is how commitlint parses a message.

{
        type: null,
        scope: null,
        subject: null,
        merge: null,
        header: 'BREAKING CHANGE: this one',
        body: null,
        footer: null,
        notes: [],
        references: [],
        mentions: [],
        revert: null,
        raw: 'BREAKING CHANGE: this one'
      }

Here at least subject and header are critical for parsers, but are not defined in the spec. It is also not clear how breaking ! is named and where it belongs.

@abitrolly commented on GitHub (Jan 5, 2024): I think human terminology should come before formal grammar. Specification should specify all details sufficiently for implementation. At the current state Conventional Commit specification doesn't exhibit this property. As a result, tools like `commitlint` have to invent their own terminology. Here is how `commitlint` parses a message. ``` { type: null, scope: null, subject: null, merge: null, header: 'BREAKING CHANGE: this one', body: null, footer: null, notes: [], references: [], mentions: [], revert: null, raw: 'BREAKING CHANGE: this one' } ``` Here at least `subject` and `header` are critical for parsers, but are not defined in the spec. It is also not clear how breaking `!` is named and where it belongs.

GiteaMirror referenced this issue

2026-02-17 11:57:13 -06:00

[PR #85] [MERGED] feat: add imperative present tense requirement #279

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/conventionalcommits.org#84