refactor: coding style cleanup

[jrson83]

This PR fixes multiple issues I encountered when working on #1562. It includes the following changes, I tried to break into multiple commits:

• provide an editorconfig
• enable no-hard-tabs lint rule
  • to apply consistent space indentation
• reformat all markdownfiles and code blocks
• fix wrong code block languages & rename them for consistency
• fix wrong use of comment tags in code blocks
• fix raw comments in code blocks
• fix multiple formatting issues in code blocks
• rename markdownlint config to work with ide extensions (e.g. vscode markdownlint is nice for live editing)
• make sure make fix runs still with success

By providing an .editorconfig phpstorm users should automatically make use of the specified settings. To provide (force) consistancy for vscode users without the need of using third party plugins, a minimal .vscode/settings.json config is required.

Since markdownlint is not intended to format language specific code in code blocks (e.g. javascript) it took longer then I thought. But in the end I think this PR will help to enforce a consistent coding/docs style.

[Isengo1989]

Hey @jrson83 I added a comment on the 3 left adr changes.

Regarding the indenting of 2 spaces. What tool did you use to correct or identify those. make fix will not detect changes as far as I could tell from running it from your branch and reverting some of it, there is no info or fix 🤔

[Isengo1989]

@jrson83 there are still 3 changes from the adrs left. Please remove them

[jrson83]

@jrson83 there are still 3 changes from the adrs left. Please remove them

I am currently unable to operate due to physical exhaustion. I will take care of it as soon as I am able to.

[Isengo1989]

@jrson83 get well soon 🛌 🙁

[jrson83]

@Isengo1989 Thanks, I feel better now.

So we might have a conflict with this last file:
resources/references/adr/2023-02-27-native-extension-system-with-vue.md

In the original file, there is a final new line, which may also include either a space or a tab character. I'm not sure which one if it is, I will try to insert a space in the final new line and commit the file.

[jrson83]

OK that did not work at all. It seams there is a conflict with all the 3 files, cause of different indentation, I cannot revert because the indentation is now forced by the .editorconfig 😟

[jrson83]

@Isengo1989

The inconsistency in indentation in the markdown files you see can happen due to several reasons, especially when there is no shared .editorconfig or other standardization mechanism in place.

• Different Editors and Settings.
• Markdown Doesn't Enforce Indentation Standards.
• Auto-Detect Indentation in Editors.
• Manual Copy-Pasting.
• Absence of Formatting Tools.

A .editorconfig file can enforce consistent formatting If you e.g. configure .editorconfig to use 2 spaces for indentation:

• Any new file created in an editor that respects .editorconfig (e.g., VS Code) will adopt 2 spaces.
• If you later change .editorconfig to use 4 spaces, new files will follow the new rule.
• However, .editorconfig does not automatically reformat existing files unless combined with a formatter.

---

There are two things to bear in mind during the changeover. Git tracks content changes rather than formatting differences like whitespace indentation when it doesn't affect the file's functionality or content meaning. Git can ignore changes in whitespace unless explicitly configured to track them.
Markdownlint works with a standard indentation width of 4, which cannot be influenced globally.

However, since our goal is to create a standardized mechanism with an indentation width of 2 in order to work with a consistent indentation size in every IDE and also with markdownlint, only the editorconfig and the minimal .vscode/settings.json file is necessary. It is not necessary to execute a bulk action or similar on all files.

What I have done here is converted all tabs to spaces with the M010 rule:

a97d97a

So I didn't actually fix the problem, but used the .editorconfig as a workaround to get around the problem.

I reformatted the xml, html and php code blocks with a vscode extension (with editorconfig & settings.json):

https://marketplace.visualstudio.com/items?itemName=ame-neko.markdown-code-block-formatter

This extension can use different configured formatter for any code-block language:

PHP:
https://github.com/bmewburn/vscode-intelephense

XML:
https://github.com/redhat-developer/vscode-xml

YAML:
https://github.com/redhat-developer/vscode-yaml

JS/TS:
Inbuild vscode formatter

Oh and markdownlint does not care about valid indentation in code-blocks at all.

[bojanrajh]

@Isengo1989 With our discussion in mind, I think we can maybe cherry pick some commits:
52540f3
3dac333

Valid, but de-aliased:
c2403ce

