search

celestiaorg / smt

A Go library that implements a Sparse Merkle tree for a key-value map.
https://godoc.org/github.com/celestiaorg/smt
MIT License
138 stars 53 forks source link

Create CHANGELOG.md, CHANGELOG-PENDING.md, and corresponding GH action #66

Closed jbowen93 closed 2 years ago

jbowen93 commented 2 years ago

Create CHANGELOG.md and CHANGELOG-PENDING.md files and a corresponding "Pending Changelog Checker" action that runs on all PRs to the master branch.

This check will only pass if the CHANGELOG-PENDING.md file is updated in the PR.

This check can be bypassed by labeling the PR with no_changelog

Resolves #65

musalbas commented 2 years ago

What's the rationale of this?

liamsi commented 2 years ago

What's the rationale of this?

In order to have a changelog moving forward, this action checks that on each PR the pending changlog is updated. Unless it is flagged the label no_changelog. That ensures that PRs will be accompanied with a changelog entry and that the developer thinks about categorizing the PR properly. This ensure a minimal viable changelog. Ideally, on each release the maintainer does not just simply copy over the the list from pending into the actual changelog but also summarizes the changes properly. But everything is better than not having a changelog at all. https://github.com/celestiaorg/smt/issues/19

musalbas commented 2 years ago

This feels like extra unnecessary bureaucracy and loop-jumping, when I thought the whole point of git squash merging is to have a clean changelog. However, I won't veto merging this.

adlerjohn commented 2 years ago

the whole point of git squash merging is to have a clean changelog

I think that's orthogonal? Squash and merge gives a clean git commit history, yes, but that's not a changelog. This PR adds a CI workflow to automatically produce a changelog between release versions, consumable by an end user.

musalbas commented 2 years ago

Git commits should be changelog entries. What else are they for, then? The standard practice in most projects I've seen, including Linux, Bitcoin, and Ubuntu packages, is to use the git commit history as the changelog. Sure, for user-facing software, it might make sense to have a smaller changelog with only the main bits, but this is a developer-facing data structure package.

liamsi commented 2 years ago

This PR adds a CI workflow to automatically produce a changelog between release versions, consumable by an end user.

Not really, this PR does what it say in the opening comment, it adds a checker that:

This check will only pass if the CHANGELOG-PENDING.md file is updated in the PR.

Git commits should be changelog entries.

Sure, I don't mind this here. But I still think it's worth thinking ahead/deciding on each merge if this change was a breaking one, if it adds a new feature, fixes a bug etc. and have that reflected in the changelog instead of just a list of commits without any further info (btw I wanted this since a long time: https://github.com/celestiaorg/smt/issues/19).

Sure, this could be automated with proper labels and a script but I don't think it hurts asking to add one line in the changelog including a link to the PR/issue.

P.S. Bitcoin's changelog is way more sophisticated than just a list of commits: https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.20.0.md or https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.11.0.md And follows a similar approach of using two file to track changes before a release: https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes.md

jbowen93 commented 2 years ago

FYI someone else has to merge this.