rome / tools

Unified developer tools for JavaScript, TypeScript, and the web
https://docs.rome.tools/
MIT License
23.76k stars 663 forks source link

Change log generation #865

Closed bitpshr closed 4 years ago

bitpshr commented 4 years ago

As we prepare for an initial release, it's important that Rome consistently produces accurate change logs that downstream consumers can safely rely on. I feel that a change log generation solution that removes the human element such as standard-version provides the level of automation and accuracy required by a mission-critical project like Rome. This tool (and many other alternatives) generate a well-formatted CHANGELOG.md based on a commit history. This would work especially well for Rome since we already squash commits, meaning each commit on main mostly corresponds to a holistic body of work. In my mind, a generated change log would coexist with hand-curated blogs that provide greater context around releases and their changes.

Automating change logs using standard-version would involve the following:

  1. Use conventional-commit messages. Note that many of us already do this, and CI can verify this.
  2. Run standard-version to cut a release. Under the hood, this will:
    1. Determine the correct release version based on commits since the last release. For example, if all commits are fix commits, a patch will be created. If there is a feat commit, a minor release will be cut, etc.
    2. Create a commit with a generated CHANGELOG.md and a bumped version.
    3. Create a new tag.

Alternatively, if Rome requires more granular releasing and tagging, it's possible to use conventional-changelog directly, which is what standard-version uses internally. This would essentially skip all releasing and tagging automation described above.

ematipico commented 4 years ago

I like conventional commits: https://www.conventionalcommits.org/en/v1.0.0/

Which is basically implemented by standard-version.

We could create our own parser (codec) to align to their specifications and install a git hook to verify the commit message. I wonder if we can do this only for anyone that can contribute, maybe we don't want to expose this internal feature to consumers.

bitpshr commented 4 years ago

@ematipico to clarify, I was suggesting using either standard-version or conventional-changelog (both of which rely on the conventional-commit specification you linked.) There would't be any need to create and maintain our own parser; there's already readily-available GitHub Actions (and local precommit hooks) to lint and to verify commit messages per the conventional-commit specification, so setup for Rome would be straightforward. I'd be happy to take care of it.

bitpshr commented 4 years ago

I'll work up a PR today that includes necessary tooling updates so we can see how this would look in practice.