Error messages are hard for harried engineers to parse

davecb commented 2 years ago

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.

escapedcat commented 2 years ago

Somewhat relates to #3045

You should get this output, right?:

⧗   input: an invalid commit
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

How about adding an individual help-url?

-H, --help-url       help url in error message                        [string]

The info behind there can be taylored to your orgs needs.

davecb commented 2 years ago

Our team has switched the url to https://www.conventionalcommits.org/en/v1.0.0/#summary as it provides more apropos information.

Not perfect, mind you: it talks about "description" while the error message talks about "subject", for what is arguably the same thing. One or the other should probably be changed to match the other.

--dave

On 8/24/22 22:10, escapedcat wrote:

Somewhat relates to #3045 https://github.com/conventional-changelog/commitlint/issues/3045

You should get this output, right?:

⧗ input: an invalid commit ✖ subject may not be empty [subject-empty] ✖type may not be empty [type-empty]

✖ found 2 problems, 0 warnings ⓘ Get help:https://github.com/conventional-changelog/commitlint/#what-is-commitlint

How about adding an individual help-url?

-H, --help-urlhelp urlin error message [string]

The info behind there can be taylored to your orgs needs.

— Reply to this email directly, view it on GitHub https://github.com/conventional-changelog/commitlint/issues/3335#issuecomment-1226686444, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAEITEOWLMSEYFQ24SBZU6TV23IY7ANCNFSM57PSJIKQ. You are receiving this because you authored the thread.Message ID: @.***>

escapedcat commented 2 years ago

Relates to #206

davecb commented 2 years ago

Yes, I can see it used to be worse, and that you've been making progress on it (;-))

davecb commented 2 years ago

Would you like a pull request with a specific proposal?

escapedcat commented 2 years ago

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.

escapedcat commented 1 year ago

Closing in favour of #206

conventional-changelog / commitlint