conventionalcommits.org, a website that introduces people to the concept of conventional commits #1

New Issue

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

GiteaMirror commented

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

Originally created by @bcoe on GitHub (Mar 31, 2017).

This post may be somewhat controversial, being Canadian I'm prefacing the whole thing with an apology 🍁

What's is conventional-changelog?

The conventional-changelog organization is a set of modules for parsing various flavors of commit message formats (angular, atom, jquery, ...), and performing useful operations based on this meta-information:

CHANGELOG generation.
recommended semantic version bumps.

Despite conventional-changelog's abstract design, many of the tools related to the conventional-changelog ecosystem are adopting the angular commit convention:

semantic-release: defaults to the angular commit format (although other formats can be provided).
standard-version: is an opinionated CLI tool, built specifically around the angular commit conventions, and has seen wide adoption.
lerna: the lerna community has, so far, embraced the introduction of the angular commit conventions (as a way to simplify managing disparate versions in a mono-repo).

The Value of Conventional Commits

When evangelizing adopting a conventional commit format to people, there are a few things I emphasize:

as a maintainer, at the time when I land a feature branch, I'm encouraged to think a little
bit more than I usually would and come up with a useful commit message -- this makes for a much more useful commit history in general.
given that the angular commit format is based on semver (BREAKING CHANGE, fix, feat), you become able to programmatically determine what the version bump for the next release should be.
when a bad release goes out the door, it's much easier to identify the root cause when an accurate CHANGELOG is in place.

perhaps most importantly!

I emphasize that it doesn't add much work:

add the conventional commit message when you squash, don't force each contributor to adhere.
use tools like semantic-release, standard-version, lerna, etc., to automate
things.

Avoiding a Paradox of Choice

I found a few things confusing when introduced to the conventional-changelog ecosystem and the concept of the angular commit convention:

I felt conventional-changelog should be more prescriptive; It's great to have flexible core libraries, but as a user I was mainly interested in: eliminating tedium around version bumps, and CHANGELOG management,
I wanted a happy path that introduced me to the concept of conventional commits.
The documentation on the topic of conventional-commit formats is spread out between, conventional-changelog, semantic-release, angular, etc.

Proposal

I really like the semver.org specification. It introduces the concept of semantic
versioning in a clear, tool agnostic way, explaining its value to the software development process.

I propose that for the conventional-changelog.github.io website, we put up a site modeled after semver.org -- potentially hosted at conventionalcommits.org:

let's make this website concentrate on the high-level value gained by introducing conventional
commits to your project.
let's use the angular commit format as the basis for conventional-commits: it has wide adoption, it's simple, and seems like a great format to standardize on.
let's have a section that introduces people to a few of the projects adopting this standard:
semantic-release, lerna, standard-version, but let's not make the website focus on the
conventional-changelog project itself.

Help Wanted!

How do folks feel about this proposal? I would love help pulling together documentation
for conventionalcommit.org; I think it will be a great place for us to point our various users to.

I reached out to @mojombo, he'd happily let us use the design from the semver.org website as
a jumping off point for our specification; @JaKXz also indicated that he'd be excited to help us setup a scaffolding using fancy pants new web technologies.

CC: @ajoslin, @stevemao, @Tapppi, @evocateur, @boennemann

