End user documentation - where is it?

[jpstotz]

I may have missed it but I can only find the documentation for people who want to set-up commitlint for their project.

I am missing the end-user documentation for those people who want to commit something to a project that uses commitlint.

Therefore in detail I am searching for a description what all the different types mean and when should I use which one.

[byCedric]

Hi Jan! I don't think you can find such information here. We also can't really provide this information because it is project specific. Each project implementing commitlint may have their own way of committing. Usually, you can find that project-specific information in their CONTRIBUTING.md or README.md file. Like chromeless from Prisma, or aws-serverless-express from AWS Labs. Generally speaking it should follow Conventional Commits.

[jpstotz]

So the projects which use commitlint can define their own types?

If your answer is yes then I agree with you that the projects have to provide the documentation.

If your answer is no I disagree, then it is the job of commitlint to provide the default documentation what those abbreviated types mean.

The third link at least provides some information about the background of commitlint. Please add it on your project Readme.md and the commitlint web page. As the page is unrelated to the commitlint project you won't find it otherwise.

BTW: The link http://marionebl.github.io/commitlint in the head of the commitlint GitHub page is HTTP not HTTPS...

[byCedric]

The answer is yes 😉 The example code in the README.md uses @commitlint/config-conventional, which is the actual conventional commits (I think). But there are others like config-angular and config-lerna-scopes (listed under Shared configuration). All of them have links on their own page, including the config-conventional one.

I totally agree with you that the learning curve might be a bit steep. It's something we can improve. But that doesn't mean that projects shouldn't be explaining which types and why they allow. At the company I work for, we add this on every readme file in every repository.

I will fix the http -> https links now! 😄 thanks!

[jpstotz]

I encountered commitlint in a open source community project which did not had a commit guideline. Therefore I only had the name "commitlint" and the error messages

• "Commit message missing" Which is really confusing as I did specify a commit message
• "Commit type missing"

May be it would be a good idea to make the error message a bit more verbose. Especially the error message on the missing commit message was very confusing for me because actually I did specify a commit message, however the real problem was that it did not apply to the commitlint format specification. Therefore the error message should be like this one:

Your commit message does not comply with the commitlint commit message format: [type]: [message]
[type] can be any of...
[message] is the human readable message
For further details please see the project specific contribution guide or ask the project maintainer

[escapedcat]

I agree that the message output could be improved.

@jpstotz it would be great if you can provide a PR with the things you mentioned which could be improved already in the README.

Have a look at @marionebl s slides to a talk he gave regarding commitlint: https://slides.com/marionebl/the-perks-of-committing-with-conventions
You think linking this would help others as well?

[jpstotz]

@escapedcat I will see what I can, however my list of tasks to be done is currently high like a sky scraper.

@byCedric There is still one HTTP link on https://github.com/marionebl/commitlint right the first entry in the "Code" tab (the section above the section displaying the repo content). AFAIR those info is not stored in the git repo, it has to be edited directly on the page.

[escapedcat]

@jpstotz I guess it's the same for us but we try to fit it into the priorities.
It's great if people find time to provide a PR who actually got confused because these people usually know best how to improve the docs.

The HTTP link in the repo description can only be changed by @marionebl for now. Thx for mentioning it.

[jpstotz]

@escapedcat I peeked into the slides you mentioned. It is nice and clean presentation, however without somebody talking and explaining all the details, the information density per slide is a bit low.

Back to the readme, even if I can't prove a PR, I want write my ideas and thoughts:

At the moment the readme start with a cool demo - we are techies and the cool stuff comes first no matter if it is important. At least I got one valuable information from it: After some time the list of types appears. For my investigation of commitlint this was the first and only time I was able to see the different available types!

The rest of the readme more or less is on the question "How to configure my project to use commitlint?".
I assume that new users that see the readme however have different questions:

1. What exactly is commitlint?
2. Why would I use commitlint?

And then and third position the question "How to configure my project to use commitlint?" comes into play.

Therefore I would restructure the readme this way:

Commitlint

Short textual description what commitlint does including it's simple syntax.

Add two examples for the most common usages types like fixand feat and listing of the default types.
Don't forget to mention that the types is configurable and may vary by project.
Also the link to https://conventionalcommits.org/ should be present here.

Benefits using commitlint

I havn't fully understand the advantages in detail, however I assume you have a lot to add here :)

Configure a project to use commitlint

The old readme content, except for the SVG animation.

[escapedcat]

Cool, thanks @jpstotz, that's a good start. I think we can work with this.

[marionebl]

Hey people, thanks for the input and the great ideas.

I talked with @escapedcat about this and here is what we gonna do:

Short term

• Make the subject error message less confusing by changing message to subject (fix: use correct label for failing empty subjects #481)
• Add a README section that targets people that encounter commitlint in a project (thanks @jpstotz for the great input regarding this)
• Link said section in the default formatter output summary

Long term

• Analyse parser output to detect runs where no valid commit message was found and emit special problems for this case

• Idea: Add a urls: string[] to all problems where a "positive/negative" message pair is shown and the rule explained