# 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.