Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use git cliff to generate changelogs #4302

Open
max-sixty opened this issue Mar 4, 2024 · 7 comments
Open

Use git cliff to generate changelogs #4302

max-sixty opened this issue Mar 4, 2024 · 7 comments

Comments

@max-sixty
Copy link
Member

What's up?

The new version of git cliff supports GitHub handles. So we could use it to generate changelogs.

If anyone is up for a dev-ops PR, this would be great. The goal would be to generate something similar to our current changelog, using the prefix of our commits to group them (which git-cliff supports)

@richb-hanover
Copy link
Contributor

@max-sixty I'm quite content with the current format and information contained in our current Changelog. Even though we have to manually curate the comments, they provide a good description of the project's progress.

My primary concern is that an automatically-generated file will hide the actual information in a flurry of commit messages. Could you point me to a sample git cliff changelog? (This project or some other project would be useful.) Thanks.

@max-sixty
Copy link
Member Author

Definitely worth checking out some of the git cliff outputs and seeing what we thinks looks best. I am keen to reduce the burden of releasing as much as possible, so unless someone wants to own maintaining the changelog, automation should win out...

@richb-hanover
Copy link
Contributor

In seeking a sample git-cliff output, I went to their repo:

Changelog: https://github.com/orhun/git-cliff/blob/main/CHANGELOG.md
Commit History: https://github.com/orhun/git-cliff/commits/main/

It's definitely a nicely formatted file. The Issue number and commit hash is useful. And if I squint, I can see how it lines up with the commit history.

I do wonder how fussy git-cliff is about the tagging and labeling of commits. Do we wind up trading a headache for an upset stomach? (Simplifying the creation of the Changelog while enforcing a bunch of strict rules for the commit messages?)

As for the current PRQL Changelog, I really like the narrative format. It helps the reader understand if it's a major release, a little one, just a bug-fix, etc. It also lets the reader get more context about what we're thinking.

And the current Changelog format allows people to make incremental entries that describe interesting changes they've made, while eliding the little stuff.

I suppose there's a hybrid path: retain the narrative form, while letting git-cliff generate the fussy PR/Issue/commit lines that can be inserted.

I'm not sure any of this helps make the decision. But thanks for listening.

@max-sixty
Copy link
Member Author

I still think we can have a few lines at the top of each release. It's normally me doing the releases and I'm happy to do that.

The main thing it can automate is the listing of the changes — which no one seems to love doing...

@richb-hanover
Copy link
Contributor

The main thing it can automate is the listing of the changes — which no one seems to love doing...

Oh, yeah. I totally agree that part is a pain. That's kind of what I was thinking when I suggested a hybrid model: hoover up the git-clif changes (maybe even curating those (how does it handle/minimize multiple commits that fix typos, etc?)) and fitting them into the narrative.

This still requires some hand-work, but automates the painful parts.

@snth
Copy link
Member

snth commented Mar 5, 2024

Thank you for those links @richb-hanover .

I was going to ask if there is a way to display PR/Issue numbers rather than commit hashes and after a quick look around I see that it uses a templating engine (similar to Jinja2 syntax) and that should be easily configurable. In fact based on this snippet, you could easily do the opposite of that and only include only specific commits, PRs, etc...

Sounds good to me!

@richb-hanover
Copy link
Contributor

In case it wasn't clear from my earlier note: Yes, let's try this. Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants