feature: git integration

[ennioVisco]

It would be very cool to have a deeper integration with git to automatize the two following actions:

• add a pre-commit hook that refreshes the changelog
• add missing tags for the new entires of the changelog

The benefit for the developers would be the following:

1. Update the changelog automatically at any commit
2. Bridge the currently suggested release flow that requires manual git tags creation

[pawamoy]

Hi @ennioVisco, thanks for the feature request.

add a pre-commit hook that refreshes the changelog

If you mean to add a pre-commit YAML file to this repository, I am against it for various reasons.

add missing tags for the new entires of the changelog

I'm not sure to follow. git-changelog builds changelog entries by looking at Git tags in your history, not the other way around 🤔 Could you elaborate?

---

Update the changelog automatically at any commit

I believe it's already possible to setup a post-commit hook (or whatever the hook name is) that runs git-changelog to update the changelog in-place, without auto-bumping the latest tag, so that you get an auto-updated "Unreleased" entry in your changelog 🙂

Bridge the currently suggested release flow that requires manual git tags creation

Same as above, I'll need you to elaborate on your use-case to make sure I understand what you mean 🙂

[ennioVisco]

add a pre-commit hook that refreshes the changelog

If you mean to add a pre-commit YAML file to this repository, I am against it for various reasons.

Could you elaborate a bit more? I'm not sure what you don't like, I'll try to clarify my view:
I think it would be nice to have a setting in the git-changelog package that allows to install a pre-commit hook in .git/hooks that has more or less the following content

#!/bin/sh
# Example pre-commit hook script
echo "Running pre-commit hook..."
# Add commands you want to run before commit here
# For example, running via poetry:
poetry run git-changelog

This of course makes sense if the configuration is loaded from a file in the usual documented ways.
AFAIK there is no need to use the pre-commit pypi package or the yaml-based syntax it provides.

add missing tags for the new entires of the changelog

I'm not sure to follow. git-changelog builds changelog entries by looking at Git tags in your history, not the other way around 🤔 Could you elaborate?

Does it? I was using it without having any tags in the repo and it was able to compute the next version (in my case 0.1.0), based on the conventional commit standard and the bump settings... AFAIK it did not create a new git tag for the new version, nor I found any setting to do that.

[pawamoy]

Thanks for the clarifications.

I was indeed speaking of the pre-commit Python tool (they should really have used another name, it requires clarification most of the time).

If it's just about Git hooks, I don't have anything against them, but I also don't think it's worth having (and maintaining) dedicated code in git-changelog just to setup empty hooks. This is easily done with other tools, maintenance tasks, or project templates.

Does it?

You're right, git-changelog is able to infer the next tag based on previous ones and commit messages. I was confused because you mentioned "new entries" (plural). The issue with auto-tagging is that it creates kind of a chicken and egg problem, at least with my own workflow. My workflow is:

• update the changelog (let it auto-bump, or provide specific version)
• let say new version is 3.4.5
• review its contents, update if needed
• commit changelog's modifications
• tag 3.4.5

If we were to auto-tag right after modifying the changelog, the changelog entry would actually not be contained in the newly tagged version. For this we would also have to stage the changelog's modifications and commit them. For the staging part, we would just stage the changelog (I suppose this would be OK in 95% cases). For the commit part, we could have an additional option to specify the commit message when committing the changelog. But... what if other files are already staged when we commit?

Well, we're between consenting adults, so I suppose it's OK to provide options to also tag when updating the changelog, and tell users to be careful with their workflow. Therefore I'm willing to consider PRs for this, if you'd like to contribute 🙂

In short, we would:

• add an option to instruct git-changelog to also tag when updating the changelog with a valid (not unreleased) version
• add an option to specify a commit message format with a placeholder for the version
• update the logic to use this option: after the changelog is updated, stage it, and commit it with the configured commit message, replacing the placeholder with the new version, then tag with the new version

WDYT?

[ennioVisco]

Thanks a lot, your comments make a lot of sense.

My workflow is:

• update the changelog (let it auto-bump, or provide specific version)
• let say new version is 3.4.5
• review its contents, update if needed
• commit changelog's modifications
• tag 3.4.5

