---
# System prepended metadata

title: Conventional Commits WG

---

# Conventional Commits WG

July 15th

Guests:

* Ben.
* Cedric.
* Eemeli.

* What are folks hoping to get out of this meeting:
  * Eemeli: is having trouble finding tooling in the ecosystem that meets needs
    for releases:
    * hoping to replace some of the lerna tool chain.
    * figuring out the best starting point.
  * Ben: would like to get conventional commits to the point where
    it's a good foundation for building tooling.
    * Eemeli: would like to get what he's working on back in the ecosystem.
  * Lots of work for commit lint. Not a super strong opinion towards anything:
    * has been using it in work at Expo.
    * believes in the approach.
* Show and tell from Ben:
  * Grammar and AST parser: https://github.com/conventional-commits/parser/tree/main/lib
  * Library using this approach: https://github.com/googleapis/release-please
    * release-please is what we've been using for all our stuff at google.
* Eemeli: talk a bit about parser:
  * oddities found in parsing: comma separted #122, #133, #144.

```
fix(my-thing): hello world

Fixes #390 this is fixing an issue.
hello world.

Author: @bcoe"

message[5] (1:1-6:14, 0-91)
├─0 summary[5] (1:1-1:27, 0-26)
│   ├─0 type "fix" (1:1-1:4, 0-3)
│   ├─1 scope[3] (1:4-1:14, 3-13)
│   │   ├─0 scope-start "(" (1:4-1:5, 3-4)
│   │   ├─1 scope-text "my-thing" (1:5-1:13, 4-12)
│   │   └─2 scope-end ")" (1:13-1:14, 12-13)
│   ├─2 separator ":" (1:14-1:15, 13-14)
│   ├─3 whitespace " " (1:15-1:16, 14-15)
│   └─4 text "hello world" (1:16-1:27, 15-26)
├─1 newline "\n\n" (1:27-3:1, 26-28)
├─2 body[3] (3:1-4:13, 28-76)
│   ├─0 text "Fixes #390 this is fixing an issue." (3:1-3:36, 28-63)
│   ├─1 newline "\n" (3:36-4:1, 63-64)
│   └─2 text "hello world." (4:1-4:13, 64-76)
├─3 newline "\n\n" (4:13-6:1, 76-78)
└─4 footer[4] (6:1-6:14, 78-91)
    ├─0 token[1] (6:7-6:7, 84-84)
    │   └─0 type "Author" (6:1-6:7, 78-84)
    ├─1 separator ":" (6:7-6:8, 84-85)
    ├─2 whitespace " " (6:8-6:9, 85-86)
    └─3 value[1] (6:9-6:14, 86-91)
        └─0 text "@bcoe" (6:9-6:14, 86-91)
```

