search

stapi-spec / stapi-fastapi

Spatio Temporal Asset Tasking with FastAPI
MIT License
12 stars 4 forks source link

CHANGELOG automation #89

Open jkeifer opened 3 weeks ago

jkeifer commented 3 weeks ago

Spinning this out of the discussion on #84 to ensure this topic gets proper consideration/dedicated discussion. Per @c-wygoda:

how about using conventional commits with commitizen for message linting (as a pre-commit hook), CHANGELOG automation and version bumping?

it's a bit awkward at first sometimes, but in 90% of commits it's using an feat: or fix: prefix only.

and

I would say than an CHANGELOG curation is a sign of missing automation at best, inefficient commit messages at worst.

jkeifer commented 3 weeks ago

My personal feeling is that the CHANGELOG definitely must be manually curated as commit messages are not adequate for capturing all the information users care about between releases. Things like breaking change notes, how to migrate, links to the relevant issues and PRs.

Perhaps the problem is one of terminology: if we are talking truly and specifically about a "change log", then I suppose I'm in agreement. In practice, however, git serves as a "change log" via the commit history, and duplicating that into a document within the repo I would argue is effectively pointless. Thus we end up using the conventional name of CHANGELOG to actually represent what might be better conceptually understood as "release notes".

I think that keep a changelog does a great job of capturing my philosophy around what a changelog is, what should be in it, and how it should be managed.

I'd still like to get other voices into this discussion so we can see if we have any consensus one way or the other. I'm open to this idea: I might feel pretty strongly that we can't just automate this concern away, but I want to ensure we have a space for dialog and discussion around it so others can provide their feedback even if it doesn't align with my viewpoint.

c-wygoda commented 3 weeks ago

now I'm thinking we're discussing changelog vs release notes maybe? and for the latter I'm seeing how one would need to manually condense the "highlights" and suggested actions, probably from the changelog.