Introduce .editorconfig to WordPress

[netweb]

Configuring your editor/IDE for submitting code/patches to WordPress is not the simplest of tasks...

Via ​http://editorconfig.org

"EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs. The EditorConfig project consists of a file format for defining coding styles and a collection of text editor plugins that enable editors to read the file format and adhere to defined styles. EditorConfig files are easily readable and they work nicely with version control systems."

Projects using .editorconfig (Detailed list ​here)

• ​jQuery (Source: ​.editorconfig)
• ​Drupal (Source: ​.editorconfig)
• ​Modernizr (Source: ​.editorconfig)

Initial patch excludes JavaScript and will need testing against all the .js files internal and external libraies.

[TobiasBg]

The patch has a comment for JS at the end, but no rules?

And out of curiosity: What's the benefit of insert_final_newline?

[netweb]

Replying to TobiasBg:

The patch has a comment for JS at the end, but no rules?

It is more of a placeholder for now per the JavaScript comment in the original ticket.

Replying to TobiasBg:

And out of curiosity: What's the benefit of insert_final_newline?

It ensures that the last line of a file has a control character at the end of the code, see ​https://en.wikipedia.org/wiki/Newline

If you look at 'most' WordPress PHP/CSS files in a text editor you will see that they do have this new line at the end of the file, you won't see it browsing Trac though. The addition of this to the .editorconfig ensures this is the case for contributions.

[TobiasBg]

Ah, I had missed that comment about the JS, sorry.

For the insert_final_newline, my question was more targeted at (quote from your Wikipedia link): "Two ways to view newlines, both of which have valid internal logic, are that newlines terminate lines or that they separate lines."
Are you aware of any situations where the EOF newline is required or beneficial? My personal style so far is to not have them, that's why I'm asking.

[netweb]

Replying to TobiasBg:

Are you aware of any situations where the EOF newline is required or beneficial? My personal style so far is to not have them, that's why I'm asking.

The primary reason is different operating systems handle line endings differently and this gives the editors/IDE's of the respective platform a consistent format to treat the line endings appropriately:
via ​https://en.wikipedia.org/wiki/Newline#Representations

• LF: Unix and Unix-like systems including MacOS
• CR+LF: Microsoft Windows

[TobiasBg]

Yes, that's the type of the newline, and that's clear to me. But what's the reason to have a newline at the end of the file (which is what insert_final_newline does).
I can imagine that it's just consistency (and that "Some programs have problems processing the last line of a file if it is not newline-terminated." in the Wikipedia article), but I'm wondering if there's "real-life" advantages for having it.

[jorbin]

I like this idea. Anything that helps ensure we only add new code that is in our guidelines is a good thing.

My question is if any editors will interpret this file and attempt to make changes to our areas of our code base for the lines not directly edited? We generally avoid whitespace only changes as they make it harder to find meaningful change sets. To quote Nacin ​“Code refactoring should not be done just because we can.”

I do wonder if we can perhaps combine all of the various file types into the top [*]. We use tabs everywhere.

[netweb]

Replying to jorbin:

I like this idea. Anything that helps ensure we only add new code that is in our guidelines is a good thing.

My question is if any editors will interpret this file and attempt to make changes to our areas of our code base for the lines not directly edited?

Yes they would, but see next paragraph.

We generally avoid whitespace only changes as they make it harder to find meaningful change sets. To quote Nacin ​“Code refactoring should not be done just because we can.”

A 'one time' patch of 'all the whitespace' could be done but I don't think it is needed.

The whitespace in the codebase is pretty good as it is. eg. The 79 .php files in the root of src\wp-admin I just tested with Sublime Text 3 with the .editorconfig patch and not a single erroneous bit of whitespace was detected. Many/most 'core devs' would most likely already have these WordPress code styling standards already manually configured in their IDE of choice.

I do wonder if we can perhaps combine all of the various file types into the top [*]. We use tabs everywhere.

As the repo contains .xml, .xap, .txt, .swf, .crt, .pot, .md, .po, .mo, .nodelete and .py (could be more I missed) filetypes and as far as I know we can't add an exclusion rule for filetypes thus the explicit grouping of the rules for only the filetypes we DO wan't to include code styling for.

I kept away from the JavaScript in the original patch as the JS guidelines were still being proposed at the time, if these are now formalized this could also be included.