See about how much conficts do we create with those:
88bf601
fde1bdc
9ee3862
52942ff

We could also git checkout jrson83:fix/indent -- .vscode .gitignore .github .editorconfig in a separate PR, maybe update this article along the way, and only then create a workflow (using diffplug/spotless?) for checking the indentation and enforce the rule by reformatting the whole repo. All these changes need to be merged into next-6.7 as well.

[Isengo1989]

@Isengo1989

The inconsistency in indentation in the markdown files you see can happen due to several reasons, especially when there is no shared .editorconfig or other standardization mechanism in place.

• Different Editors and Settings.
• Markdown Doesn't Enforce Indentation Standards.
• Auto-Detect Indentation in Editors.
• Manual Copy-Pasting.
• Absence of Formatting Tools.

A .editorconfig file can enforce consistent formatting If you e.g. configure .editorconfig to use 2 spaces for indentation:

• Any new file created in an editor that respects .editorconfig (e.g., VS Code) will adopt 2 spaces.
• If you later change .editorconfig to use 4 spaces, new files will follow the new rule.
• However, .editorconfig does not automatically reformat existing files unless combined with a formatter.

There are two things to bear in mind during the changeover. Git tracks content changes rather than formatting differences like whitespace indentation when it doesn't affect the file's functionality or content meaning. Git can ignore changes in whitespace unless explicitly configured to track them. Markdownlint works with a standard indentation width of 4, which cannot be influenced globally.

However, since our goal is to create a standardized mechanism with an indentation width of 2 in order to work with a consistent indentation size in every IDE and also with markdownlint, only the editorconfig and the minimal .vscode/settings.json file is necessary. It is not necessary to execute a bulk action or similar on all files.

What I have done here is converted all tabs to spaces with the M010 rule:

a97d97a

So I didn't actually fix the problem, but used the .editorconfig as a workaround to get around the problem.

I reformatted the xml, html and php code blocks with a vscode extension (with editorconfig & settings.json):

https://marketplace.visualstudio.com/items?itemName=ame-neko.markdown-code-block-formatter

This extension can use different configured formatter for any code-block language:

PHP: https://github.com/bmewburn/vscode-intelephense

XML: https://github.com/redhat-developer/vscode-xml

YAML: https://github.com/redhat-developer/vscode-yaml

JS/TS: Inbuild vscode formatter

Oh and markdownlint does not care about valid indentation in code-blocks at all.

Hey @jrson83 thx for elaborating. The issue we are having is that the indention is currently not reproducible in a workflow / check, as you mentioned this is not typically done by markdownlinters nor by the ide settings.

Not sure how the IDE behaved if you copy code from another project and paste it in the code block 🤔 But that just said as a side note.

I would agree with @bojanrajh for the time being to cherry pick some commits in order to get the new spacing ready to go in the IDEs and fix comments / code block definitions (PHP -> php ) and some others.

We do have some bigger PRs coming in for 6.7 and a restructuring draft of a lot of content. If those are merged and we can take a closer look at fixing the existing indenting to be up to date. That lead to my question if there was a tool you used to fix those ( I suppose you used the plugins and did a "reformat" in vscode). We can also look at the tool @bojanrajh mentioned (not familiar with it yet).

[Copilot]

Copilot reviewed 301 out of 311 changed files in this pull request and generated no suggestions.

Files not reviewed (10)

• .editorconfig: Language not supported
• .vscode/settings.json: Language not supported
• Makefile: Language not supported
• guides/hosting/infrastructure/message-queue.md: Evaluated as low risk
• guides/hosting/infrastructure/rate-limiter.md: Evaluated as low risk
• concepts/commerce/checkout-concept/cart.md: Evaluated as low risk
• guides/hosting/configurations/framework/samesite-protection.md: Evaluated as low risk
• guides/hosting/configurations/shopware/staging.md: Evaluated as low risk
• guides/hosting/infrastructure/filesystem.md: Evaluated as low risk
• guides/hosting/configurations/observability/profiling.md: Evaluated as low risk

[jrson83]

@bojanrajh @Isengo1989 this sounds great to me. It would be great if the indentation could also be applied to the inported files, if this is possible with the workflow mentioned.

[bojanrajh]

Thanks guys, closing in favour of #1629