Next Steps

It’s been a while since you’ve all heard from me, so I wanted to check in and assure you I am still alive. I’ve been plodding along behind the scenes with the JSON API and mostly getting design documents sorted.

The big feature I’m working on at the moment – media – has turned out to be tricker than I initially thought. While media is technically handled via custom post types, it’s a completely different kettle of fish to normal post types, so I’ve been working through the conceptual issues behind this to ensure that the API stays consistent both internally and externally. I really believe that it’s worth my time to sit down and consider these conceptual issues in depth rather than pumping out the feature as soon as possible. (The implementation of the media-related endpoints is working locally, but I don’t want to push this up while it’s still in flux.)

I still hold out hope to push through media, but will likely reduce the scope of the other tasks to compensate, due to the complexity of media and the time it has taken so far. I’d like to personally apologise for this, this is a result of improper scheduling for the second half of the project.

Personally, the past month or so has been pretty stressful as well, due to a number of other things going on in the background. Balancing this project with university work has become a big issue recently, so I’m working through this as best as I can. Ideally, my preferred option at this point would be to push this project out of the Summer of Code phase and into the opensource team phase rather than continuing to work on the project in isolation.

Along those lines, revisions will be bumped from the Summer of Code phase completely. While they are part of core functionality, they’re a rather large task that is secondary in importance to media and also behind taxonomy handling. I’d love to see these in the plugin at some point, but that won’t be happening during the Summer of Code phase. What I would love is for someone to volunteer to develop this (in a separate plugin for now, thanks to GSoC’s restrictions) for integration back in as soon as possible, which would also help with validating the API’s usefulness.

So again, sorry and hopefully I’ll have something better to show you next week. Thanks for your patience.

Hello world! My name is Frederick, one of the GSoC interns who will be contributing to WordPress migration features this summer.

A proud Canadian who grew up in Toronto and its suburbs, I am currently a bioengineering undergraduate at the University of Pennsylvania in Philadelphia, with hopes of working in the clinical and public health roles of a physician. The connection to coding might seem tenuous, but I am a firm believer in pursuing passions, despite how incongruous they may seem. As I wrote in my application, WordPress has offered me much in the way of community and inspiration, and I hope to gain better insight into my own aspirations through this internship.

Like many in the community, my involvement with WordPress has included some plugins, and sites developed for work and student organizations. Although I’ve worked on two separate opensource PHP projects, this is the first opportunity I’ve had to contribute to something that can reach so many people; indeed, the past Ten Good Years have yielded not only a collection of lines of code, but a huge and intensely active ecosystem of developers, designers, and users. To have the chance, even for 3 short months, to be a part of it, is both exhilarating and terrifying at the same time!

My project is to improve the migration experience and the portability of WordPress. Just the thought of moving WordPress elicits headaches because of all the things that can go wrong, as one stunningly recent discussion in the community reminded me.

For this project, I’ll be treading across both familiar and foreign territory. By current plans, I’d like to bring domain/URL renames to the backend and WP CLI, improve media handling and progress feedback in the WordPress-to-WordPress importer, and build in some semblance of plugin & option migration to the export/import workflow. (Subject to further change with notice.) More details will come in the days ahead.

I’m really thrilled to be working with all of you! In addition to my weekly updates here, my notes-to-self and handy links to Trac/source can be found on my project site. I’d love to hear your feedback here and throughout the project.

Hi everybody! Some of you may know me from various patches or WP-related endeavours: I’m Ryan McCue, developer of the SimplePie library used in core, along with a HTTP library called Requests, and long-time core hacker. I’ve been working with WordPress for quite a while now, both on opensource and professional work with clients. What you may not know is that I’m also studying Electrical Engineering and Maths at UQ in Australia, and I’m here to give you a heads up on my Summer of Code project over the coming months.

For those who missed the discussion on wp-hackers about my proposal, I’m working on a JSON-based REST API for core. I started on this with an initial proof-of-concept back at the end of last year, and I’m now working on expanding this out into a larger project. The code is being written as a plugin for testing, with the goal of having it integrated into core in some form post-GSOC.

