More descriptive error messages

[poppabear8883]

It would be beneficial to developers workflow to not have to interpret what the error means.

Current Behavior

Currently this is what we are seeing

husky > npm run -s commitmsg (node v6.11.3)

⧗   input: should fail
✖   message may not be empty [subject-empty]
✖   type may not be empty [type-empty]
✖   found 2 problems, 0 warnings

husky > commit-msg hook failed (add --no-verify to bypass)

Expected Behavior

Something to this effect seems like a better output to me ...

husky > npm run -s commitmsg (node v6.11.3)

**Format**
type[(scope)]: subject
[body]
[footer]

**Acceptable Values***
- Types: 'build' , 'chore' , 'ci' , 'docs' , 'feat' , 'etc...'
- Scopes: 'ANY' *MUST be lower-case*
- Subject: 'ANY' *MUST NOT be pascal-case sentence-case or camel-case*
- Body: 'Any' *etc ...*
- Footer: 'Any' *etc ...*

⧗   input: should fail
✖   message may not be empty [subject-empty]
✖   type may not be empty [type-empty]
✖   found 2 problems, 0 warnings

husky > commit-msg hook failed (add --no-verify to bypass)

Also being consitent with the following:

message may not be empty [subject-empty]
SHOULD BE
subject may not be empty [subject-empty]

Affected packages

• [ x] cli
• [ x] core
• [ x] prompt
• [ x] config-angular

Possible Solution

Simply add more information to the output messages.

Context

Workflow

[marionebl]

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?

[poppabear8883]

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.

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.

As I would admit that this could had been prevented on our side, I can't help but to agree with the dev that the error output was to vague.

I don't think anyone would disagree with adding more descriptive error messages in any context.

[poppabear8883]

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

This allows the level of verbosity to the individual.

[marionebl]

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

[poppabear8883]

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?)

This sound reasonable to me. My point was mainly that there should be a way to make better use of whats displayed in the case of a warning or error. So this proposal seems reasonable enough to satisfy that need.

[huchenme]

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

[n1313]

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?

[e-cloud]

@poppabear8883 I think we could add description flag to control message visibility, and add a description field in config file to provide the custom message.

[DavideDaniel]

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.

[the0neWhoKnocks]

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?

[jorgebucaran]

@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! 👋

[escapedcat]

@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?

[jorgebucaran]

LGTM 🙌

[tuesday-freya]

The ability to customize the output would still be valuable.

We use commitizen with husky. Developers are split across windows and mac. Configuring commitizen + husky to have a prepare-commit-msg to enforce the commit format does not work for windows because it cannot be interactive due to "exec < /dev/tty". So I am using commitlint to enforce the format instead. It would be nice for us to be able to configure a custom error message that suggests using our alternative script "yarn commit" which calls "npx git-cz" and shows them the interactive console that guides them on the proper format.

[escapedcat]

@eschall sounds like configuring your own help messge might help in your situation, no? Should be released soonish.

[marionebl]

Locked this down as the first unhelpful comments trickled in. We will get around implementing a way for users / integrators to provide custom error messages at some point. Please keep in mind that this project is run by volunteers in their free time.