[cargo-smart-release] Fully support conventional commit?

[jcornaz]

Hi,

The cargo-smart-release readme tells to follow conventional commits

Therefore, I would personally expect the changelog generator to fully support the convention:

• Include the scope in the generated changelog
• Include the BREAKING CHANGE footers in the generated changelog
• Only include feat, fix, perf and docs in the generated changelog, but not chore, refactor, ci, build and test
  • Potentially let the user configure this in a config file
  • That's because every commit must be prefixed. But we still need a way to commit changes that should not appear in the changelog (like when we adjust the changelog before releasing)

What do you think?

[Byron]

Thanks for your interest!

Therefore, I would personally expect the changelog generator to fully support the convention:

To clarify, conventional commits is merely a vessel to have a format to signal whether or not something should go into the changelog, as opposed to cargo-smart-release being a vessel to enforce conventional commits.
I hope this reframes expectations a little.

Include the scope in the generated changelog

Even though it's not the same, it naturally scopes messages by crate. Adding the conventional scope to the mix might be a possibility but it's not planned.

Include the BREAKING CHANGE footers in the generated changelog

I don't actually know what it currently does with those.

Only include feat, fix, perf and docs in the generated changelog, but not chore, refactor, ci, build and test

Indeed, this reflects my needs only (as most of the tool) and that could be a configurable.

That's because every commit must be prefixed. But we still need a way to commit changes that should not appear in the changelog (like when we adjust the changelog before releasing)

Currently removing commits from the changelog or re-arranging them is somewhat cumbersome and I can't imagine that to be useful for a bigger amount of commits. This is why conventional commits are intended to be used sparingly to lift only those messages into the changelog.

cargo-smart-release in its current form is clearly not very suitable for projects that use conventional commit messages everywhere and I don't think this will ever be feasible unless most of the messages it would put into the changelog are supposed to be kept. Most of my commit messages definitely aren't suitable for that which is reflected in the tools preference.

Maybe these ramblings above can help to plot a path forward to making it suitable for conventional-commit-only projects, contributions in that regard are welcome as long as the defaults don't change.

[jcornaz]

Thanks for your reply :-)

Even though it's not the same, it naturally scopes messages by crate. Adding the conventional scope to the mix might be a possibility but it's not planned.

Okay, I didn't know that. I personally don't have a mono-repo but a single crate per repo and I use the conventional-commit scope when the change relates to a specific cargo feature flag. Anyway, this is the least important point to me as I can easily add them myself to the generated changelog.

Include the BREAKING CHANGE footers in the generated changelog

I don't actually know what it currently does with those.

As far as my experimentations go, it is completely ignored and does not appear in the changelog at all.

Currently removing commits from the changelog or re-arranging them is somewhat cumbersome and I can't imagine that to be useful for a bigger amount of commits. This is why conventional commits are intended to be used sparingly to lift only those messages into the changelog.

cargo-smart-release in its current form is clearly not very suitable for projects that use conventional commit messages everywhere and I don't think this will ever be feasible unless most of the messages it would put into the changelog are supposed to be kept. Most of my commit messages definitely aren't suitable for that which is reflected in the tools preference.

To me, it looks like we have the same problem but don't solve it the same way. I don't want every single commit to appear in the changelog either. In particular, I think the conventional-commit types refactor, chore, build, ci and test are of no interest to the user. Hence my request to be able to exclude them from the generated changelog.

Maybe these ramblings above can help to plot a path forward to making it suitable for conventional-commit-only projects, contributions in that regard are welcome as long as the defaults don't change.

I guess there could be an optional config file. If the file is absent, it would behave as of today. If the config file is present, its content would be taken into consideration. Here is an example of what the config file could look like:

.smart-release.yml:

changelog:
  without: [commit-details, commit-statistics, clippy]
  include:
    types: [feat, fix, docs, perf]

[Byron]

For configuration, there is crates that are able to put a configuration file layer on top of an existing clap app. That way, each flag in the clap app can be represented by a value in a toml file and it sorts out defaults that way.

This way, everything that can be configured in file can also be set in the CLI when invoking the program. If anyone were to implement this, I recommend starting with a command-line flag for handling the headline filter. Configuration files could then be tacked separately, knowing that it should be sorted by a crate.

[jcornaz]

Ok. I don't mind if those options are also available via CLI flags. But I think support for config file should be added first.