(You’ll notice I’m currently about a week behind on my schedule, which I suspected may happen, as I’m in the midst of my final exams here. I’ve allocated an extra week just before the midsemester review for catching up if I don’t do so before then.)

As it is, the plugin is in a usable format, and you can grab it from either GitHub or Subversion. I’d also recommend checking out the GSOC Trac issues if you’d like to keep track of the status. I’d love to have your feedback (especially on the design documents) as I move forward.

Cheers, and I look forward to working with you all in the coming months!

Part of the design of the core of the JSON handler is the idea that global state is to be avoided where possible in the methods. Although it’s not part of the GSOC scope, it’s definitely designed so that you can add an endpoint handler and route everything yourself while still reusing the existing code. (I’d like to tackle it at some point, but out of scope for now)

Good luck working out the endpoint handling though. 😉

That’s correct regarding SVN, but the .org SVN is our “official” repository in terms of GSOC accountability (and is also linked to Trac).

The plan is that plugins will be able to add additional endpoints with all the same flexibility and features as the core API, so yes, as long as bbPress adds in those hooks for additional endpoints, this will be possible eventually.

Great work, Ryan. This will really empower JavaScript developers to develop applications on top of WordPress. No longer will they have to create WP Ajax handlers every time for anytime they may need to do: they can do it all in JavaScript.

Allow me to introduce myself — my name is Kat. I’ll be working on core this summer as an OPW intern.

I live in the Bay Area and have been a freelance web developer for the past couple of years, so as you can imagine, I work with WordPress quite a bit. I’ve written custom themes, taxonomies, post types and plugins, but nothing that I’ve been able to release back to the community.

Even though contributing to an opensource project has been a goal of mine for many years, I was never able to figure out how to get started until now. When a friend sent me the OPW page and I saw WordPress on the list, I leapt at the chance to get more involved with a tool (and a community) that I’ve worked so much with, and in the process really level up my WP knowledge.

For my summer project, I’ll be removing the “post by email” functionality from core, deprecating it and replacing it with an official plugin. This addresses Trac ticket #22942.

There are some more details in the initial version of the proposal I wrote up. Note that I haven’t yet hashed through the plan with my mentors, so standard disclaimers apply. (Details subject to change without notice. Void where prohibited. Not labeled for retail sale.)

Feel free to comment with feedback, or just to say hi. I’m looking forward to working with you!

Congrats on the internship Kat. I’m suring that working with wp core will be an amazing experience. I wish I had the opportunity to do so full-time as well. Keep your head up and stay positive, the whole world’s on your shoulders now…..no pressure though..lol

Like any coding standard, the purpose of the WordPress CSS Coding Standards is to create a baseline for collaboration and review within various aspects of the WordPress opensource project and community, from core code to themes to plugins. Files within a project should appear as though created by a single entity. Above all else, create code that is readable, meaningful, consistent, and beautiful.

Within core stylesheets, inconsistencies will often be found. We are working on addressing these and make every effort to have patches and commits from this point forward follow the CSS coding standards. More information on the above and contributing to UI/front-end development will be forthcoming in a separate set of guidelines.

Structure

There are plenty of different methods for structuring a stylesheet. With the CSS in core, it is important to retain a high degree of legibility. This enables subsequent contributors to have a clear understanding of the flow of the document.

Use tabs, not spaces, to indent each property.

Add two blank lines between sections and one blank line between blocks in a section.

Each selector should be on its own line, ending in either a comma or an opening curly brace. Property-value pairs should be on their own line, with one tab of indentation and an ending semicolon. The closing brace should be flush left, using the same level of indentation as the opening selector.

Selectors

With specificity, comes great responsibility. Broad selectors allow us to be efficient, yet can have adverse consequences if not tested. Location-specific selectors can save us time, but will quickly lead to a cluttered stylesheet. Exercise your best judgement to create selectors that find the right balance between contributing to the overall style and layout of the DOM.

