Explicit Changelog Standard

[MichaelHirn]

I am not sure if Clog or Clog-CLI currently aggrees on an explicit standard for the change logs it generates, but I think that would have a tremendious impact on the Rust crate ecosystem.

Many points are pointed out in this post. But to summarize a standard on how a change log should look (as well as the file name e.g. CHANGELOG.md), would lead to a parseable crate ecosystem and would help spreading best practices faster.

A lot of work on standarizing was already done by http://keepachangelog.com/ and https://github.com/tech-angels/vandamme/ . Basing Clog on such a standard would bring the Rust crate system forward. Happy to discuss thoughts on this :)

An agreed standard would help to resolve some minor issues I would propose such as:

• Referencing Issues in the changelog (e.g. CLOSED)
• Referencing the authors
• Adding semantic versioning support
• And discussing the overall structure/outline. KeepAChangelog, proposeses e.g. also deprecation and security notes

[vyp]

In general, I think the following is the current inspiration: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit. And also see the google document linked there.

Edit: As in, that's the git commit guidelines, but see https://github.com/angular/angular.js/blob/master/CHANGELOG.md for an example format of what it can produce.

[kbknapp]

@MichaelHirn I agree it would be great to get to a parsable state, and some sort of standard but at the same time I wouldn't want to deny anyone's ability to deviate from that standard if they willing choose to do so.

I believe clog already does two of the things on your list, and the third isn't really something clog proper can do, but some docs linked to or provided by clog would be great. Here's your list, as I see it

• Referencing Issues in the changelog (e.g. CLOSED) (This is done by placing Closes #<NUM> anywhere in the commit message, also supports things like Resolves, Fixes, etc.)
• Referencing authors
• Semantic versioning support (I would say this also complete, unless you mean clog automatically detecting breaking in semantic versioning, because different projects have different meanings of what "breakage" is, generally I believe it's best if the developer manually sets version numbers...which I'm not sure should be clogs job and could be a fairly huge undertaking. Having said that, if someone submits a PR that adds this, I wouldn't be against it per se. Now clog does support bumping version numbers easily via --patch | --minor | --major flags)
• And discussing the overall structure/outline. KeepAChangelog, proposeses e.g. also deprecation and security notes (Deprecation notes could be added in the same manner as Closes, but the rest is a docs issue IMO)

Please correct me if I'm mistaken on any of these!

[MichaelHirn]

@vyp Thank you for the quick reply. I agree, the Angular CONTRIBUTING.md seems to be the standard and we used it as the blueprint for our CONTRIBUTING.md as well. But we made two small but principal changes - which, now in hindsight, might not have been super smart. <type>/<scope>: <subject> instead of <type>(<scope>): <subject> and agreeing in the footer on:

BREAKING CHANGE: [specify what is breaking]

{ REFERENCE, CLOSE, FIX } #Issue

I think we thought that Angular's commit message format is ambiguous on purpose and leaves the exact implementation to the respective project. GitCop reinforced our thought's by being flexible on many details.

Which leads us to the tradeoff @kbknapp mentioned, between standardized, parsable and flexible, individual change logs.

One solution might be to be specific about the high-level structure of a commit message (e.g. header, body, footer), referencing closed issues, etc. but leaving the details of the commit message format to be configured. E.g. what we did, was specifying a custom regex for the header, maybe something similar could be done for issue referencing. (e.g. CLOSE instead of Closes, etc.), which could be configured via the .clog.toml. Default would be the Angular standard. Would a PR for this be welcomed?

Also, big thanks for the list. I wasn't aware, that many of the things are already implemented.

Clarifying "adding semantic versioning support", because I was really inaccurate an ambiguous about it. I meant some sort of flag, that says "we are following semantic versioning", which adds a note to the CHANGELOG.md. Something that is proposed at KeepAChanglog. Example can be found here.

[epage]

RE Authors

This is something I'd appreciate as a way to help call out my contributors.

Came here looking for an issue regarding this after seeing this reddit post and how nom thanks people.