shaddydc / committable Goto Github PK

For flexibility, rules should be configurable with a config file in a repository, but people should be able to quickly override any behaviour from the CLI.
There are some options to layer options with clap that look more or less good.

Makes it simple to pass in a specific regex, so people can easily enforce their own format like [issue-number] Some message

Does it matter? Is there a recommendation? A standard?

Eg body line length limit

Some examples are eg in the commitlint configs like here.

Also look through some posts like this one, this, and this.

Also some rules from other tools like go-commitlinter.

• Simple spell checker
• Unusual punctuation: Hey ,guys

If I use semantic versioning, I'll have to decide on what they mean and how to manage rule updates.
Do I want to bump the major version every time I add a new rule? There are several approaches for going about this.

1. Tie rule set to tool version.
   This would limit me to add new rules only on major updates and otherwise hide them behind eg --experimental.
   I still want most rules to be enabled by default so not much configuration is required,
   and I don't want to constantly bump the major version, so I don't really like this option.
2. Rules sub-crate with independent version.
   This allows me to update the rules version independently from the committable itself,
   so I can reserve major bumps to changes to the cli options etc.
   I may still want to allow users to avoid breaking changes.
   An option for that is to pass in a rules version, so only rules added before that version are applied.
   Otherwise, everything (stable) is applied.
3. Don't add new rules.
   This is all hypothetical of course.
   If I never work on this beyond maybe a prototype, none of this matters, and I'm overthinking everything.

It might be fine either way, and especially until I reach version 1.0.0,
I can add new rules on minor versions anyway, so it won't matter for a while.

Inspired by this

There are cases when committable fails a commit, and the person who tried to commit doesn't know how to fix it

1. Somebody set up a CI check, and an inexperienced dev had his commit rejected
2. A pre-commit hook rejects a commit from an inexperienced person
3. A specific rule rejects a commit, and it is not clear how to fix it

For 1., it might make sense to to an explanation of how to rebase, reword, and force push. I'm not sure always printing this explanation to the output is useful. Maybe it should be limited to an extra flag that can be enabled in a CI context, or it is always printed when commits are extracted from a git repository rather than provided via stdin.

I'm not sure 2. needs any special handling.

Hopefully, all rules should be clear enough and no explanation necessary. However, I might want to implement a similar mechanism to cargo explain to provide further information on specific rules, good and bad examples, and ways to fix them.

See https://www.conventionalcommits.org/en/v1.0.0/

Or maybe the there-linked angular style?

We might want to support different options in the future or even allow passing in a custom grammar, but for now we keep it simple and use a sensible default

See miette

Some thoughts are here.

A very simple heuristic might be to check that the first word doesn't end in a single s, -ing, or -ed. I'll have to research more and see how well these work.

Some problems can be fixed automatically, such as removing trailing whitespace or breaking overlong lines.
It might make sense to have a mode where a fixed version of the input is printed to stdout and the warnings and errors are printed to stderr. Errors or warnings that could have been fixed automatically need not be shown, although maybe printing which rules have been fixed is still useful for understanding the changes.

Potential example:

~ echo "feat: add support for RevolutionaryX" | committable --autofix
# stdout: "feat: Add support for RevolutionaryX"
# stderr: "Fixed: Start with capital letter"

Some more or less obvious cases

• Document general usage
• Pre-commit hook
• CI
• Merge-request title (like go-commitlinter

In a commit message like feat(scope): Do something, a project might limit the scope to a fixed set of keywords to make eg changelogs more uniform. Something like frontend, backend/db, etc.

Some rules are redundant when other rules are fail.
For example, there is no point warning about the wrong number of lines before the body when there is no body.
We either have to design our rules to avoid that, or we add a mechanism for conditional rule application.
This also makes it easier to avoid errors on eg merge messages (Merge feature-branch into main) and Revert.

Example usage is here

Current output is workable, but it's not great:

› echo "   \n\n\n\n\n" | cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/committable`
Error:   × 2 error(s)

Error:   × NonEmptyHeader
   ╭─[1:1]
 1 │    
   · ─┬─
   ·  ╰── header is empty
 2 │ 
   ╰────
Error:   × NonEmptyBody
   ╭─[2:1]
 1 │        
 2 │ ╭─▶ 
 3 │ │   
 4 │ │   
 5 │ ├─▶ 
   · ╰──── body is empty
   ╰────

Some points on better use of warnings and groups are here and here.
I'll have to think about how I want to go about this.