Similar to the WordPress Coding Standards for file names, use lowercase and separate words with hyphens when naming selectors. Avoid camelcase and underscores.

Use human readable selectors that describe what element(s) they style.

Attribute selectors should use double quotes around values

Refrain from using over-qualified selectors, div.container can simply be stated as .container

Properties

Similar to selectors, properties that are too specific will hinder the flexibility of the design. Less is more. Make sure you are not repeating styling or introducing fixed dimensions (when a fluid solution is more acceptable).

Properties should be followed by a colon and a space.

All properties and values should be lowercase, except for font names and vendor-specific properties.

Use hex code for colors, or rgba() if opacity is needed. Avoid RGB format and uppercase, and shorten values when possible: #fff instead of #FFFFFF.

Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values as much as possible. (For a shorthand reference, see CSS Shorthand.)

Property Ordering

“Group like properties together, especially if you have a lot of them.”
— Nacin

Above all else, choose something that is meaningful to you and semantic in some way. Random ordering is chaos, not poetry. In WordPress Core, our choice is logical or grouped ordering, wherein properties are grouped by meaning and ordered specifically within those groups. The properties within groups are also strategically ordered to create transitions between sections, such as background directly before color. The baseline for ordering is:

Display

Positioning

Box model

Colors and Typography

Other

Things that are not yet used in core itself, such as CSS3 animations, may not have a prescribed place above but likely would fit into one of the above in a logical manner. Just as CSS is evolving, so our standards will evolve with it.

Top/Right/Bottom/Left (TRBL/trouble) should be the order for any relevant properties (e.g. margin), much as the order goes in values. Corner specifiers (e.g. border-radius-*-*) should be top-left, top-right, bottom-right, bottom-left. This is derived from how shorthand values would be ordered.

Vendor Prefixes

We use grunt-autoprefixer as a pre-commit tool to easily manage necessary browser prefixes, thus making the majority of this section moot. For those interested in following that output without using Grunt, vendor prefixes should go longest (-webkit-) to shortest (unprefixed). All other spacing remains as per the rest of standards.

Multiple comma-separated values for one property should be separated by either a space or a newline, including within rgba(). Newlines should be used for lengthier multi-part values such as those for shorthand properties like box-shadow and text-shadow. Each subsequent value after the first should then be on a new line, indented to the same level as the selector and then spaced over to left-align with the previous value.

Media Queries

Media queries allow us to gracefully degrade the DOM for different screen sizes. If you are adding any, be sure to test above and below the break-point you are targeting.

It is generally advisable to keep media queries grouped by media at the bottom of the stylesheet.

An exception is made for the wp-admin.css file in core, as it is very large and each section essentially represents a stylesheet of its own. Media queries are therefore added at the bottom of sections as applicable.

Commenting

Comment, and comment liberally. If there are concerns about file size, utilize minified files and the SCRIPT_DEBUG constant. Long comments should manually break the line length at 80 characters.

A table of contents should be utilized for longer stylesheets, especially those that are highly sectioned. Using an index number (1.0, 1.1, 2.0, etc.) aids in searching and jumping to a location.

Comments should be formatted much as PHPDoc is. The CSSDoc standard is not necessarily widely accepted or used but some aspects of it may be adopted over time. Section/subsection headers should have newlines before and after. Inline comments should not have empty newlines separating the comment from the item to which it relates.

/* This is a comment about this selector */
.another-selector {
position: absolute;
top: 0 !important; /* I should explain why this is so !important */
}

Best Practices

Stylesheets tend to get long in length. Focus slowly gets lost whilst intended goals start repeating and overlapping. Writing smart code from the outset helps us retain the overview whilst remaining flexible throughout change.

If you are attempting to fix an issue, attempt to remove code before adding more.

Magic Numbers are unlucky. These are numbers that are used as quick fixes on a one-off basis. Example: .box { margin-top: 37px }.

DOM will change over time, target the element you want to use as opposed to “finding it” through its parents. Example: Use .highlight on the element as opposed to .highlight a (where the selector is on the parent)

Know when to use the height property. It should be used when you are including outside elements (such as images). Otherwise use line-height for more flexibility.

