mirror of
https://github.com/conventional-commits/conventionalcommits.org.git
synced 2026-03-22 12:44:37 -05:00
Consolidate Summary Items With Specification #39
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/conventionalcommits.org#39
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 @hutson on GitHub (Aug 19, 2018).
I would like to suggest we consolidate the numbered items under the Summary section into the Conventional Commits Specification section.
@damianopetrungaro commented on GitHub (Aug 26, 2018):
@hbetts what do you mean with this?
@hutson commented on GitHub (Aug 27, 2018):
Items 1 through 4 in the Summary are a duplication of content in the Specification section.
They feel like extra reading without adding any value.
@damianopetrungaro commented on GitHub (Aug 27, 2018):
Let looks good to me, they are a summary of the specs.
What do you suggest?
@damianopetrungaro commented on GitHub (Feb 8, 2019):
@hutson any other input?
@hutson commented on GitHub (Feb 9, 2019):
Thank you for bringing it back to my attention.
So re-reading the website, I still feel the summary section is a duplicate of the specification content.
Now, perhaps, the summary can help learn the bare minimum needed to start using the convention. However, there are additional requirements in the specification that aren't covered in the summary. For example, the description is a requirement, yet it's not covered in the summary.
On Fri, Feb 8, 2019, at 6:55 AM, Damiano Petrungaro wrote:
@damianopetrungaro commented on GitHub (Feb 18, 2019):
I do agree with you, and there was a huge discussion with @bcoe where we had different opinions.
This issue is the third time that someone has this feeling about it, so there is space for improvement.
Do you want to take it and try to rephrase it in a better way?
@bcoe commented on GitHub (Feb 18, 2019):
Here's why I would strongly argue against removing the summary section.
The motivation of standard-version, and the conventional-commits specification was that at npm, Inc, we were not doing a good job of documenting changes to npm's various services, such that whenever it came time to cut a release of npm Enterprise it was hard to tell what major features had changed since we last put the product out -- resulting in frequently breaking customers.
@nexdrew advocated pulling in a conventional commit message format, as a way to prevent this ... here's the problem, it's a pain in the butt to switch how you write commit messages, and getting buy-in from the engineering team would have potentially been difficult...
The goal was to create a convention and methodology so simple that engineers would gradually adopt it because it's a no brainer. Long story short, I'll argue that the summary is the most important part of this document, it's what demonstrates to engineers that you can start using the conventional commits methodology with a few simple changes to your engineering practices ... making someone read an 11-point specification does not do this.
@bcoe commented on GitHub (Feb 18, 2019):
I might add that conventional-commits has been successful, and has gained wide adoption at npm, Inc and across other open-source projects, I think it would be a huge mistake to remove the simple summary of the specification in favor of the daunting 11-point specification.
@bcoe commented on GitHub (Feb 18, 2019):
@hutson @damianopetrungaro
☝️ this is exactly what the summary should be treated as; someone to hit the ground running with conventional commit messages, as an example, probably doesn't need to know:
A footer MAY be provided one blank line after the body. The footer SHOULD contain additional issue references about the code changes (such as the issues it fixes, e.g.,Fixes #13).
And it starts to feel a bit overwhelming if it feels like I do need to know all these edge-cases. Perhaps we just need to word-smith the summary a bit, so that it gets at the heart of the specification.
... If folks do feel that we need all 11 points to hit the ground running with the spec, I'd argue that it's time to start over again with this project; we didn't succeed in making a simple convention.
@nexdrew commented on GitHub (Feb 18, 2019):
My opinion might not hold a lot of weight, but I agree with @bcoe. Ever since adopting the convention - at npm, in my open source work, and with my current development team - the thing that has won people over is the simplicity of the convention and the ease of applying it to a GitHub-flow methodology.
I, for one, appreciate the simplified summary - in my experience, that's what most folks read/care about; we only need to dig into the actual spec if there are questions about details or if we're attempting to enforce the spec, like probot does.
If anything, I think the summary should be simplified further, not removed. The main thing everyday developers need to know are the
feat:orfix:prefixes and theBREAKING CHANGE:explanation. The next most important part is when to apply these conventions, which, when using GitHub-flow, is only when squashing and merging PRs, but that is perhaps beyond the scope of the spec.@nexdrew commented on GitHub (Feb 18, 2019):
I would argue that, when I go to the conventionalcommits.org site, the primary goal should be to quickly and concisely tell what the spec is and why it's useful, perhaps pointing to a handful of the tools that make developers lives easier when using it. IMO this is what the summary should represent. All the other details can be explained subsequently and secondarily.
@zkat commented on GitHub (Feb 18, 2019):
I'd much rather read as concise a spec as possible, and only read the details if I need to implement something myself.
@hutson commented on GitHub (Feb 19, 2019):
@bcoe @nexdrew @zkat thank you all for your input, and insight, on how you, among many others, use the Summary section to help build a culture that leads to high quality commit messages, and successful product execution.
@damianopetrungaro I still feel there are opportunities for targeted improvements to the Summary section that may provide additional clarity. Please let me close this issue out and attempt to open up issues that address specific points of confusion I have with the summary that are more targeted and respect the strong value a summary provides.