Improve example "Commit message with multi-paragraph body and multiple footers" #122

New Issue

GiteaMirror · 2026-02-17T11:48:05-06:00

GiteaMirror commented

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

Originally created by @shaman-apprentice on GitHub (Mar 8, 2021).

As a developer I want commit messages to be succinct and readable. As a user of Conventional Commits I want the examples to be clear and inspiring to use the guidelines.

I had to read the given example below Commit message with multi-paragraph body and multiple footers multiple times to understand, that both bodies are one connected sentence.

fix: correct minor typos in code

see the issue for details

on typos fixed.

Reviewed-by: Z
Refs #133

I think it is more intuitive to write the two bodies as one, which is more readable than splitting one sentence over 3 lines.

What do you think about updating the example, so that each body is a sentence with a separate meaningful concern by itself? Maybe:

refactor: implement observer pattern

this makes it easy to add new observers in the future.

see [architecture](link-to-architecture-documentation) for further details.

Reviewed-by: Z
Refs #133

Originally created by @shaman-apprentice on GitHub (Mar 8, 2021). As a developer I want commit messages to be succinct and readable. As a user of Conventional Commits I want the examples to be clear and inspiring to use the guidelines. I had to read the given example below [Commit message with multi-paragraph body and multiple footers](https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with-multi-paragraph-body-and-multiple-footers) multiple times to understand, that both bodies are one connected sentence. > fix: correct minor typos in code > > see the issue for details > > on typos fixed. > > Reviewed-by: Z > Refs #<span/>133 I think it is more intuitive to write the two bodies as one, which is more readable than splitting one sentence over 3 lines. What do you think about updating the example, so that each body is a sentence with a separate meaningful concern by itself? Maybe: > refactor: implement observer pattern > > this makes it easy to add new observers in the future. > > see \[architecture](link-to-architecture-documentation) for further details. > > Reviewed-by: Z > Refs #<span/>133

GiteaMirror closed this issue

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

GiteaMirror commented

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

@derekmurawsky commented on GitHub (Sep 23, 2021):

I second this, and would take it a step further by possibly incorporating some of the ideas around what makes a good commit message. I have used this blog post by Chis Beams as the basis of my commit messages for a while now and have found it to be an excellent pattern. The key aspects are:

Separate subject from body with a blank line
Limit the subject line to 50 characters
Capitalize the subject line
Do not end the subject line with a period
Use the imperative mood in the subject line
Wrap the body at 72 characters
Use the body to explain what and why vs. how

That last point, number 7, is huge to me. If nothing else is incorporated to conventional commits, I would encourage you consider that. Issues trackers can change over time. Commit histories are, generally, forever.

@derekmurawsky commented on GitHub (Sep 23, 2021): I second this, and would take it a step further by possibly incorporating some of the ideas around what makes a good commit message. I have used [this blog post by Chis Beams](https://chris.beams.io/posts/git-commit/) as the basis of my commit messages for a while now and have found it to be an excellent pattern. The key aspects are: 1. Separate subject from body with a blank line 2. Limit the subject line to 50 characters 3. Capitalize the subject line 4. Do not end the subject line with a period 5. Use the imperative mood in the subject line 6. Wrap the body at 72 characters 7. **Use the body to explain what and why vs. how** That last point, number 7, is huge to me. If nothing else is incorporated to conventional commits, I would encourage you consider that. Issues trackers can change over time. Commit histories are, generally, forever.

GiteaMirror commented

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

@damianopetrungaro commented on GitHub (Sep 28, 2021):

@shaman-apprentice I agree with you, do you wanna open a PR for that?

@damianopetrungaro commented on GitHub (Sep 28, 2021): @shaman-apprentice I agree with you, do you wanna open a PR for that?

GiteaMirror commented

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

@damianopetrungaro commented on GitHub (Sep 28, 2021):

@derekmurawsky At the moment the convention is totally open to provide support to most of the tooling around, I agree with you that those are really good rules for writing a commit message, but still, I'd consider those not mandatory for the current state of the specification.

@damianopetrungaro commented on GitHub (Sep 28, 2021): @derekmurawsky At the moment the convention is totally open to provide support to most of the tooling around, I agree with you that those are really good rules for writing a commit message, but still, I'd consider those not mandatory for the current state of the specification.

GiteaMirror commented

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

@derekmurawsky commented on GitHub (Sep 30, 2021):

@derekmurawsky At the moment the convention is totally open to provide support to most of the tooling around, I agree with you that those are really good rules for writing a commit message, but still, I'd consider those not mandatory for the current state of the specification.

Thanks for the reply!

To clarify, I meant that we should either reference the other work or improve the example. I did not mean it should be included in the standard itself.

And I don't mean to speak for @shaman-apprentice - But I believe they were referring to the examples as well.

@derekmurawsky commented on GitHub (Sep 30, 2021): > @derekmurawsky At the moment the convention is totally open to provide support to most of the tooling around, I agree with you that those are really good rules for writing a commit message, but still, I'd consider those not mandatory for the current state of the specification. Thanks for the reply! To clarify, I meant that we should either reference the other work or improve **_the example_**. I did _not_ mean it should be included in the standard itself. And I don't mean to speak for @shaman-apprentice - But I believe they were referring to the examples as well.

GiteaMirror commented

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

@damianopetrungaro commented on GitHub (Sep 30, 2021):

Then it’s totally ok! If you want you can open a PR and fix that! I’d love
it :)

