Error messages are hard for harried engineers to parse

We are a happy user of conventional commits, but the messages can be unclear for engineers in the middle of trying to debug a failing pipeline.

The messages are written in terms immediately understandable to the authors, and to the team here that deals with our CI/CD pipelines, but puzzle engineers who are merely using the pipelines. We (ie, you and I) should be aware our readers don’t necessarily know what the technical terms refer to.

It’s not as hard as having to write for ops on-call engineers who have been woken up in the middle of the night (something I do a lot) but it’s a bit of extra effort.

Expected Behavior

We called commitlint on the string ‘an invalid commit’ and expected to be told we need a type

Current Behavior

We got

✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

The first message is puzzling: it sounds like it’s just wrong.

Both could use terminology that are more recognizable to engineers working on commits (repeated below) I suggest, for example,

• changing the first message to ‘commit message may not be empty [subject-empty]’
• changing the second to ‘“type” prefix must not be empty and must end in a colon [type-empty]’

Affected packages

Sorry, I don’t know the implementation

Possible Solution

Both could use terminology that are more recognizable to engineers working on commits I suggest, for example,

• changing the first message to ‘commit message may not be empty [subject-empty]’
• changing the second to ‘“type” prefix must not be empty and must end in a colon [type-empty]’

Steps to Reproduce (for bugs)

COMMIT_MSG=‘an invalid commit’ echo “$COMMIT_MSG” | npx commitlint

Context

We’re rolling out commitlint to a 400-engineer organization, after a successful POC with one team. Most engineers understand conventional commits in the abstract, but have not used them before.

Your Environment

Run in docker, not known.

[davecb]

Would you like a pull request with a specific proposal?

[escapedcat]

Sure, if you have time and motivation.
tbh I’m happy enough keeping this project maintained as it is right now. I can only handle this with the help of others. If you think it’s suitable you can use 206 and close this. Whatever you prefer.