Automatic pushes to update readme help output?

[katrinafyi]

In #2047, I added a make readme command which runs a python script to update the readme with the latest --help output. This simplifies the workflow a little but when help options are updated, since you don't have to copy paste anymore.

The workflow could be simplified even more with an automatic Github action that runs make readme and pushes the result to PR branches. This would be very similar to the current "update TOC" workflow.

This is a ticket to think about doing that eventually (or decide not to, in case it might be too disruptive).

[...] Maybe there could be a ci task that generates the readme and pushes it, then we don't need the unit test and the developer doesn't have to think about it at all.

Originally posted by @katrinafyi in #2047 (comment)

[thomas-zahner]

I like the idea 👍

[cristiklein]

Would a pre-commit hook make sense? 🤔 This way, the contributor would be encouraged to update the README in the same commit as changing the command-line. Of course, the CI would need to run pre-commit run --all to catch those contributions which didn't have pre-commit installed.

[thomas-zahner]

Personally I like the current approach we use with updating the table of contents in the README.md. This way users don't have to install pre commit hooks and we can't forget about it, as it's performed automatically.

Or isn't it necessary for users to install pre commit hooks themselves? I don't think we have any pre commit hooks in this repository at the moment.

[katrinafyi]

If there were a pre-commit hook, I would never use it :) I feel like they get in the way more than they help.

If a pre-commit hook was added to run cargo run --help > README.md, then every commit would have to be fully compilable, and you would have to wait for it to compile and run. The friction adds up.

Whereas, a CI job to update and push just works in the background and can run parallel to your own work.

[cristiklein]

Haven't thought about that. Indeed, my idea would add an annoying amount of friction. Thanks for sharing your thoughts.