Skip to content

Add a project .editorconfig file #7081

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mhucka merged 4 commits into from
Feb 25, 2025
Merged

Add a project .editorconfig file #7081

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5fdf996
Resolve #6998: add a .editorconfig file
mhucka Feb 23, 2025
b150b54
Add explanation for .md setting for trailing spaces
mhucka Feb 24, 2025
c693197
Take out exception to trailing spaces rule for .md files
mhucka Feb 25, 2025
2531c2f
Merge branch 'main' into mh-add-editorconfig
mhucka Feb 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions .editorconfig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Summary: coding style configuration for editors that read .editorconfig.
#
# EditorConfig defines a file format for specifying some common coding style
# parameters. Many editors recognize .editorconfig files automatically, and
# there exist plugins for other editors. See https://spec.editorconfig.org/.

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
spelling_language = en-US
trim_trailing_whitespace = true

[*.md]
# Important setting: trailing whitspace is meaningful in Markdown.
trim_trailing_whitespace = false
Copy link
Copy Markdown
Collaborator

@pavoljuhas pavoljuhas Feb 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please comment when is this needed?

My impression was that trailing spaces in md were basically a noise that would be better removed.

Copy link
Copy Markdown
Contributor Author

@mhucka mhucka Feb 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a little bit bonkers, but the use of 2 trailing spaces is one of the ways that md lets you indicate an explicit line breeak. Here are a couple of places where this is described:

I'll try to find a public spec somewhere and add a comment to the .editorconfig file to point to it.

The Google md style recommentation (which I can't find atm) recommends avoiding this construct. However, because it's technically allowed, and because other style guides and formatters pay attention to it, and because there doesn't seem to be a setting in editorconfig for "allow exactly 2 spaces but remove 1 or 3+ spaces", the only safe thing to do for md files seems to be to disable the setting to remove trailing whitespace. (If there's a better way, I'm completely happy to do it!)

Copy link
Copy Markdown
Contributor Author

@mhucka mhucka Feb 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, I didn't test this, but I bet 3 or more spaces would also produce a line break.

Copy link
Copy Markdown
Contributor Author

@mhucka mhucka Feb 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, markdownlint has a setting to control this: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md#md009---trailing-spaces

The default is 2 spaces, meaning it will flag single spaces at the ends of lines.

Copy link
Copy Markdown
Collaborator

@pavoljuhas pavoljuhas Feb 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are only 3 places in our markdown files that have 2 trailing blanks. None of those is necessary; they don't really seem intentional.

$ git grep -n "\s{2,}$" "*.md" "*.mark*"
.github/ISSUE_TEMPLATE/project_health.md:3:about: Issues related to CI, automation infra, clean code, depreca>
docs/dev/nomenclature.md:14:`wave_function`, or `state` for this object (`state` is too overloaded).
docs/dev/style.md:13:with the following guidance.

I think the Google style guide recommendation against trailing double-spaces is reasonable.
They make text behave differently without visible markup, which makes it harder to judge if those spaces are intentional or left over from text editing. It is IMO better to stick to the explicit \ or <br> syntax for creating manual linebreaks.

Can we disallow trailing blanks in editorconfig and also flag them as errors in markdownlint?

Copy link
Copy Markdown
Contributor Author

@mhucka mhucka Feb 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes; I'll make the change and push an update. (Actually, I just looked at our .markdownlintrc again, and it turns out it already disallows trailing spaces.)


[*.py]
indent_size = 4
indent_style = space
max_line_length = 100

[*.sh]
indent_size = 4
indent_style = space
max_line_length = 100

[*.yml,*.yaml]
indent_size = 2