Is there a rule for column width? #546
-
|
Sometimes I get the feeling that people don't really care about column width; I usually tend to refuse to read such documents due to poor readability. I wonder if there is or could be a rule in this project about that. |
Beta Was this translation helpful? Give feedback.
Replies: 2 comments 2 replies
-
|
Hmmm I don't think there is a rule from Keep a Changelog itself.. but people usually have rules for their markdown files, or maybe use some formatter. Since the Changelog is a list of changes, each line would not be that long, and could link to the Pull Request for more details. And since it is markdown, it can be rendered in a viewer that wraps lines. |
Beta Was this translation helpful? Give feedback.
-
|
I'm not sure that the lines can always be short to describe more complex changes, we have a changelog that has also several related issue/pull requests numbers. I wonder if it could be an additional suggestion to have a max number and/or some tip to keep lines short. |
Beta Was this translation helpful? Give feedback.
-
|
We don't trade in rules in this project, only guidelines. I'd echo @aryelgois's feedback here. There are many textfile/Markdown-focused linters in place in Projects and I don't think it would be productive to give guidelines on column length when that might clash with existing preferences in projects. That would end up becoming friction to changelog adoption and it's the last thing we want. The number one focus should be to have a changelog in the first place. Since Markdown renders as HTML the formatting of the source matters more for maintainers and contributors than changelog consumes — assuming folks consume the rendered HTML (which I'd argue is the majority of folks). But it's true that making a changelog more readable as source (or if it's plaintext and not Markdown or other plaintext markup languages) is a healthy goal that likely encourages good changelog maintenance practices, and good writing in general. |
Beta Was this translation helpful? Give feedback.
-
|
OK, so what about adding suggestions/advices? Thinking of some "this/these is/are not required but good practice..." section in the site. |
Beta Was this translation helpful? Give feedback.
We don't trade in rules in this project, only guidelines. I'd echo @aryelgois's feedback here.
There are many textfile/Markdown-focused linters in place in Projects and I don't think it would be productive to give guidelines on column length when that might clash with existing preferences in projects.
That would end up becoming friction to changelog adoption and it's the last thing we want.
The number one focus should be to have a changelog in the first place. Since Markdown renders as HTML the formatting of the source matters more for maintainers and contributors than changelog consumes — assuming folks consume the rendered HTML (which I'd argue is the majority of folks).
But it's true t…