mirror of
https://github.com/conventional-commits/conventionalcommits.org.git
synced 2026-03-22 12:44:37 -05:00
Confusion over "body" #70
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @epage on GitHub (Jul 26, 2019).
The way the spec is written, it sounds like there can only be one paragraph in the body but I'm assuming that isn't the case because there are a lot of times when a commits need multiple paragraphs. This confusion is exacerbated by the discussion in #98 which makes it sound like the footer can be assumed based on the number of paragraphs.
Also, it sounds like "BREAKING CHANGE" must precede the first paragraph in the body?
@bcoe commented on GitHub (Jul 29, 2019):
This is a conversation worth having, I believe the way things are written it's assumed your
bodyand firstfooterwill be separated by two newlines, so if you did have multiple paragraphs you would write them, like:There is an expectation that
BREAKING CHANGE:will start the first paragraph when the PR represents a breaking change, my expectation currently is that the breaking change would then pull in the full body -- I don't think we'd only want the breaking change section to only display the first paragraph?@epage commented on GitHub (Jul 29, 2019):
Since your comment in #171 was a little more explicit
@epage commented on GitHub (Jul 29, 2019):
The suggestion to indent further paragraphs seems at odds with wider git commit styles like tpope and chris beams talk about. Conventional could go its own direction on this but I suspect that will hurt adoption.
Personally, I also treat git commit messages as markdown, which would have paragraphs separated by extra newlines. This is reinforced by common platforms, like github, taking commit messages and making them the PR message.
@bcoe commented on GitHub (Jul 29, 2019):
@epage this creates an ambiguity in the grammar between what's a footer and what's a body, is my concern; I don't want to define a specification that's not easily machine readable, I also don't want to introduce that many additional rules, e.g., that footers need to be key values (even that is ambiguous).
@epage commented on GitHub (Jul 29, 2019):
I understand the concern over ambiguity. I'm writing a parser which led me to these questions. I also strongly value inter-operating with existing tooling, processes, and practices and am hopeful that we can find a way to satisfy all
^Wmost of them. I suspect it will take a wider look at ways of resolving the ambiguity would be helpful, similar to some of the discussion in #98 before people (seemed) to settle on footer requiring a body.And yes, footer being key/value pairs only gives parse hints; it doesn't make anything definitive. I do not even know strict that pattern is in various footers/trailers. Github's
Closed #<N>fits a role similar to the footers and isn't a key/value pair.@epage commented on GitHub (Jul 30, 2019):
I think a fairly unobtrusive unambiguous rule would be for the footer to be defined as the the section after the last markdown horizontal rule. We could even constrain it to a subset of markdown's horizontal rule definition to simplify parsing, ie 3+
-in direct sequence. I'm mixed about whether to require a blank line before and after the horizontal rule.Adapting your earlier example:
And one from the web page
@damianopetrungaro commented on GitHub (Jul 30, 2019):
Jumping by to drop my 2 cents:
This is how it should be split IMHO (as it is described right now).
If you need to have a lot of paragraphs probably the PR is too big.
It is easy to automate, easy to understand just looking at it and already used by the whole community that has no issue with it.
What is the point of your issue? Where did you see a real limit of the convention?
Just asking so I can understand better :)
@epage commented on GitHub (Jul 30, 2019):
From my perspective, that is not described in the spec.
Remember, this is not even the PR but the commit which is even worse for it to be too big :)
And while I can understand the sentiment that too much text is a smell for a ommit that does too much, there are a lot of valid cases for multi-paragraph commit messages. For one commit, I included benchmark information which had newlines embedded in it as one example.
Also, I already feel
type+ subject does a great job of encouraging atomic commits.I wonder how much of the conventional community understands this limitation. I've been using conventional for years and seen other people using it as well. I've always seen paragraphs separated by newlines. I'll admit, there might be some bias in us sharing knowledge and learning from each other.
First, the issue was because the convention isn't stated and is left for people to read into it what they want to read into it.
As for limitations:
@bcoe commented on GitHub (Jul 31, 2019):
@damianopetrungaro I think this is a conversation worth having; I'm personally not a fan of introducing an additional markdown token, like,
----.I like the simplicity of having the footer sections and body separated by
\n\n, but it does fall short of supporting some PR formats, such as:e378e7d7b1When we hit points of friction like this, I like the discussion, even if ultimately we just add clarification to an FAQ.
@JeanMertz commented on GitHub (Aug 9, 2019):
I'm writing a tool that uses conventional commits as well, and build a small parser in Rust to get the relevant commit details. I have to agree with the points @epage made.
Here are a couple of points worth considering:
Adding to this, it's worth noting that even Git itself does some hacky/fancy (take your pick) string parsing. For example, in annotated signed git tags, they parse the message for
-----BEGIN PGP SIGNATURE-----to strip the signature out of the message itself.All in all, given the importance of parsing for breaking changes, I feel that a clear separation between the three "parts" of a commit would be a good design:
===) without messing up the parser.@damianopetrungaro commented on GitHub (Aug 10, 2019):
Ok I think that at this point PR are welcome and we can simply discuss what's the best separator between the different sections.
@JeanMertz commented on GitHub (Aug 10, 2019):
Reading the spec again, and thinking out loud, I wonder if it even makes sense to have the concept of a "footer", or if we should simply have a way to identify commit metadata specifically.
If we tightened the spec a bit, you could say something like:
[ALL CAPS]is considered to contain meta-information about the commit.Then, the metadata specification could mention the following:
[BREAKING CHANGE]for breaking changes introduced in the commit[RESOLVES]for linking to issues that are resolved in this commit.*/-, andcloses/fixesto have GH auto-close issues, and support lists, parsers should take this into account.[...]is also considered part of the metadata, and should be parsed as[<metadata type>] <metadata content>by parsers, but their purpose are not (yet) encoded in the spec.That last one is important I think, to support the use-case of writing extensive breaking change documentation in a commit.
So let's take an example:
So the above would parse as:
It introduces all the new features.
broke because of this change.
So much broke, that it requires summing up all breakage.
* by
* using
* bullet
* points
And then a final "sorry for the trouble!".
Which doesn't have to start on the same line as "[CUSTOM]"
I feel like this would strike the best balance between:
[and])So basically the concept of a "footer" would no longer exist, unless you want to mention that the "footer" starts at the first occurrence of a metadata tag, but I don't think there's any value in including that in the spec, to be honest.
Let me know what you think, I would be willing to write the changes in the spec for this.
@JeanMertz commented on GitHub (Aug 10, 2019):
Building a bit on the above, I think just supporting
[ALL CAPS]as metadata is not enough. I think single line metadata with colons to separate the type from the value is also needed, so an extension to the above could be to also support:This is to support already existing non-standard usage of these tags to automate certain processes in big repositories and hosters such as Github (something @epage also brought up in https://github.com/conventional-commits/conventionalcommits.org/issues/171).
I haven't thought of what it would mean to merge this with what I wrote above, but at least both of these are unambiguous, and can co-exist together.
@epage commented on GitHub (Aug 10, 2019):
So hosting services, like github, support extracting
Closes #<num>. Would adding the:break support for that feature? If so, I suspect that will surprise too many people that our recommendation does not align with github.@JeanMertz commented on GitHub (Aug 14, 2019):
It does not appear to break support:
I'm pretty sure they added support for the colon because it's a known standard in Git.
@blowmage commented on GitHub (Aug 15, 2019):
FWIW, I would prefer it if the footer was wrapped in
[]:@epage commented on GitHub (Aug 16, 2019):
The downside to that is it isn't compatible with git conventions for trailers which I assume we'd want to be compatible with.
@bcoe commented on GitHub (Aug 20, 2019):
I think @JeanMertz has put together a very compelling proposal here:
https://github.com/conventional-commits/conventionalcommits.org/issues/179