Improve markdown linter; Optimize for human time vs brittle manual markdown formatting.
bwplotka opened this issue · 4 comments
Hello 👋🏽
I like the fact that this project has a markdown linter that enforces some consistent styling. We do that in projects we maintain e.g Thanos (e.g here). However, I think there is some room to improve. As an author of the proposal or some markdown document, I want to focus on the content, not on formatting. Yet I literally spent ~2h in a total of my time on fixing my proposal #866 formatting (not mentioning context switches). I think that's not the smartest way to spend my paid work time, and I think there are alternatives that will minimize human time but enforce good styling which is aiming to improve maintenance and readability.
Let's enumerate why I had to spend so much time (and my PR at the time of writing is still failing #866):
- Linter is giving me only snippets of errors, not all the errors (or I cannot use the output), this means I have to push and check if it passes to learn there is a bunch of errors in another place.
- Almost 99% of errors I fixed was arguably useful. Things like:
- Line length does not matter these days. Most editors can wrap lines on certain width and markdown format does not care either.
- Why do spaces inside linked item matters? or code spans?
- Language in code spans having to be specified is also a bit too strict
Anyway, those are just opinions, but there is something that will satisfy everyone. If we lint on some problem, why not.. fixing this automatically?
Proposal
- Introduce a proper markdown formatter that fixes all problems and produces formatted markdown or fails if it cannot fix it.
- Run it in CI, if produced output by formatter is different then what was committed then fail. If formatter fails, fail.
- Allow users easily install and run formatter without extra configuration
We did that in https://github.com/bwplotka/mdox if we want to use it here too. Just run mdox fmt of mdox fmt --check if we want to validate if things are formatted.
We use https://github.com/Kunde21/markdownfmt internally.
Hope that will help future designers and authors of markdown in this project (:
Inactive enhancement proposals go stale after 28d of inactivity.
See https://github.com/openshift/enhancements#life-cycle for details.
Mark the proposal as fresh by commenting /remove-lifecycle stale.
Stale proposals rot after an additional 30d of inactivity and eventually close.
Exclude this proposal from closing by commenting /lifecycle frozen.
If this proposal is safe to close now please do so with /close.
/lifecycle stale
Stale enhancement proposals rot after 7d of inactivity.
See https://github.com/openshift/enhancements#life-cycle for details.
Mark the proposal as fresh by commenting /remove-lifecycle rotten.
Rotten proposals close after an additional 7d of inactivity.
Exclude this proposal from closing by commenting /lifecycle frozen.
If this proposal is safe to close now please do so with /close.
/lifecycle rotten
/remove-lifecycle stale
Rotten enhancement proposals close after 7d of inactivity.
See https://github.com/openshift/enhancements#life-cycle for details.
Reopen the proposal by commenting /reopen.
Mark the proposal as fresh by commenting /remove-lifecycle rotten.
Exclude this proposal from closing again by commenting /lifecycle frozen.
/close
@openshift-bot: Closing this issue.
In response to this:
Rotten enhancement proposals close after 7d of inactivity.
See https://github.com/openshift/enhancements#life-cycle for details.
Reopen the proposal by commenting
/reopen.
Mark the proposal as fresh by commenting/remove-lifecycle rotten.
Exclude this proposal from closing again by commenting/lifecycle frozen./close
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.