Support conventionalcommits syntax

[maelle]

Cf https://github.com/conventional-commits/conventionalcommits.org + https://github.com/cynkra/fledge/issues/20#issuecomment-929834045 by @rtaph

[rtaph]

Willing to help implement this if needed.

[maelle]

@krlmlr if we were to implement this, a challenge would be to know what syntax a package uses (default or conventional commits). How about storing the info in a DESCRIPTION field like testthat edition?

[maelle]

Not directly related to the feature, I wonder whether conventional commit users often use pre-commits to check their commit messages (not that it'd work for merging PRs anyway).

[maelle]

https://github.com/zeke/semantic-pull-requests

[maelle]

https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests

[krlmlr]

Installed the probot for fledge.

[maelle]

Awesome! I'm also writing this down for the docs, so that we can give users an idea of how to set up their repo for a successful conventional commits usage.

[krlmlr]

The GH docs mean that we don't need to interact with the API for squash commits, because the PR title can be copied automatically.

[maelle]

Yep.

And it also relates to the discussion around protected branches but I'll stop going into :rabbit: :hole: and concentrate on the syntax now. :grin:

[krlmlr]

@rtaph: Thanks, your input would be very valuable!

[maelle]

In the changelog

• should types become h2
• should trailers (e.g. Reviewed-by) become something between parentheses.

[maelle]

And should the body be compacted into one single paragraph, or is it fine to have news item be several paragraphs :thinking:

[krlmlr]

Types become h2, but only during releases. For now let's keep it simple, and leave out the trailers. We would also ignore the body if it's not prefixed with a <type>: .

[maelle]

The body will never be prefixed by a type, only the description is.

I've just realized that at the moment when using a bullet you can have several items per commit message e.g.

- Adds bla
- Adds blop

which with conventional commit would not work.

[maelle]

Reg h2. For common types abbreviations it is easy enough to translate.

For custom ones later we might want to let users store a dictionary somewhere.

[krlmlr]

I'd suggest a simpler approach for now: treat header and body the same, just like fledge is doing today, only allow accepting type prefixes in addition to bullets.

[maelle]

to recognize the first trailer one needs info on the trailer line (token: value, token # value) and on the line before (which has to be a blank line). Now I'm wishing the git log were transformed to XML :grin:

[maelle]

(saw the answer before a bit late, sorry)

[maelle]

Needed for full support

Docs of set up for successful conventional commit usage (pre-commit, or PR stuff + protected branch)

• [x] Fledge to accept pre-commit messages as newsworthy
• [ ] Full parsing, grouping, sorting of the conventional commits
• [ ] Hook the parsing into pre_release() which guessing.
• [ ] Document that conventional commits are supported. Actually, put it front and center as it'd be an important feature.
• [ ] Add the words "conventional commits" to the DESCRIPTION file.

The PR #188 only tackles the second point.

[krlmlr]

Only the second point seems good for a start. Please ping me for review.

[maelle]

Just parking some notes about parsing

• translating the types into actual words
• translating the different BREAKING CHANGES markers (the breaking change trailers, the "!").
• grouping the h2 together (i.e. all features together for instance)
• doing the same with the scopes
• ordering the h2 according to a given order (probably features first, and within h2, breaking changes first)

The two latter items would be useful for a function related https://github.com/cynkra/fledge/issues/147 to "merge" versions before a release.

[maelle]

I'm quickly looking at https://github.com/conventional-changelog/standard-version just because fledge should probably mimick what's done there.

[maelle]

https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.1.0/README.md

[krlmlr]

How different is "conventional changelog" from our established NEWS.md format?

[maelle]

Not that different https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/CHANGELOG.md but the differences are important because of how pkgdown uses NEWS.md

What I think needs to be mimicked is the configuration (:innocent: ) of e.g. what abbreviations mean, of what types are hidden in the changelog.

[maelle]

One aspect of conventional commits that's hard to reconcile with e.g. https://style.tidyverse.org/news.html is that breaking changes are not a type, they qualify any type.

[maelle]

Where could users store abbreviations for their conventional commits usage. :thinking: https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.1.0/README.md#types=

.fledge.json?

[krlmlr]

We could repeat breaking changes in their own header, and leave it to the user to reconcile.

Where do other conventional-commit users store their definitions?

[maelle]

Good idea to repeat the breaking changes!

Where do other conventional-commit users store their definitions?

Apparently in https://github.com/conventional-changelog/standard-version#configuration=

.versionrc.json or .versionrc sound ok although the name might be confusing to fledge users?

[krlmlr]

We could do fledge::edit_conventional_config() ?

The release-please project looks great, I wonder if we can offload some of the work we're doing there.

All of this seems out of scope for now.

[maelle]

Another particularly interesting aspect of that project is the use of footers for indicating several changes in a commit https://github.com/googleapis/release-please#what-if-my-pr-contains-multiple-fixes-or-features=

[krlmlr]

Let's wrap up here for now and list all remaining work in new separate issues, perhaps with a specific tag? CC support is very much experimental for now. Perhaps some things will be easier with #331, and we might want to rethink the whole approach.

[maelle]

https://github.com/cynkra/fledge/issues?q=is%3Aopen+label%3A%22conventional+commits+%3Asparkles%3A%22+sort%3Aupdated-desc :heavy_check_mark: (@rtaph please feel free to comment in any of those, thanks again for the feature request :pray: )

[github-actions[bot]]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue and link to this old issue if necessary.