Helm-charts: Markdown: should we require one sentence per line?

[scottrigby]

📊 Maintainers poll: should we require one sentence per line in markdown files?

I initially removed these from the READMEs where they existed, but am rethinking that now. I removed them because they were not consistent. But maybe it's better to make them consistent the other way, by adding them back, and then requiring that moving ahead. https://sembr.org/ makes a compelling case for this, and I'm inclined to agree.

This issue is only about whether maintainers also agree, and want this to be part of this repo style guide. Thoughts?

Also see this related issue about whether to enforce markdownlint in general: https://github.com/scottrigby/prometheus-helm-charts/issues/19

For options, see:

• https://github.com/DavidAnson/markdownlint/issues/66
• PS I know Josh as well and can discuss implementation with him if needed: https://github.com/JoshuaKGoldberg/sentences-per-line

[torstenwalter]

@scottrigby nice references! I like the article linked from denver.org https://rhodesmill.org/brandon/2012/one-sentence-per-line/

I agree that semantic line breaks / one sentence per line makes it easier to review changes.
I have no experience with linters to enforce it.
A good start would be to disable rules which force line breaks after 80 characters when linting markdown.

[gkarthiks]

@scottrigby I like the semantics breaks. It's also easy on eyes, doesn't need to read a statement twice to make sense of.

Here's my +1 on this.

[monotek]

Could we add this as a requirement to the ci pipeline / linter maybe?
If so, sounds good to me :)

[scottrigby]

@JoshuaKGoldberg pointed me here https://github.com/JoshuaKGoldberg/sentences-per-line/issues/6 and said it should be doable, the rule is basically a glorified regular expression

[JoshuaKGoldberg]

It would be an honor to have my teeny markdownlint rule used here ☺️ and I would be happy to support as needed!

[torstenwalter]

It would be an honor to have my teeny markdownlint rule used here and I would be happy to support as needed!

@JoshuaKGoldberg Do you know if it's possible to in include your rule in https://github.com/github/super-linter?

Markdownlint is called here: https://github.com/github/super-linter/blob/c58bab262756890004e5bbb3cf8744ed1e6174c4/lib/linter.sh#L1646

[JoshuaKGoldberg]

😕 no, it looks like it's not possible to include custom -r/--rules markdownlint rules in super-linter right now. I'll defer to @DavidAnson as to whether there's any interest in allowing those rules to be configured via the config file.

Alternately, maybe super-linter could take an issue to allow configuring those things? I haven't used it enough to know their project ethos very well.

[DavidAnson]

@JoshuaKGoldberg Maybe add the markdownlint-rule keyword to your package so it shows up here for other people to find: https://www.npmjs.com/search?q=keywords:markdownlint-rule

@JoshuaKGoldberg You may be able to use the markdownlint-rule-helpers package to remove the dependency of your rule on internals of the linter: https://www.npmjs.com/package/markdownlint-rule-helpers

@JoshuaKGoldberg I added a note to the issue above to address one of the concerns therein.

Everyone: The .markdownlint.json configuration file is exclusively for configuring rules, so that doesn't help the scenario above. However, I created an alternate version of the CLI that is entirely configuration-file-based. This scenario where it's not convenient to update the caller of the tool is sort of kind of what I had in mind when I created it. Perhaps that could help: https://github.com/DavidAnson/markdownlint-cli2

Everyone: you may also be interested in this issue with a somewhat more detailed discussion of line breaking: https://github.com/DavidAnson/markdownlint/issues/298

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Any further update will cause the issue/pull request to no longer be considered stale. Thank you for your contributions.

[stale[bot]]

This issue is being automatically closed due to inactivity.