Originally created by @bcoe on GitHub (Mar 31, 2017). _This post may be somewhat controversial, being Canadian I'm prefacing the whole thing with an apology 🍁_ ## What's is conventional-changelog? The conventional-changelog organization is a set of modules for parsing various flavors of commit message formats (angular, atom, jquery, ...), and performing useful operations based on this meta-information: * CHANGELOG generation. * recommended semantic version bumps. Despite conventional-changelog's abstract design, many of the tools related to the conventional-changelog ecosystem are adopting the angular commit convention: * [semantic-release](https://github.com/semantic-release/semantic-release#default-commit-message-format): defaults to the angular commit format (although other formats can be provided). * [standard-version](https://github.com/conventional-changelog/standard-version): is an opinionated CLI tool, built specifically around the angular commit conventions, and has seen wide adoption. * [lerna](https://github.com/lerna/lerna/pull/665): the lerna community has, so far, embraced the introduction of the angular commit conventions (as a way to simplify managing disparate versions in a mono-repo). ## The Value of Conventional Commits When evangelizing adopting a conventional commit format to people, there are a few things I emphasize: * as a maintainer, at the time when I land a feature branch, I'm encouraged to think a little bit more than I usually would and come up with a useful commit message -- this makes for a much more useful commit history in general. * given that the angular commit format is based on semver (`BREAKING CHANGE`, `fix`, `feat`), you become able to programmatically determine what the version bump for the next release should be. * when a [bad release goes out the door](https://github.com/facebook/jest/issues/3179), it's much easier to identify the root cause when an accurate CHANGELOG is in place. _perhaps most importantly!_ I emphasize that it doesn't add much work: * add the conventional commit message when you squash, don't force each contributor to adhere. * use tools like `semantic-release`, `standard-version`, `lerna`, etc., to automate things. ## Avoiding a Paradox of Choice I found a few things confusing when introduced to the `conventional-changelog` ecosystem and the concept of the angular commit convention: * I felt `conventional-changelog` should be more prescriptive; It's great to have flexible core libraries, but as a user I was mainly interested in: eliminating tedium around version bumps, and CHANGELOG management, I wanted a happy path that introduced me to the concept of conventional commits. * The documentation on the topic of conventional-commit formats is spread out between, `conventional-changelog`, `semantic-release`, `angular`, etc. ## Proposal I really like the [semver.org](http://semver.org/) specification. It introduces the concept of semantic versioning in a clear, tool agnostic way, explaining its value to the software development process. I propose that for the `conventional-changelog.github.io` website, we put up a site modeled after semver.org -- potentially hosted at conventionalcommits.org: * let's make this website concentrate on the high-level value gained by introducing conventional commits to your project. * let's use the angular commit format as the basis for `conventional-commits`: it has wide adoption, it's simple, and seems like a great format to standardize on. * let's have a section that introduces people to a few of the projects adopting this standard: semantic-release, lerna, standard-version, but let's not make the website focus on the conventional-changelog project itself. ### Help Wanted! How do folks feel about this proposal? I would love help pulling together documentation for conventionalcommit.org; I think it will be a great place for us to point our various users to. I reached out to @mojombo, he'd happily let us use the design from the semver.org website as a jumping off point for our specification; @JaKXz also indicated that he'd be excited to help us setup a scaffolding using _fancy pants new_ web technologies. CC: @ajoslin, @stevemao, @Tapppi, @evocateur, @boennemann

GiteaMirror closed this issue

2026-02-17 11:30:37 -06:00

GiteaMirror commented

2026-02-17 11:30:38 -06:00

@evocateur commented on GitHub (Mar 31, 2017):

I also like the example of http://keepachangelog.com/. I think this would be a great idea for conventional-commits + friends.

@evocateur commented on GitHub (Mar 31, 2017): I also like the example of http://keepachangelog.com/. I think this would be a great idea for `conventional-commits` + friends.

GiteaMirror commented

2026-02-17 11:30:40 -06:00

@bcoe commented on GitHub (Apr 1, 2017):

I'm looping in @jameswomack as well, who works on unleash; a cool release management tool that also adheres to the angular commit standards.

@bcoe commented on GitHub (Apr 1, 2017): I'm looping in @jameswomack as well, who works on [unleash](https://www.npmjs.com/package/unleash); a cool release management tool that also adheres to the angular commit standards.

GiteaMirror referenced this issue

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

[PR #157] [MERGED] feat(lang): add brazilian portuguese (pt-br) language #326

GiteaMirror referenced this issue

2026-02-17 12:01:54 -06:00

[PR #255] [MERGED] feat: add turkish translation to v1.0.0 #395

GiteaMirror referenced this issue

2026-02-17 12:03:05 -06:00

[PR #308] [MERGED] fix(content): add missing periods #427

GiteaMirror referenced this issue

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

[PR #331] [CLOSED] docs(summary): rm `:` colon in type values #443