The patch also needs a refresh to include SCSS, i.e. From [*.css] to [*.css,*.scss]

Rule/s for .travis.yml, package.json, phpunit.xml.dist, .gitignore, .jshint could be added or left alone 'for now' and added later 'ron.

[nacin]

If no erroneous whitespace was detected across 79 files, then these rules must not be very strict. :-) Yeah, tabs, line endings, etc., are all going to be just fine across WordPress.

[nacin]

Replying to TobiasBg:

Yes, that's the type of the newline, and that's clear to me. But what's the reason to have a newline at the end of the file (which is what insert_final_newline does).
I can imagine that it's just consistency (and that "Some programs have problems processing the last line of a file if it is not newline-terminated." in the Wikipedia article), but I'm wondering if there's "real-life" advantages for having it.

cat/tail a file without a newline and you'll end up with no \n between the output and your prompt. It also makes patches more verbose, as the default is to assume that there *is* a new line, so it has to add a special comment to the bottom of the file saying that a new line is *not* there. Consistency is needed here to help keep patches less noisy (a lot of them accidentally add/remove this line), and \n at the end of files are far more common and accepted.

[TobiasBg]

Thanks for the explanation, nacin! That cat/tail example and better patches makes sense!

We might have to consider some exceptions for certain files, like end_of_line for wp-config.php, where we want to keep CRLF to make it editable in Notepad on Windows. Except of course if we rely on SVN to not change it in a commit, as it has svn:eol-style set to CRLF.

[netweb]

Replying to nacin:

If no erroneous whitespace was detected across 79 files, then these rules must not be very strict. :-) Yeah, tabs, line endings, etc., are all going to be just fine across WordPress.

Yes, I am quite sure most of WordPress' codebase will be fine as these rules are only the basic tabs, line endings rules etc

Asking a 'new contributor' to adhere to the WP coding standards and configuring their text editor/IDE per ​http://make.wordpress.org/core/handbook/coding-standards/, then digging into each HTML, PHP, JS & CSS sections to just get 'the basics' up and running is quite daunting, it was for me so this is the context I proposed this.

There is a section on the ​.editorconfig wiki on future 'domain specific' ideas such as spaces_around_operators, spaces_around_brackets & indent_brace_style that could be looked at, it's the first time just now I've seen these 'proposed'.

[kirasong]

I also like this idea -- even if it just means we create a default .editorconfig that is linked from the wiki or Contributor Handbook, rather than included in the codebase.

[netweb]

Replying to DH-Shredder:

I also like this idea -- even if it just means we create a default .editorconfig that is linked from the wiki or Contributor Handbook, rather than included in the codebase.

Hadn't really thought of this as an option ;)

Created here: ​https://github.com/ntwb/wp.editorconfig

I haven't added it to the ​Coding Standards handbook though/yet.

[netweb]

In .editorconfig.1.patch:

Refreshed .editorconfig via latest ​https://github.com/ntwb/wp.editorconfig additions by @jorbin

• Adds *.js support
• Adds *.json support
• Combines php, css, scss, html and js file rules into a single rule

[jorbin]

While this doesn't work with every editor and requires a plugin in other editors, this will help developers adhere to our style guide. Let's do it!

[nacin]

In 27198:

Add .editorconfig file, see ​http://editorconfig.org/.

"EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs."

props jorbin, netweb.
fixes #26429.

[nacin]

[27198] is something I actually put together last week, based on netweb's original work. I based it a bit on jQuery's .editorconfig as well, as they are pretty religious about it. If I missed anything or over-simplified, let me know.

[tomauger]

Replying to nacin:

[27198] is something I actually put together last week, based on netweb's original work. I based it a bit on jQuery's .editorconfig as well, as they are pretty religious about it. If I missed anything or over-simplified, let me know.

Wow, once I actually looked into what editorconfig supports, it's pretty disappointing. I was expecting us to be able to define spacing rules ( spaces inside brackets ), indentation rules, nesting rules etc. To me, these seem like the real coding standards that new developers will need help adopting.

Guess we just keep promoting the Coding Standards guide...

[tomauger]

NetBeans is taking first steps to implement EditorConfig: ​https://blogs.oracle.com/geertjan/entry/editorconfig_and_netbeans_ide