clog-tool / clog-cli

Generate beautiful changelogs from your Git commit history
MIT License
856 stars 43 forks source link

Explicit Changelog Standard #81

Open MichaelHirn opened 8 years ago

MichaelHirn commented 8 years ago

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:

vyp commented 8 years ago

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 commented 8 years ago

@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

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

MichaelHirn commented 8 years ago

@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 commented 6 years ago

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.