commitlint: More descriptive error messages

@marionebl Just adding my two cents here.

I was stuck for 5 minutes trying to fix a commit message in some project I was contributing to until I watched the termcast / gif on marionebl.github.io/commitlint. Then I knew what went wrong. I think a simple note telling users:

To learn more about using commitlint visit: marionebl.github.io/commitlint

…would go a long way, and we don’t have to bloat the error output while drawing some attention to your website at the same time.

You could even spice it up a bit if you want:

Stuck on git commit? Visit marionebl.github.io/commitlint to learn how to use commitlint.

Cheers! 👋

Agree, adding this to an open source project and contributors will face difficulties understanding why commit fail if they did not read the CONTRIBUTE.md. It will be nice to add a configurable message append to the error messages and pointing people to read the guides

@jorgebucaran the output was changed to this:

⧗   input: fooo
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]
✖   found 2 problems, 0 warnings
    (Need help? -> https://github.com/conventional-changelog/commitlint#what-is-commitlint )

Is this what you were hoping for?

Having an option to configure the error message would be a very beneficial addition to the project, in my opinion. It would allow maintainers to carefully guide first-time contributors (who may not have paid enough attention to documentation) to understand the requirements and craft their commit messages properly. Without this, the first-time experience for a user unfamiliar with the concept may be somewhat daunting: What is a “commit type”? What is “husky”? What is the difference between subject and message?

Another suggestion is to simply add a configurable “verbose” type of switch eg. -vv

This allows the level of verbosity to the individual.

LGTM 🙌

We’d love this addition at our company. Is this feature in the works, and if not, is there a roadmap for this feature to be added?

Maybe the approach is to provide an interface to provide better error messages. That way, a project such as conventional-commits (used in the example from OP) would be able to provide a template… in the meantime, consumers can provide their own templates.

My opinion is there is no such thing as bloat in a error message when the content is relavent. It’s no different then providing a stack trace.

Well, if something is relevant is determined by the knowledge of our user, which we don’t know anything about in advance.

I personally don’t want to skip over a format description every single time I see a commitlint message.

My recent encounter was when I implemented this into our workflow, I had a particular dev that was confused to how to get his commit to be accepted. Caused a lot of frustration and unproductive research to find the solution. Yes we did document this, but he had to wait till we helped him find said documentation.

We could allow projects such as yours to adapt to specific needs by extending the rule API and the configuration of rules. We could achieve a lot in DX if we emit configured descriptions and “do” / “dont’t” examples (configurable, too?)

• https://github.com/marionebl/commitlint/pull/150#issuecomment-346125201

Thanks for the suggestion. I’m a bit worried this would bloat the error output to a level that puts most users off.

We could use external explanations on e.g. commitlint.github.com and link to the relevant pages, e.g. like eslint does: https://eslint.org/docs/rules/for-direction

What do you think?