First Sumary Sentence Seems Out of Place #38

New Issue

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

GiteaMirror commented

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

Originally created by @hutson on GitHub (Aug 19, 2018).

The first summary sentence:

As an open-source maintainer, squash feature branches onto master and write a standardized commit message while doing so.

Seems out of place.

I land on the conventionalcommits website and the first sentence is talking about squashing commits (something I don't do), but only for features (so what am I supposed to do for other commit types), and only talks about open-source maintainers, which seems to exclude third-party contributors to a project.

Can we just eliminate that sentence?

Originally created by @hutson on GitHub (Aug 19, 2018). The first summary sentence: ``` As an open-source maintainer, squash feature branches onto master and write a standardized commit message while doing so. ``` Seems out of place. I land on the `conventionalcommits` website and the first sentence is talking about squashing commits (something I don't do), but only for features (so what am I supposed to do for other commit types), and only talks about `open-source maintainer`s, which seems to exclude third-party contributors to a project. Can we just eliminate that sentence?

GiteaMirror added the suggestion label 2026-02-17 11:36:22 -06:00

GiteaMirror closed this issue

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

GiteaMirror commented

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

@damianopetrungaro commented on GitHub (Aug 20, 2018):

@hbetts yup, totally agree, I already asked about it.
It was partially done with #58 but we need to rephrase this instead of removing it IMHO.

A little summary it's fine to have in place ;)

@damianopetrungaro commented on GitHub (Aug 20, 2018): @hbetts yup, totally agree, I already asked about it. It was partially done with #58 but we need to rephrase this instead of removing it IMHO. A little summary it's fine to have in place ;)

GiteaMirror commented

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

@damianopetrungaro commented on GitHub (Aug 20, 2018):

This sentence too sounds strange to me:

In software development, it’s been my experience that bugs are most often introduced at the boundaries between applications. Unit testing works great for testing the interactions that a maintainer knows about, but do a poor job of capturing all the interesting, often unexpected, ways that a community puts a library to use.

@damianopetrungaro commented on GitHub (Aug 20, 2018): This sentence too sounds strange to me: ``` In software development, it’s been my experience that bugs are most often introduced at the boundaries between applications. Unit testing works great for testing the interactions that a maintainer knows about, but do a poor job of capturing all the interesting, often unexpected, ways that a community puts a library to use. ```

GiteaMirror commented

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

@hutson commented on GitHub (Aug 21, 2018):

What needs to be rephrased, and how do you see it being rephrased?

@hutson commented on GitHub (Aug 21, 2018): What needs to be rephrased, and how do you see it being rephrased?

GiteaMirror commented

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

@damianopetrungaro commented on GitHub (Aug 26, 2018):

@hbetts

The main issue is that the entire first block seems to be out of context and it's justified only by the last sentence of the entire introduction that makes it easier to debug issues across project boundaries.

In software development, it’s been my experience that bugs are most often introduced at the boundaries between applications. Unit testing works great for testing the interactions that a maintainer knows about, but do a poor job of capturing all the interesting, often unexpected, ways that a community puts a library to use.
Anyone who has upgraded to a new patch version of a dependency, only to watch their application start throwing a steady stream of 500 errors, knows how important a readable commit history (and ideally a well maintained CHANGELOG) is to the ensuing forensic process.
The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages. This convention dovetails with SemVer, asking software developers to describe in commit messages, features, fixes, and breaking changes that they make.

By introducing this convention, we create a common language that makes it easier to debug issues across project boundaries.

I think this will be better:

The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages.
This convention dovetails with SemVer, asking software developers to describe in commit messages, features, fixes, and breaking changes that they make, in order to create a readable commit history (and ideally a well-maintained CHANGELOG) and creating a common language that makes it easier to debug issues.

Let's see also the other mebers think about it @conventional-commits/committee

@damianopetrungaro commented on GitHub (Aug 26, 2018): @hbetts The main issue is that the entire first block seems to be out of context and it's justified only by the last sentence of the entire introduction `that makes it easier to debug issues across project boundaries.` > ~In software development, it’s been my experience that bugs are most often introduced at the boundaries between applications. Unit testing works great for testing the interactions that a maintainer knows about, but do a poor job of capturing all the interesting, often unexpected, ways that a community puts a library to use. Anyone who has upgraded to a new patch version of a dependency, only to watch their application start throwing a steady stream of 500 errors, knows how important a readable commit history (and ideally a well maintained CHANGELOG) is to the ensuing forensic process.~ The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages. This convention dovetails with SemVer, asking software developers to describe in commit messages, features, fixes, and breaking changes that they make. > > By introducing this convention, we create a common language that makes it easier to debug issues across project boundaries. I think this will be better: > The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages. This convention dovetails with SemVer, asking software developers to describe in commit messages, features, fixes, and breaking changes that they make, in order to create a readable commit history (and ideally a well-maintained CHANGELOG) and creating a common language that makes it easier to debug issues. Let's see also the other mebers think about it @conventional-commits/committee

GiteaMirror commented

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

@damianopetrungaro commented on GitHub (Aug 26, 2018):

@hbetts what o you think about

As a software developer, I want to create a readable commit history writing standardized commit messages to make easier and explicit what changes have been applied to a project.

For the first sentence?

@damianopetrungaro commented on GitHub (Aug 26, 2018): @hbetts what o you think about ``` As a software developer, I want to create a readable commit history writing standardized commit messages to make easier and explicit what changes have been applied to a project. ``` For the first sentence?

GiteaMirror commented

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

@damianopetrungaro commented on GitHub (Aug 26, 2018):

@hbetts I can open a PR for his, let me know if you are fine with those changes

@bcoe @zeke give a feedback too please 😄

@damianopetrungaro commented on GitHub (Aug 26, 2018): @hbetts I can open a PR for his, let me know if you are fine with those changes @bcoe @zeke give a feedback too please 😄

GiteaMirror commented

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

@hutson commented on GitHub (Aug 27, 2018):

@damianopetrungaro I agree that there are issues in the introduction, but I was trying to keep this issue scoped to just the first sentence of the website/convention.

As a software developer

That sentence has the same issue of being very specific to a group of open source contributors.

If we are looking at re-wording the Introduction section, I would propose we do that, followed by taking the new content and making it the first paragraph of the Summary section, thereby eliminating the Introduction section. (My reasoning is that if you have an introduction, it should be placed first so that it introduces the rest of the website content.)

@hutson commented on GitHub (Aug 27, 2018): @damianopetrungaro I agree that there are issues in the introduction, but I was trying to keep this issue scoped to just the first sentence of the website/convention. > As a software developer That sentence has the same issue of being very specific to a group of open source contributors. If we are looking at re-wording the _Introduction_ section, I would propose we do that, followed by taking the new content and making it the first paragraph of the _Summary_ section, thereby eliminating the _Introduction_ section. (My reasoning is that if you have an introduction, it should be placed first so that it _introduces_ the rest of the website content.)

GiteaMirror commented

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

@damianopetrungaro commented on GitHub (Aug 27, 2018):

@hbetts totally agree, let's reword the first section and let's remove the introduction.
Something like this it's fine for me:

# Summary:
As a software developer, I want to create a readable commit history writing standardized commit messages to make easier and explicit what changes have been applied to a project.

The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages.

This convention dovetails with SemVer, asking software developers to describe in commit messages, features, fixes, and breaking changes that they make, in order to create a readable commit history (and ideally a well-maintained CHANGELOG) and creating a common language that makes it easier to debug issues...

# Examples
Commit message with description...

# Specification
The key words MUST....

Let me know what do you think, let's see what @bcoe thinks about it, he always find some issues that we miss 😄

@damianopetrungaro commented on GitHub (Aug 27, 2018): @hbetts totally agree, let's reword the first section and let's remove the `introduction`. Something like this it's fine for me: ``` # Summary: As a software developer, I want to create a readable commit history writing standardized commit messages to make easier and explicit what changes have been applied to a project. The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages. This convention dovetails with SemVer, asking software developers to describe in commit messages, features, fixes, and breaking changes that they make, in order to create a readable commit history (and ideally a well-maintained CHANGELOG) and creating a common language that makes it easier to debug issues... # Examples Commit message with description... # Specification The key words MUST.... ``` Let me know what do you think, let's see what @bcoe thinks about it, he always find some issues that we miss 😄

GiteaMirror commented

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

@damianopetrungaro commented on GitHub (Aug 28, 2018):

See #91

@damianopetrungaro commented on GitHub (Aug 28, 2018): See #91

GiteaMirror commented

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

@bcoe commented on GitHub (Sep 16, 2018):

@hbetts @damianopetrungaro see my notes in #91, my concern about moving the introduction section to the top is that "Conventional Commits" is an attempt to describe a standard.

If you look at semver.org, the content immediately jumps into a functional description of what a user adhering to the standard should do. For this reason, I advocate that we opt for a first sentence that reads something like my proposal on #91:

When writing software use a standardized commit message, such that the commit history conveys meaning to developers and can be more easily consumed by tools.

I don't see a strong argument for removing the Introduction section from the conventional commits. I modeled the original document after https://semver.org/, which uses a similar structure:

Summary; introducing a trimmed down version of the spec.
Introduction; explaining the motivation for the specification.
a more thorough break down of the specification.

We've done well for the past couple years using semver as a foundation for how we approach this specification. And semver.org has done an amazing job of gaining traction of the years. I see no reason for us to deviate from a pattern that's worked.

@bcoe commented on GitHub (Sep 16, 2018): @hbetts @damianopetrungaro see my notes in #91, my concern about moving the introduction section to the top is that "Conventional Commits" is an attempt to describe a standard. If you look at semver.org, the content immediately jumps into a functional description of what a user adhering to the standard should do. For this reason, I advocate that we opt for a first sentence that reads something like my proposal on #91: > When writing software use a standardized commit message, such that the commit history conveys meaning to developers and can be more easily consumed by tools. I don't see a strong argument for removing the Introduction section from the conventional commits. I modeled the original document after https://semver.org/, which uses a similar structure: 1. Summary; introducing a trimmed down version of the spec. 2. Introduction; explaining the motivation for the specification. 3. a more thorough break down of the specification. We've done well for the past couple years using semver as a foundation for how we approach this specification. And semver.org has done an amazing job of gaining traction of the years. I see no reason for us to deviate from a pattern that's worked.

GiteaMirror commented

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

@hutson commented on GitHub (Sep 17, 2018):

When writing software use a standardized commit message, such that the commit history conveys meaning to developers and can be more easily consumed by tools.

@bcoe I like your suggestion, though I would like to propose replace When writing software ... to When contributing to a project ... as not all participants in Open Source write software.

@hutson commented on GitHub (Sep 17, 2018): > When writing software use a standardized commit message, such that the commit history conveys meaning to developers and can be more easily consumed by tools. @bcoe I like your suggestion, though I would like to propose replace `When writing software ...` to `When contributing to a project ...` as not all participants in Open Source write software.

GiteaMirror referenced this issue

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

Question: What approach have people used for work in progress features? #63

GiteaMirror referenced this issue

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

Confusion about the extent of feat #86

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/conventionalcommits.org#38