Once it’s finalized could you merge it with the pre-existing CSS Coding Standards on the Codex? I added that over 2 years ago and we’ve been using it for default themes since.

Biggest differences are ordering of properties, comment format (standard on Codex is more strict), and the one line between rule blocks (no line in the Codex standard when in a grouping of similar rules).

Hi, Phil here, I’m doing my first review of a wp theme. The css will not validate after the second test. The 6 errors are below, can these be fixed? there are also 71 warnings(due to the 6 errors i suppose), also, does the css have to pass validation for a wp theme? Thanks wpcustom

But I think that conflicts with the WordPress Coding Standards article on the Codex. In the Naming Conventions section, it says, “Separate words via underscores”, and only mentions hyphens in the context of filenames.

Is the general coding standards article only referring to PHP, and not HTML? It seems odd to me to use underscores in PHP, but hyphens in HTML/CSS, especially since there’s so much PHP and HTML intertwined in Core. You’d end up with lines of code that looked http://pastebin.com/iZ4tu9e6, where hyphens and underscores are mixed for the same piece of data.

Since hyphens can’t be used in PHP variable names, would be better to standardize around always using underscores for PHP, HTML and CSS? Maybe it’s too late for that, though.

Ok, thanks for updating the wording in the Selectors section; it’s clearer now.

Is there a WP naming convention for hyphens vs underscores in HTML? I couldn’t find any. I’m wondering what’s appropriate for the example I linked to above. I’m guessing hyphens in the id attribute (because it’ll be used as a CSS selector), but underscores in the name attribute (because it’ll be processed by PHP when the form is submitted) ?

You say “Above all else, choose something that is meaningful to you and semantic in some way. Random ordering is chaos, not poetry. In WordPress Core, our choice is logical or grouped ordering, wherein properties are grouped by meaning and ordered specifically within those groups. The properties within groups are also strategically ordered to create transitions between sections, such as background directly before color. The baseline for ordering is […]” but in WordPress core, not even a single CSS file in /wp-admin/ or /wp-includes/ follows any standard…… it’s chaos.

Do WordPress ” CSS Shorthand Standards” always override “CSS Coding Standards”? Examples
** “Properties should be followed by a colon and a space.” vs shorthand standards which eliminates the space
**Placing block items and braces on separate lines vs shorthand standards which uses a single line.
(Probably obvious to everyone else but I am a newb and standards are for newbs!)

Internet Relay Chat, a network where users can have conversations online. IRC channels are used widely by opensource projects, and by WordPress. The primary WordPress channels are #wordpress and #wordpress-dev, on irc.freenode.net.

The plugin directory’s licensing guidelines have been updated. The guidelines will now allow code that is licensed under (or compatible with) version 3 of the GPL.

The guidelines still encourage use of “GPLv2 or later,” the same license as WordPress. However, we understand that many opensource libraries use other licenses that are nonetheless compatible, such as GPLv2 only, GPLv3, and Apache 2.0.

Now may be a good time for plugin authors to review their plugins to ensure a license is specified. You can add License and License URI headers to readme.txt and the plugin’s headers. (You may also wish to include a copying permission statement.) For example:

This change brings the guidelines in line with the themes directory, which has for some time accepted GPLv3-compatible code. (Probably a good time to note that Creative Commons licenses are still incompatible with the GPL, and the theme and plugin directories.)

It would be nice to have a list with (in)compatible licenses for users which aren’t familiar with this topic.
Since it’s also a problem if your plugin is GPL but your are using an external lib which is incompatible and you didn’t know that.

It’s good practice to include a license.txt or COPYING file. At the very least, you should probably include the copying permission statement, which would state, “You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.” At worst, as long as it is specified somewhere in the readme or code, at least people know what your intent is.

And, if it is in the readme, we will be able to show it on your plugin’s page in the future.

I used the readme validator twice today. it worked earlier this afternoon then failed this evening. I was expecting some explanation would surface eventually. Currently the validator has trouble with the License: lines – sometimes suggesting that the description is too long as well