Your workflow is quite typical and actually the concerns you have with auto-tagging are legitimate.
The only way I see to cleanly avoid having to mess with staged files and changelog is to do that in a pre-commit hook.
Basically, when you commit the changelog's modification, the changelog should be updated, and the tag should be created.
I'm also not a huge fan of git hooks, but what alternative option do you see to using them without interfering with the dev flow?

[pawamoy]

Thanks.

The only way I see to cleanly avoid having to mess with staged files and changelog is to do that in a pre-commit hook.

That's unclear to me. A pre-commit hook verifies things before a commit is made, right?

Basically, when you commit the changelog's modification, the changelog should be updated, and the tag should be created.

Even more unclear to me 😅 You commit the changelog and then the changelog is updated (again)?

I'm also not a huge fan of git hooks, but what alternative option do you see to using them without interfering with the dev flow?

If you want to use Git hooks, use Git hooks ☺️ It's the user's responsibility to integrate them in their own workflow.

---

I think we mostly agree. If you tell me you agree with my previous, last paragraph ("in short..."), we can proceed 🙂

[ennioVisco]

In short, we would:

• add an option to instruct git-changelog to also tag when updating the changelog with a valid (not unreleased) version
• add an option to specify a commit message format with a placeholder for the version
• update the logic to use this option: after the changelog is updated, stage it, and commit it with the configured commit message, replacing the placeholder with the new version, then tag with the new version

Here is the thing, this is one of the two options, but I feel this would be a bit brittle:

• what if they want to control differently a single changelog commit?
• what if they want to avoid triggering new CI workflows
• etc.

I believe this option would allow for more flexibility and less intrusive DX:

• add a boolean option like add-git-hook that tells whether the checks should be done at commit time
• add a boolean option like auto-tag that tells whether the changelog generation should also trigger the tag creation

The git hook can be something very minimal, like the following:

#!/bin/sh

# Execute auto-changelog (not sure how to pick the correct runtime here, so I write mine with poetry)
poetry run auto-changelog

# Add the generated file to the staging area
git add Changelog.md # The name should come from the config

# Add the missing tag (this could actually happen in the auto-changelog script directly)
git tag -a vx.y.z -m "vx.y.z"

# Exit with 0 to indicate success
exit 0

Concerning your question:

Even more unclear to me 😅 You commit the changelog and then the changelog is updated (again)?

That's the thing, the pre-commit happens while the user generated the commit, the flow is more or less the following:

• you type git commit -m "hello" after having staged a few files
• the pre-commit hook is triggered, which updates the staged files
• the commit hash is generated and returned to the user.

I hope this clarifies my view.

[pawamoy]

Thank you for your patience ☺️

add a boolean option like add-git-hook that tells whether the checks should be done at commit time

Hmm, I'm having trouble understanding this suggestion. A boolean option sounds like something persistent (in config) or ephemeral (CLI flag). But:

• if the option is added to the config, it's used only once, to write the Git hook? Surely, removing the option would not mean that the hook is removed?
• if the option is passed as a CLI flag, it means we have to write the hook, then somehow wait for the user to commit (??), and finally remove the hook?

I'm sorry but I don't see how this could work. Either git-changelog runs Git commands while its process is running, either it doesn't. And I don't think providing a command to setup a Git hook is a good idea, if this is what you're suggesting: these hooks are terribly subjective and there's no way we can provide a generic hook that satisfies everyone. A few examples that come to mind:

• users will want something else than a sh script (Bash, Powershell, Python, whatever)
• users will want something else than Poetry (PDM, make, venv, nothing, whatever)
• users will want to sign tags, or pass different options to the various Git commands

By the way, there's an issue with the hook above (unless I'm missing something): you stage the changelog, but then tag before committing. That means your tag will be attached to the previous commit, which does not contain the changelog modifications.

(also not sure what auto-changelog is in your hook)

---

add a boolean option like auto-tag that tells whether the changelog generation should also trigger the tag creation

Yes, this makes sense to me. But as mentioned above, this means we have to also stage and commit before tagging, which you said is brittle and intrusive 🤔 (which I agree with)