On Thu, 30 Sep 2021 at 16:06, Derek Murawsky @.***>
wrote:

@derekmurawsky https://github.com/derekmurawsky At the moment the
convention is totally open to provide support to most of the tooling
around, I agree with you that those are really good rules for writing a
commit message, but still, I'd consider those not mandatory for the current
state of the specification.

Thanks for the reply!

To clarify, I meant that we should either reference the other work or
improve the example. I did not mean it should be included in the
standard itself.

And I don't mean to speak for @shaman-apprentice
https://github.com/shaman-apprentice - But I believe they were
referring to the examples as well.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/conventional-commits/conventionalcommits.org/issues/348#issuecomment-931354904,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/ACEJFZ2LO543WKHVNCE3SMLUERVE3ANCNFSM4YZQXPIQ
.

@damianopetrungaro commented on GitHub (Sep 30, 2021): Then it’s totally ok! If you want you can open a PR and fix that! I’d love it :) On Thu, 30 Sep 2021 at 16:06, Derek Murawsky ***@***.***> wrote: > @derekmurawsky <https://github.com/derekmurawsky> At the moment the > convention is totally open to provide support to most of the tooling > around, I agree with you that those are really good rules for writing a > commit message, but still, I'd consider those not mandatory for the current > state of the specification. > > Thanks for the reply! > > To clarify, I meant that we should either reference the other work or > improve *the example*. I did *not* mean it should be included in the > standard itself. > > And I don't mean to speak for @shaman-apprentice > <https://github.com/shaman-apprentice> - But I believe they were > referring to the examples as well. > > — > You are receiving this because you commented. > Reply to this email directly, view it on GitHub > <https://github.com/conventional-commits/conventionalcommits.org/issues/348#issuecomment-931354904>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/ACEJFZ2LO543WKHVNCE3SMLUERVE3ANCNFSM4YZQXPIQ> > . >

GiteaMirror commented

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

@shaman-apprentice commented on GitHub (Oct 1, 2021):

I am just writing quickly from train and I don't want to rush. Thanks for your comments! I will gladly create a PR in the next days.

@shaman-apprentice commented on GitHub (Oct 1, 2021): I am just writing quickly from train and I don't want to rush. Thanks for your comments! I will gladly create a PR in the next days.

GiteaMirror referenced this issue

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

[PR #122] [MERGED] chore(readme): update config.yml to match config.yaml #301

GiteaMirror referenced this issue

2026-04-11 07:24:21 -05:00

[PR #122] [MERGED] chore(readme): update config.yml to match config.yaml #960

GiteaMirror referenced this issue

2026-04-13 12:53:09 -05:00

[PR #122] [MERGED] chore(readme): update config.yml to match config.yaml #1623

GiteaMirror referenced this issue

2026-04-16 01:21:55 -05:00

[PR #122] [MERGED] chore(readme): update config.yml to match config.yaml #2286