thanks, now I have more work ensuring all my source files have both Copyright AND (currently missing from some) a statement of copying permission, saying that the program is distributed under the terms of the GNU General Public License.

Reporting Security Issues

While we try to be proactive in preventing security problems, we do not assume they’ll never come up. If you believe you’ve found a security problem in a release of WordPress, please see the Security FAQ for information on how to report the problem.

It is standard practice to notify the vendor (the WordPress security team, in this case) of a security problem before publicizing, so a fix can be prepared, and public damage due to the vulnerability minimized.

Overview of Bug Reporting and Resolution

There are many steps in the process of reporting and resolving a bug in WordPress. Here is an overview:

A user finds a bug that appears to be in the core of WordPress (not a theme or a plugin).

The user confirms it is actually a bug which has not yet been reported.

A WordPress developer (who is a volunteer, like you) confirms that the bug does actually exist, and that it should be fixed, and comments as such.

A WordPress developer (which could be you) decides to fix the bug. The developer figures out how to fix the bug, create a patch, and uploads the patch to Trac.

Members of the WordPress development community test the patch to see if it fixes the bug, and doesn’t break anything else. They may also run Automated Tests against the bug and patch, and write new tests (or suggest new tests be written).

One of the WordPress developers with authority to modify the official WordPress source code commits the patch to the core code in the SVN repository. They are more likely to do this if the bug and patch has been verified by someone they trust – WordPress development operates largely on a system of trust and merit.

The person who commits the patch closes the bug as fixed.

Before You Report a Bug

With large projects like WordPress, so many users report bugs that there’s a good chance your bug has already been reported. Because of this, it’s very important to check to ensure it’s not already in the system before you submit it. If you are new to reporting bugs in WordPress, it is also a good idea to discuss the issue with more experienced developers before reporting it.

1. Make sure the bug is actually caused by WordPress core.

Just because an error message points to a core file, doesn’t mean that’s where the problem is. You may want to use a plugin like Debug Bar to track down the problem. A simple script like this debugging file could help you see where exactly the error is coming from. (You can place this file in your wp-content/mu-plugins directory; create it if it doesn’t exist.)

Another key strategy is to try and replicate the bug in a fresh WordPress install with no extra plugins or themes. While this may not always be possible, if you can find it in a fresh install, the issue is much more likely to be in core.

If your issue has already been reported, please do not report a duplicate bug. If you have further information to contribute, add a note to the existing bug.

If your issue is similar, but not quite the same as another issue, you may decide whether to add a note to the similar issue, or report a new one. In general, if you just have more information to contribute to a current, open issue, simply add a note to that issue. If you have a different enough issue, or if you are experiencing a recurrence of an issue that was previously resolved, report a new bug. Either way, core contributors will offer you guidance once you’ve posted about your issue.

If your issue was recently reported and then closed, and you do not agree with the resolution, you can still post comments as to your reasoning.

It is best not to re-open bugs that have been closed for some time. If the bug was closed as fixed for a version of WordPress that has been released already (see the Milestone field), open a new ticket.

The Version field relates to the version in which the bug was originally discovered. If you’re seeing the same bug in a newer version, mention so in a comment, but please do not change the version number.

Reporting a Bug

Trac is the name of the official WordPress bug tracker. It uses the opensource bug tracking software Trac, by Edgewall Software. To learn more about Trac, see The Bug Tracker (Trac). To create a good bug report:

Fill in the title, summary, and other fields. For more, see the section on Ticket Properties.

Click Submit Ticket after previewing it.

Your involvement doesn’t end after you’ve submitted a ticket. Developers may need more information as they review the ticket (and may specifically request more information from you by tagging the ticket with reporter-feedback).

You can also help by verifying that proposed fixes solve the problem you were experiencing. The processing of your bug may require your participation, so please be willing and prepared to aid the developers in resolving the issue. If you’d like to help fix the bug, see the section on Fixing Bugs.

You will be automatically emailed when your tickets are updated if you’ve entered your email address in your Trac preferences.