WordPress.org

Make WordPress Core

Opened 15 months ago

Closed 13 months ago

Last modified 12 months ago

#26429 closed enhancement (fixed)

Introduce .editorconfig to WordPress

Reported by: netweb Owned by: nacin
Milestone: 3.9 Priority: normal
Severity: normal Version: 3.8
Component: Build/Test Tools Keywords: commit
Focuses: Cc:

Description

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)

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

Attachments (2)

.editorconfig.patch (1.1 KB) - added by netweb 15 months ago.
.editorconfig.1.patch (1.1 KB) - added by netweb 13 months ago.

Download all attachments as: .zip

Change History (23)

@netweb15 months ago

comment:1 follow-up: @TobiasBg15 months ago

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?

comment:2 in reply to: ↑ 1 @netweb15 months ago

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.

comment:3 follow-up: @TobiasBg15 months ago

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.

comment:4 in reply to: ↑ 3 @netweb15 months ago

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

comment:5 follow-up: @TobiasBg15 months ago

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.

comment:6 @jdgrimes15 months ago

  • Cc jdg@… added

comment:7 follow-up: @jorbin13 months ago

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.

comment:8 in reply to: ↑ 7 @netweb13 months ago

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.

comment:9 follow-up: @nacin13 months ago

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.

comment:10 in reply to: ↑ 5 @nacin13 months ago

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.

comment:11 @TobiasBg13 months ago

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.

comment:12 in reply to: ↑ 9 @netweb13 months ago

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'.

comment:13 follow-up: @DH-Shredder13 months ago

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.

comment:14 in reply to: ↑ 13 @netweb13 months ago

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.

comment:15 @ircbot13 months ago

This ticket was mentioned in IRC in #wordpress-dev by jorbin. View the logs.

@netweb13 months ago

comment:16 @netweb13 months ago

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

comment:17 @jorbin13 months ago

  • Keywords commit added
  • Milestone changed from Awaiting Review to 3.9

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!

comment:18 @nacin13 months ago

  • Owner set to nacin
  • Resolution set to fixed
  • Status changed from new to closed

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.

comment:19 follow-up: @nacin13 months ago

[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.

comment:20 in reply to: ↑ 19 @tomauger12 months ago

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...

comment:21 @tomauger12 months ago

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

Note: See TracTickets for help on using tickets.