* Eemeli what usage is footer?
  * Ben: we use this for a several things at Google: rollbacks, tracking commits.
  * Cedric: having something resembling key value pairs.
    * [git-trailers](https://git-scm.com/docs/git-interpret-trailers).



May 7th

* Ben
* Wes

* TODO: let's make an issue to move our meeting time.
    * Wes has something that comes up on Fridays.
    * Ben is going to be EST now.
* Ben approval to ship randomUUID().
    * So now has time to put work into this.
* Conventional Commit technical
* 

April 9th

* Benjamin
* Cedric
* Wes


* Wes' patch to make our tree a full AST.
    * [Wes]: I think nesting it in a node is reasonable.
        * Ben agrees.
        * https://gist.github.com/bcoe/f2330eae198c5d720fb1c8ed44d73d6a
* [ben]: Google continues to double down on Conventional Commits.
    * LTS becoming a really important need for us.
* Wes how tightly tied to semver are we:
    ```
    Auto-generated CL for //google/pubsub:pubsub_public_proto_gen

    It contains one or more of the following:
        - sanitized API protos
        - sanitized OnePlatform service config
        - gRPC ServiceConfig file(s) (unmodified from source)
        - generated Bazel BUILD files

    BEGIN_PUBLIC
    feat: Add topic retention options.
    END_PUBLIC
    ```
    * We have a pool of people on our team who reviewd the message format for the first few months.
* Working on next version of spec.
    * v2 of the spec <-- consider standards body.
        * https://hackmd.io/2Rl1AYyPTJSks5R4KjhlDg <-- we should start fleshing this out.
    * https://google.aip.dev/
* `DEPRECATION`, similar to `BREAKING-CHANGE` footer:
    * feature request from angular folks, we keep getting more stakeholders.
    * Any /[A-Z-]{2}/ <-- this is very English centric.
* Wes' tool recommended bump:
    * https://github.com/conventional-commits/git-recommended-bump
* Markdown generation.
    * https://github.com/googleapis/google-api-nodejs-client/pull/2582 <-- so we can customize PRs like that.
    * customization is the user need.
        * https://github.com/googleapis/release-please/blob/a99a5357c0797f9a5651b492ceab9c123216e042/src/manifest.ts#L514


February 26th

**Attendance:**

* Benjamin.
* Cedric.
* Wes.

* Rolling out a bunch of original tooling;
    * not using the new parser yet; it was promising and hoping to pick it up soon.
    * the part with the parser worked well:
    * Ben: noticing really weird bugs. Conventional Changelog Markdown generation:
        * order is random depending on operating system (compare-func).
        * would love to pull in Cedric's markdown implementation at some point in the future.
            * integration tests for current markdown: https://github.com/googleapis/release-please
        * Ben: pick a few key tools we need:
            * bump figuring out.
            * changelog.
            * parser.
            * conventional-commits.
        * Wes: let's reach out to Daniel Stockman.
* Fun monorepo stuff:
    * https://github.com/googleapis/release-please/pull/803
* Moving towards v2 of the spec:
    * let's flesh out v2 of the spec: https://hackmd.io/2Rl1AYyPTJSks5R4KjhlDg
    * could I find someone who's excited to contribute to conventional commits website?
* Outstanding work in the parser:
    * maybe "* " is a bad idea?
        * inconclusive.
    * we're still missing some elements in the token:
        * some tokens aren't in tree.

Meeting January 15th 2021

*Attendance:**

* Cedric.
* Ben.
* Wes.

* Talk about what standardization continues to look lik
    * IETF maybe not a good fit.
    * Wes: pushing on this a little bit:
        * v1 didn't align very well with some very common practices.
        * Ben: agrees let's make v2 less likely to change.
        * Can we find something similar to conventional commits specified anywhere?
* Internal adoption:

```
feat: adds v4 UUID to crypto

This adds support for v4 UUIDs to the library.

fix(utils): unicode no longer throws exception
  PiperOrigin-RevId: 345559154
  BREAKING-CHANGE: encode method no longer throws.
  Source-Link: googleapis/googleapis@5e0dcb2

feat(utils): update encode to support unicode
  PiperOrigin-RevId: 345559182
  Source-Link: googleapis/googleapis@e5eef86
```

* Wes we should be careful about not underdefining things.
    * Ben: what if we enshrine this in our spec.
    * Wes: maybe it's enough to have this in the companion document.

```
feat: adds v4 UUID to crypto

This adds support for v4 UUIDs to the library.

* fix(utils): unicode no longer throws exception
  PiperOrigin-RevId: 345559154
  BREAKING-CHANGE: encode method no longer throws.
  Source-Link: googleapis/googleapis@5e0dcb2

[* ]feat(utils): update encode to support unicode
  PiperOrigin-RevId: 345559182
  Source-Link: googleapis/googleapis@e5eef86
  ```

* parser updates.
  * let's add support for "* ".
  * Reverts "feat: 93994994" <-- Ben finds this one wonky:
      * Wes/Ben don't love "Reverts", leave it to people's opinions.
      * Cedric: considers Revert commits a pain; what are we supposed to do when a breaking change
        was introduced in a Reverts commits; BitBucket has a different format.
  * Wes: one argument, if we had it in a spec we could perhaps try to aim for more standardization
    across vendors.
  * "(" <-- should be in tree:
      * CST good.
* Moving to v2 of Conventional Commits:
  * the "spec" spec, is on its own page, i.e.,
    * no tools listed.
    * no useful tips.
    * what is it?:
      * it's the formal grammar.
      * it's the very small number of symantic tokens we define:
        * "BREAKING-CHANGE", "!", feat, fix, feat(foo), fix(foo).
        * how footers work.
        * how body works.
  * pages:
    * really clear lead in on the main landing page.
    * the formal spec.
    * some best practices, e.g., here's what angular used.
    * tools, etc.
* Cedric is working on a CHANGELOG on the fly.
* Ben: what's the plan for the linter?
  * Cedric: might start as side project to see if it works as a CST.
  * Ben: I'm excited to see how this goes.
  * Wes: it will be very important for the linter that these errors are good.
    * Cedric: we're not quite there yet, but doesn't think it should be too hard.

Next Steps:

* thinking about v2 of spec, but don't make PR yet:
  * Wes: still haven't come up with concrete plan for monorepo stuff:
      * Let's talk about this topic more before we take a stab at writing a new one pager.
  * perhaps get one or two guests to join and give us feedback.
* Ben: Add "* " token to parser, and make sure that works for GitHub use case.
* Full CST: Cedric: not much availability next week, but available after.
* Website Work, in support of v2:
  * Wes: perhaps we can find someone at Netflix.

Meeting December 22nd 2020

**Attendance:**

* Cedric.
* Ben.
* Wes.

Agenda:

* Ben and Cedric sat down and started writing parser:
  * https://github.com/conventional-commits/parser
  * https://github.com/syntax-tree/unist <-- the tool kit.
  * Footer:\n<whitespace>more stuff.
  * Ben: there might still be some edge cases:
    * Cedric: there's sometimes post processing in other tools to deal with these edge cases.
    Ben: perhaps we could formalize some of the post processing steps:
      * Wes: we could define @ mentions.
    Ben: Example commit https://github.com/googleapis/google-cloud-go/pull/3391:
      * Wes: suggested as '---'.
    Cedric: we should probably support how GitHub is doing it, as a happy path.
* Next steps:
  * Ben: I'd love to get the initial grammar implemented.
    * Cedric: it won't be a pain if Ben finishes implmenting the grammar.
  * Cedric: Excited to do a Node refactor.
  * Everyone: chime on whether you like the node names, etc.
* IETF draft proposal vs., ECMA spec.
  * Ben: was suggesting we rethink the pros a bit.
  * https://www.ietf.org/standards/process/
* Adoption at Google.
* Wes: would be good to have Daniel join.



Meeting December 4th 2020

**Attendance:**

* Cedric.
* Ben.

* Proper AST for Conventionl Commits
    * https://github.com/byCedric/commit-ast-experiment
    * https://github.com/micromark/common-markup-state-machine
        * https://github.com/micromark/micromark
        * unified is the underlying parser.
    * Action Items:
        * Ben and Cedric going to play with the parsing tool chain linked above.
* Stream parsing broken in newer Node.js versions:
    * https://github.com/googleapis/release-please/pull/581
* no updates ECMA, haven't done anything for IETF
    * https://tools.ietf.org/html/rfc4122
    * https://www.ietf.org/standards/ids/guidelines/#1


Meeting November 6th 2020

**Attendance:**

* Wes Todd (@wesleytodd)
* Ben Coe (@bcoe)

* update re: ECMA process.
    * bencoe: maybe wait a couple weeks and send a follow on.
    * IETF: https://www.ietf.org/rfc/rfc2119.txt
    * _what do we do with the current licensing?_
* [bencoe] current state of ecosystem:
  * [14 open issues on conventional changelog].
  * [31 open issues on standard-version].
  * Wes:
      * the number of projects in the mono-repo.
      * Ben: think the conventional changelog is maybe sliced into a few too many pieces.
      * Wes: I'm used to dealing with lots of repos, find the mono-repo approach hard.
          * probably only using 3 or 4 directly.
          * ben: should we consider splitting out some of the most important libraries?
              * parser perhaps could sit on its own.
              * which bump could sit own its own.
              * We: not blocking progress just a hurtle.
  * supporting multiple scopes: https://github.com/conventional-commits/conventionalcommits.org/issues/302
      * feat(module,fs): 
      * cedric: common request for commit lint:
          * in theory a commit should only touch one part of the code.
          * module/errors <-- when I'm working on stack trace stuff.
              * module part of system where source maps are collected.
              * errors are where they're displayed.
          * Wes: what are the valid characters.
              * we need to define the valid characters.
              * wes: would be nice to collect all these ideas that would be breaking.
          * Ben: is the scope the component we're touching, or the action that the commit is performing.
              * Wes: I've sometimes seen both; unless we come up with recommendation.
              * Cedric: if we allow multiple full conventional commit messages:
                  * this could also also solve this same issue.
              * Wes: multiple headers could be a better solution because it solves both use cases.
          * _Plan a new major version eventually._
              * what the heck are our tokens for different things, what characters are valid?


----
chore(deps): synced with latest version of protos

this is a description of my normal conventional commit message.

feat(module): improved error output
  this is a description of this.
  
  hello world.
feat(errors): improved error output
 multiline
feat(errors): improved error output
 muliline
Refs: 20222
Signed-Of-By: @wes
----
https://git-scm.com/docs/git-interpret-trailers

Ben: aside Wes, can we please use your parser, and actually have a reference implementation for JavaScript.
  * Cedric: we would also love this for commit lint.
        
  * https://github.com/conventional-commits/conventionalcommits.org/issues/294
  * https://github.com/conventional-commits/conventionalcommits.org/issues/200
* https://github.com/conventional-commits/meta/pull/6

New Business:

* what do conventional commits look like in a mono-repo?

-----

* @bycedric, @wesleytodd: hash out parser implmentation?
    * bencoe@ would really love to pull this into conventional-changelog.
    * big strict about writing down aspects that are poorly specificed (what are strings? unicode?); TC39 spec defines unicode tokens that work with API.
    * Unified <-- when building parser.
        * https://unifiedjs.com/
    * https://commitist-7a7qx1zbs.vercel.app/ast/simple
* @bencoe: keep trying to poke and prod standards bodies.


Meeting October 9th 2020

**Attendance:**

* Ben Coe (@bcoe)
* Wes Todd (@wesleytodd)
* Damiano Petrungaro (@damianopetrungaro)
* Cedric van Putten (@bycedric)
* Guilherme Hermeto (@ghermeto)
* Zeke Sikelianos (@zeke)

## Agenda

* Introductions:
    * what interests you about conventional commits?
        * Ben Coe:
            * works at Google/wrote this while I worked at npm.
            * wrote the document initially at npm for our Enterprise product.
        * Wes Todd:
            * Works at Netflix.
            * Looking at the question of how we can improve the user story for libraries authors.
            * Trying to put their own release process into place.
            * has been working on a parser that's more formally to spec.
        * Damiano:
            * based in Italy.
            * writing code for about five years.
            * started looking into Conventional Commits when they were in a small startup:
                * and was asking the question of how we can improve workflow for a fast moving team.
                * combined advice on how to write good commits, with the convention.
                * knowing what broke something in production; aligned with atomic commits, so that it's easy to roll back.
            * Working for a unicorn startup "Message Bird".
                * trying to make conventional commits a thing here as well.
                * folks aren't adopting it yet on back end.
        * Guilherme:
            * Has been using conventional commits for a while now, as the Node.js platform uses it:
                * there is a deprecated too at Netflix that was reaching the end of its life (_became abandon ware_).
                * we've been talking for a while.
        * Cedric:
            * based in Amsterdam (NL), working on expo (a react native based technology).
            * was working at incubator with high velocity, which benefited from having more structure.
            * found conventional commits, and it helped development performance signficantly.
            * moved to atomic commits.
            * also introduced commitlint, which a few folks on commitlint (Hannes, Mario, Scott).
        * Zeke:
            * works at GitHub on the docs team; used to work with Ben at npm.
            * we just open sourced GitHub's docs.
            * somewhere along the line started embracing conventional commits.
                * what's challenging is it's hard to onboard new people to this idea.
                * paticularly it's difficult to help folks not release breaking changes appropriately.
                * decisions we make don't necessarily propagate.
            
* How do we manage issues on Conventional Commits.
    * Damiano: start with bi-monthly meeting, to start to burn down some issues.
        * probably we'd be okay to move down to a monthly after that.
    * something like a TSC?
        * Gui: good idea but might be problematic as we move to to ECMA; we might need to rethink it in a couple months.
        * It's up to eveyone on this call to de4cide if we're okay about this.
        * Wes: can you outline what is needed.
            * Gui: ECMA has a thing about not allowing just anyone on the governance call, we can't just accept a separate group of delegates.
                * Wes: would this be resolved by having a formal chartered document for how folks enter and leave.
                * Gui: we can't have an approval process.
        * Ben:
            * maybe call this a steering call?
                * you show up, you get a vote?
            * Gui: likes how we're doing it on the web severs framework team:
                * you can join to by submiting your PR to the list: put people's name in the "Collaborators" list if they ask to be.
            * Ben: how do we resolve a deadlock.
                * this is known to happen.
                * this can be a good reason: it allows us to see everyone's perspective and everyone's point of view.
                * in ECMA or Node, you can force vote; we shouldn't do this yet as it might specifically hurt our ability to move into ECMA.
            * Wes: leave it open for now, we'll try to reach consensus; anything that's left open:
                * self select, and we could potentialy have votes on a call.


* Topics:
    * Standardizing Conventional Commits in Standards Body:
        * benefits:
            * Tooling:
                * easier for tooling to know what they should build against.
                * e.g., it sounded like semantic release could be into it.
            * Adoption by other languages:
                * Gui: lots of push back from Java folks, as an example.
                * Damiano: this is something I see myself, the risk of introducing something that is too JavaScript specific.
                * Ben: JSON is a good example of an ECMA standard.
                * Adoption in general.
        * challenges:
            * IP <-- as Ben (not a lawyer) reads the license.
                * lawyers Ben talked to seemed to be slightly concerened.
            * Gui: Myles Borins wondered if we could perhaps try something different.
                * Zeke: is there prior art we could follow. JSON perhaps?
                    * maybe we only have 20 significant contributors?
            * Ben: non ECMA company contributors:
                * Gui: Open JS foundation has some contributors; I wonder if we could perhaps do something like this.
                    * domain experts could be permanent invited guests, e.g., Henry from Babel.
                * Gui: one wrinkle, is invited guests can't technically vote -- but we could create governance that says vote is the last resort for anything, or say that there is no vote.
            * Ben: how do folks feel about standardizing Conventional Commits?
                * Damiano: one concern, having the specification only used in some specific areas.
                    * we may just deep hole on some issues we already have.
                    * be careful not to bring just our own perspctive to the table.
                * Gui: standards body could make it easier to get other languages involved.

* Conclusions:
    * In two weeks, same meeting time?, let's bring some issues to it?
        * let's move an hour earlier; 9AM PDT.
        * add labels to issues for meeting.
        * Invite gregor.
        * Invite the person doing go library; try to do this each week.
        * Gui: we'll keep conversation going with ECMA.