Otherwise, it is too error prone IMO to have to write something like that every single time we release:

cargo smart-release --changelog-without commit-details --changelog-without commit-statistics --changelog-without clippy --changelog-without clippy --changelog-include feat --changelog-include fix --changelog-include docs --changelog-include perf -u -e

[Byron]

These features are independent of each other and are both valuable in their own right, so who am I to dictate an ordering. Any contribution in that regard is welcome.

[jcornaz]

Ok. Fair enough. I may try to find the time for this.

Can you expand more on the crate you would like to use and the approach you have in mind? I saw clap_conf but it is not immediately clear to me how to combine it with a CLI that uses clap with derive. I am also wondering, how do you want to unify the two CLI (e.g. --changelog-without in smart-release vs --without in changelog). I assume you don't want two config files?

I am also wondering, are you not bothered by the idea of coupling the config-file deserialization tech to the CLI option parsing tech? What if clap publishes a new major version or if you want to swap clap for a different solution?

Personally, I think it would be simpler to use serde to deserialize the config file into a struct instance. Eventually, that struct may be the CLI option struct used for clap, without the need for a technology that directly knows about clap.

[Byron]

It's possible to obtain the clap::App from any derived command via <Args as clap::CommandFactory>::command(), and from there I'd hope clap_conf can work as intended. However, I think argfile is more popular and the recommended crate for this as per claps own documentation (see 'Related Projects') - it's also made by Ed Page, who is a trusted author for me. argfile should integrate perfectly with the clap_derive as well since it provides arguments to pass to the matcher.

I assume you don't want two config files?

Two config files are fine to start with - they are separate programs with mutually incompatible settings, potentially. If config settings should be shared, I think this would have to be implemented somehow differently, with 'somehow' being unclear to me at this point.

I am also wondering, are you not bothered by the idea of coupling the config-file deserialization tech to the CLI option parsing tech? What if clap publishes a new major version or if you want to swap clap for a different solution?

cargo smart-release is a tool to do a specific job and ideally it costs nothing to maintain. Cheap is good, so using off the shelf components of authors I trust is the way to go to get results fast. clap is here to stay - I had made painful experiences already trying to use argh and ultimately wasted quite some time on something that didn't pan out. clap is good :D.

Personally, I think it would be simpler to use serde to deserialize the config file into a struct instance. Eventually, that struct may be the CLI option struct used for clap, without the need for a technology that directly knows about clap.

I'd be happy with that as well - that way this file would be specific to the way the changelog looks and sharing between the two programs is should be easier. argfile can be used at a later time for everything else if there is demand. This would mean that the 'CLI-overrides-config' policy would have to be implemented by hand though, which still seems feasible.

[jcornaz]

Ok. Thanks for the precisions. I'll see if I can find the time to do something.

[...] are you not bothered by the idea of coupling the config-file deserialization tech to the CLI option parsing tech? [...]

cargo smart-release is a tool to do a specific job and ideally it costs nothing to maintain. Cheap is good, so using off the shelf components of authors I trust is the way to go to get results fast. clap is here to stay - I had made painful experiences already trying to use argh and ultimately wasted quite some time on something that didn't pan out. clap is good :D.

I understand your position, and I am not trying to challenge it, but I would like to clarify what I meant.

I do think clap is the best solution available at the moment, and I think it should be used. My concern is not about using clap, but about coupling two different concerns together, increasing the maintenance cost. Even if clap remains your favorite crate for the job, in case of a new major version of clap, if the other dependency depends on clap, you would have to wait until it supports the new major version of clap.

It is anyway a concern about maintenance, so I don't have any personal stakes in this. I would follow whatever you think leads to the cheapest maintenance costs. And the crate argfile does not depend on clap, so my concern is addressed already :-p

[Byron]

Ok. Thanks for the precisions. I'll see if I can find the time to do something.

That's great, I am looking forward to it. Thank you!

It is anyway a concern about maintenance, so I don't have any personal stakes in this. I would follow whatever you think leads to the cheapest maintenance costs. And the crate argfile does not depend on clap, so my concern is addressed already :-p

Sounds like a win-win :)! Thanks for the clarification! I admit that I do have a bias towards Ed Page who just tends to deliver supreme quality and responds to requests very quickly, so it's a safe bet to me.