Make WordPress Core

Updates from Aaron Jorbin Toggle Comment Threads | Keyboard Shortcuts

  • Aaron Jorbin 3:52 pm on March 31, 2015 Permalink |
    Tags: , ,   

    Screen Reader Text in output of comments_popup_link 

    As of WordPress 4.2, the output of comments_popup_link now uses .screen-reader-text in themes using the default strings in calls to comments_popup_link. The accessibility team has put together a post on hiding text for screen readers that includes sample code to use in your themes.

    I recommended that all themes include the .screen-reader-text class. This change was announced by the on the theme team blog in January. In the future, there may be more changes to output that relies upon the presence of the .screen-reader-text class.

    Related Ticket:

  • Aaron Jorbin 7:49 pm on December 16, 2014 Permalink
    Tags: ,   

    WordPress 4.1 Field Notes 

    The release of WordPress 4.1 is imminent. By now, you should have already been testing and preparing your plugins and themes. I wanted to highlight a couple of posts here over the last few months on changes in WordPress 4.1.  This is by no means a complete summary of everything that has changed, but will give you a sense of what you have coming to you in the next few days.

    This version of WordPress features some new template tags in a continued attempt to improve core’s Theme APIs.

    Taxonomy, Date, Meta and Comment queries all have been updated and improved.

    As a part of the taxonomy roadmap, When a term is created with a matching slug as an existing term, we now create a new entry in wp_terms.

    Distraction-free writing has received a full revamp.

    Themes now can have better support for the <title> tag

    There have been several improvements to the Customizer API, including contextual panels and sections, and JavaScript templates for controls.

    Please continue testing your sites, plugins and themes. WordPress wouldn’t be where it is without you.

  • Aaron Jorbin 4:50 pm on October 28, 2014 Permalink
    Tags: ,   

    WordCamp San Francisco User Testing Results 

    WordCamp San Francisco, @johnbillion and I conducted some user tests.  We focused on three feature plugins planned for 4.1: Focus, Author Select, Session Manager.  When possible, we created an editor account for users and had them participate on there own device.  When they didn’t have a device, they participated on one of our laptops.

    Below are the notes.

    Dan – developer. using a macbook

    “Wow” was first reaction to focus. Kind of felt like it was shocking and he needed some frame of reference. Maybe keep 5px or so of menu so you know you can go back to it. Fading of buttons kind of make it feel like they are disabled.
    Author select – Immediately knew what to do. super natural
    “Where are you logged in” – knew to go to profile page, found the panel right away.

    Michelle – designer/developer. using a macbook

    It’s disconcerting not to see all the things. “If the point of things is to be distraction free, it’s weird not to see publish since that is what people want to do”. Fading of buttons seems a bit weird. Not sure she like automatically going into distraction free. It’s jarring.
    Author select -didn’t search, just selected.

    Janneke – Developer. using an iPad mini

    Author select on iPad mini – Super hard to use. Can’t really scroll down. Not at all intuitive.
    Profile manager – Looks horrible on iPad mini
    Focus – She is building it, so I didn’t test it :)

    Josh – Developer. using a macbook

    Likes not having the sidebar menu. Losing the meta boxes seems odd. Might be weird for some people.
    Author select. Select 2. Using display name instead of user name. Seems odd.
    First looked to tools to find where he was logged in.

    Joe – Developer. using a macbook

    Lag on the editor screen makes things feel slow and confusing.
    Author – Not used to to having it enabled by default is different. Seems to be able to use

    Cory – WP business owner. using his macbook

    Loves the focus. Seems super natural.
    Author – Very usable.
    Profile – Didn’t quite understand question at first, but once he did, made it and found that info right away.

    Mel – designer. using our laptop

    Focus – It’s weird that it’s not centered. Less things on the page makes it harder to focus.
    Author – “I heart Select2″

    Jen –  Freelance writer and photographer. Has her own blog, using a MacBook.

    Initially wasn’t enthusiastic about the fact that the meta boxes and menu disappeared, “oh, what’s going on?”. Was confused about how to get them to re-appear, erroneously clicked an unrelated button in the browser in an attempt to get the UI to reappear. After figuring out that the UI re-appears when you move your mouse or tab away, actually very much liked the behaviour.

    I mentioned that we were considering adding a feature pointer pointing to the DFW button. Jen said she thinks this will be important. User has no other idea of what’s going on otherwise.

    Couldn’t find where the user sessions may be listed. Mentioned that she is the only user on her site so she would have no interest in it. Expected it to be on the dashboard, or on the same screen as Jetpack analytics.

    Christen –  blogger

    “Create a new post” – First went to quick draft. When I sent her to the regular draft screen, it seemed natural to her. She liked the “Distraction free writing”. It felt natural to her. Once it was in place though, she didn’t really look for anything else on the page.

    Andre – Theme Builder. Design and build.

    Focus Was natural. Really liked and it seemed 100% natural to him.
    Author – Select two was a natural choice and he really likes it.
    Went to tools page to find sessions.

    Matt – developer and project manager

    Not enthusiastic about using the editor focus improvements himself, but said he would leave it enabled for his clients who write more long form content than he does. Suggested that some form of A/B testing may be desirable if we have the time. No other feedback.

    User session list will be of interest to him as a project/site manager, not so much use to his clients themselves. Suggested that we could implement a dashboard widget which displayed the “last accessed” time for the current user, or listed other current sessions if there is more than one. Also suggested adding an “active sessions” column to the user list screen, visible to site admins.

  • Aaron Jorbin 5:26 pm on October 24, 2014 Permalink

    Feature Testing at WordCamp San Francisco 

    Getting feedback from real users is incredibly valuable, and WCSF occurs at a great time in the 4.1 dev cycle to do that. We will have a space next to the happiness bar to solicit feedback on upcoming features. In order to accomplish this, if you will be at WordCamp SF this weekend and want to get feedback on a feature that you are working on, please comment below.

    I will setup some test sites with trunk and the trunk version of the feature plugins (along with some test data) to help expedite this. The plugins I am planning on having are:


    If you can help with staffing this area, please comment below.

    • Drew Jaynes (DrewAPicture) 5:33 pm on October 24, 2014 Permalink | Log in to Reply

      I’m in to help test for a while.

    • Daniel Bachhuber 6:08 pm on October 24, 2014 Permalink | Log in to Reply

      I’ll co-opt people who come to visit me at the Happiness Bar to do some testing.

    • Avryl 6:14 pm on October 24, 2014 Permalink | Log in to Reply

      I can help too.

    • Ipstenu (Mika Epstein) 10:59 pm on October 24, 2014 Permalink | Log in to Reply

      I can help

    • Luke Carbis 1:35 pm on October 25, 2014 Permalink | Log in to Reply

      Happy to help staff the area. @lukecarbis

    • Nick Halsey 5:38 pm on October 25, 2014 Permalink | Log in to Reply

      I’m not there, but it would be cool if you have enough interest to test some of the non-4.1 plugins like the Front End Editor and Menu Customizer as well.

    • Ryan Boren 11:40 pm on October 26, 2014 Permalink | Log in to Reply

      Feature plugins should be updated every week in the plugin repo (every day would be even better). With the beta tester plugin, auto updating to each nightly is effortless. Following feature plugin development should be as convenient.

      • Knut Sparhell 1:57 am on October 28, 2014 Permalink | Log in to Reply

        I have the beta tester plugin, but not Twenty Fifteen. I have the session management plugin from Github, but not a one click update for it. I’m the dog and wordpress.org is the dogfood here.

    • Ryan Boren 1:02 am on October 27, 2014 Permalink | Log in to Reply

      Instead of just testing new stuff, have them show how they usually work. Capture real flows. Be an Alan Lomax of flow. Seeing how people work with and around our interfaces is very interesting. For example, Android users use the Android sharing mechanism to push images to the media library through the Android app. Later, they create galleries from wp-admin on the desktop. Why? Because creating galleries is impossible in the apps and painful on the mobile web due to things like lack of multi-select and aggravating tab switching in the media modal. Another example, some use upload.php to edit image meta because they can’t use the small input fields in the sidebar of the media modal. Those are revealing flows.

  • Aaron Jorbin 8:08 pm on September 29, 2014 Permalink

    Core Build/Test tools chat 

    I’ll be hosting a chat for Build and Test tools on Wednesday, October 8, 2014 2:00am UTC . The goal will be to triage and discuss the existing tickets along with identifying enhancements, new initiatives, and other improvements.

    Please comment below if you have any suggested build/test improvements that are not currently in a ticket.

    Note, that this may not be the permanent time for Build/Test tool chats. I know it isn’t ideal for everyone (especially Europe).

    • Rodrigo Primo 10:13 pm on September 30, 2014 Permalink | Log in to Reply

      Last WCSF during Contributor Day I worked with Bryan Petty to configure Travis CI on his fork of WordPress:


      The configuration file we created was incorporated into the official repository (https://core.trac.wordpress.org/ticket/26364). Any progress has been made after that towards having an official CI solution for WordPress?

      People are still using Bryan account for Travis CI or there is another CI service being used?

    • Rodrigo Primo 1:05 pm on October 2, 2014 Permalink | Log in to Reply

      Having an official CI service running somewhere would be great. But anyway it is good to know that you have configured Travis CI based on a mirror of the official repository. This is already very useful.

      I will try to attend the meeting next week. I’m available to help with build and test tools but I don’t know where to start.

    • Stephen Edgar 10:59 pm on October 5, 2014 Permalink | Log in to Reply

      Agenda Items: Tabs vs Spaces indentation for JSON files https://github.com/FlagshipWP/Compass/pull/11

    • Gary Jones 12:40 am on October 6, 2014 Permalink | Log in to Reply

      I’d really like to see configs agreed for the WP community as programmatic definitions of WP Coding Standards, even if they cant be used in core yet. Having them agreed means themes and plugins can be using them. Examples:

      Hopefully plugins and themes would adhere to these configs, but could always use theme as starting points if they needed to adapt them to their own situation. Having it seen as come from core gives it more weight than individuals doing their own (individual) thing.

      To clarify – I know WP core isn’t in a position to use all these, but I’d hope that this group discussion could get some technical agreements made for the benefit of the wider community, which core could then use at a later date.

      Instead of a single Gruntfile.js, I’d like to see a more modular approach, with each task put into it’s own file, such as seen in https://github.com/FlagshipWP/Compass/tree/master/grunt/config – the benefits are code that is easier to read, cleaner version control history, and potential code re-use. The Gruntfile.js then becomes setting up of paths and files variables, meaning a module like checking JSHint checking could be used in core and in plugins or themes, with no or few changes – setting a good example for the wider community.

      As it’ll be 3am in the UK, I’ll be unable to attend, but I hope my thoughts here can be considered.

    • K.Adam White 1:44 am on October 6, 2014 Permalink | Log in to Reply

      I may be unable to attend this chat due to a work meeting conflict, but I second most of what Gary says above: blowing the gruntfile into separate task files is definitely best practice, and I’ve been generally impressed with JSCS as a style-oriented complement to JSHint. We’ve got lots of fun opportunities to make working with the codebase easier!

    • Gary Jones 7:30 pm on October 6, 2014 Permalink | Log in to Reply

      Just to add to my earlier comments regarding discussion and potential agreement around configurations, particularly for coding standards and style, I think there should be two configs for each tool or area:

      1. An ideal-world configuration for tool X, that WordPress core and plugins and themes should ultimately be aiming to satisfy for coding standards and coding style.
      2. A real-world “this is what we can manage right now” config that WP core can satisfy in the short term, and a plan for how to get from here to the ideal config.

      Once the first is formally decided (ignoring the current state of any code), then these config files along with the verbose descriptions and examples can be added to the Handbooks, enhancing and filling in the gaps in the existing standards.

      As an example, an ideal config might say that each PHP class should go into it’s own file, to keep declarations and side-effect-causing code separate, as per PSR-1. Realistically WP might never manage that, and the real-world config committed to develop would reflect that, but having the endpoint agreed means that:

      • Plugins and themes, especially new ones, should aim for one-class per file.
      • New commits to core should follow one-class per file.

      I think it’s important to identify what we’d like the code in the WP community to be like, and how to programatically test against it, even if WP core itself isn’t going to get there in the foreseeable future.

    • Aaron Jorbin 1:59 am on October 8, 2014 Permalink | Log in to Reply


      • Tabs vs Spaces indentation for JSON files
      • Spliting up Gruntfile.js
      • css linting #29792
      • JSCS
      • Config files for additional tools
      • Open Tickets
    • Gary Jones 8:10 am on October 8, 2014 Permalink | Log in to Reply

      Chat logs: https://irclogs.wordpress.org/chanlog.php?channel=wordpress-dev&day=2014-10-08&sort=asc#m935953

      I wanted to write this post to record the type of thing I would have replied, if I had been able to make it.

      > I would want to see how badly we fail running jscs before knowing if it makes sense to include it or not

      I’m reading that as “If we suck at our own standards so much, we won’t bother trying to fix it”.

      > Would need to look at those Compass .jscsrc rules and compare with WP Core standards and see where there at for starters

      Definitely. I’ve explained above how that file is sectioned, and some rules are what I think are good practices but are not covered in the current textual description of the JS CS. Having a group of people look at it, decide which rules code in the community should be following and publishing that means themes (and plugins) like Compass can update their own .jscsrc to match and update their code accordingly.

      > In general, I don’t think we should include config files for tools we aren’t using in core

      I would agree with that; I never said that the discussion and agreement of various config files should result in them being added to core. As per my earlier comment above, what I propose is ideal world configs that everyone should be aiming at, and then each project (Core included) can just include / use the ones they want or are able to.

      > we shouldn’t tell plugin/theme developers what standards they should follow

      Disagree. As a community I believe we should be coming up with code standards configurations that are programatically testable and making an opinionated statement of CS that is applicable to all code within the community. Plugin and theme authors are free to ignore these standards if they wish, as some already do.

      The WP CS for PHP says:
      “Keep the following points in mind when writing PHP code for WordPress, whether for core programming code, plugins, or themes.”

      The WP CS for JS says:
      “JavaScript has become a critical component in developing WordPress-based applications (themes and plugins) as well as WordPress core. Standards are needed for formatting and styling JavaScript code to maintain the same code consistency as the WordPress standards provide for core PHP, HTML, and CSS code.”

      Both of those imply that the standards are intended to apply to all code in the WordPress community, not just core. The chat logs mention bbPress and BuddyPress both attempting to follow the standards too.

      > unless we are going to hold ourself to the same standards

      Core doesn’t follow it’s own PHP and JS standards, yet they are defined in the Handbooks. The point about having configs for PHPCS, JSCS, CSSLint/CSSComb are that these make the standards automatically testable, and cover ambiguous holes in the current wordy-descriptions of the standards.

      Core is just another project within the WP community, albeit the main one, so by having testable standards agreed *for the community*, Core can gradually and incrementally work towards satisfying those in it’s own time, the same as any plugins or themes that also want to work to them (and should be encouraged to).

      > I think we should move the discussion back onto make/core since at this point it is all hypothetical

      Aaaaand I think I’ve discovered the source of my frustration with this. Jorbin (quite rightly) is considering the practicalities of *Core* build and test tools. There doesn’t seem to be an obvious group of folks who are making decisions about standards at a higher level, for the whole community. Maybe my points here have missed the mark because of it. I’d like to help out with any such group, because I feel there is value in having testable code standards across all code in the community, that is not limited by the current situation of the main project.

  • Aaron Jorbin 5:28 pm on January 3, 2014 Permalink  

    #26669: wp-admin.css should be broken up into modules 

    During 3.8, we started to work on Adding a CSS preprocessor by using SASS for the color schemes in WordPress Core. We also had some great discussion about using a CSS preprocessor.

    Most of the ideas for where we want to end up (Either using a pre-processor like Sass or a post-processor like Autoprefixer) depend upon our CSS not being in a single file with over 13k lines.

    Something like this needs to be done early in a release cycle since it will 1) invalidate patches that are currently based on a single wp-admin.css file (though MP6 already invalidated almost all of them from before 3.8) and 2) creating a patch like this is time consuming and relies upon wp-admin.css not changing while the patch is being created.

    I’ve created ticket number #26669 and uploaded a patch which shows the grunt and script-loader changes necessary. These changes make it so the only difference you see when running WordPress from /src are that you have more css files being loaded in the browser. It will still work smooth.

    Please share your thoughts on splitting wp-admin.css up. Ideally we can make a decision on this during or before the January 8 Dev chat in order to get this in for 3.9.

    • Mel Choyce 5:33 pm on January 3, 2014 Permalink | Log in to Reply

      Yes please. I feel like splitting up the files would make it SO much easier to find where particular styles live, and definitely would have made me feel much more confident poking through the files when I started contributing to core.

    • bobfox321 5:45 pm on January 3, 2014 Permalink | Log in to Reply

      I think it necessary to make it easier for non or neophyte WordPress coders to figure out what works and what doesn’t in CSS. I really rely on examples from my use of TablePress. When I do my pre-modification review (faqs, forums, manuals, etc) to my tables I usually find answers. When I apply answers, particularly in CSS, they sometimes work and sometimes not. That is easier to understand than when they work one day and stop working the next.

      TablePress is an outstanding product but as always there are features I want that makes a difference.

      I understand the many conflicts between plugins and WP releases but something has to be done for us common WP affectionados that just want an outstanding Internet presence with our message.

      SO, please keep us in mind and make it easier and less technical so I do not have to hire expensive consultants.

      Thank you

    • Bryan Petty 5:47 pm on January 3, 2014 Permalink | Log in to Reply

      There was still some hesitation about making this move just yet until source maps were more widely available to use. We’re using grunt-sass now, and libsass only just recently merged in adequate support for sourcemaps, meaning it might still be a bit of time before it makes it into a stable release of grunt-sass. Not long mind you, likely just one more release cycle for WP.

      I’d say go ahead and start testing out your approach and coming up with your plan of attack, but I wouldn’t plan on it being merged in 3.9. There’s no need to rush everything.

      • Helen Hou-Sandi 5:55 pm on January 3, 2014 Permalink | Log in to Reply

        Where did you see concerns about concatenation and source maps?

      • Aaron Jorbin 5:58 pm on January 3, 2014 Permalink | Log in to Reply

        I don’t think source maps are a blocker to splitting up our css if you take a look at my approach. In order to make a change and test the un minified CSS, you would define script_debug to be true. From there, you would be served all the individual files (and thus have no need for a source maps).

        This is just the first step to make it so that when we decide on the next step (whether it is SASS, Autoprefixer or an entirely different approach), our code is already

        That said, we could use https://github.com/kozy4324/grunt-concat-sourcemap to generate sourcemaps. Though I’m not sure we want to ship the production version of WP with sourcemaps. We already don’t ship the ones that come with jQuery.

    • jackreichert 5:59 pm on January 3, 2014 Permalink | Log in to Reply

      On a similar note, if the CSS will be broken up, it would be nice to modularize it with OOCSS principals. Building in the back-end is somewhat frustrating since there are so many similar visual concepts being used, but not many styles that can be used across the board.

      • Aaron Jorbin 6:05 pm on January 3, 2014 Permalink | Log in to Reply

        A complete switch to something like OOCSS is out of scope for this ticket and change, but I think if we do it, moving in that direction would become much easier.

    • Dominik Schilling (ocean90) 7:19 pm on January 3, 2014 Permalink | Log in to Reply

      I’m fine with splitting this huge file up,..
      …but what are the real benefits of a interim stage – splitting one CSS into multiple CSS files – and not going directly into Sass partials? Just splitting it up because we can merge it later again doesn’t make sense for me.
      And maybe we should do a step back first and review our existing CSS rules, since there are some places with repeating style declarations. I’m sure, having multiple files with the same styles won’t make it easier.

      • Aaron Jorbin 7:56 pm on January 3, 2014 Permalink | Log in to Reply

        I think the benefits are:
        1) That it will be easier to work with, both for new and for existing developers since extremely large files are harder to work with.
        2) It will make it easier to move these into partials if we decide to go that route.
        3) Once we are in smaller files, we can look into tools such as csscss and csslint to find ways to optimize our CSS. Right now, running those tools on the single file produces so much content that it is almost impossible to be useful.

    • Bryan Petty 8:44 pm on January 3, 2014 Permalink | Log in to Reply

      I really do like this idea, and I’d love to see it happen, but feel the need to make a point about something that’s been bothering me lately since you brought this up. I can’t just create a new post, so I’m sorry I have to hijack your thread for it, even though it has nothing to do with wp-admin SASS.

      It would be nice if people had this kind of enthusiasm for basic maintenance tasks we’re way farther behind on, but made decisions on more than a year ago in some cases. For example…

      • What happened with reviewing @codebykat‘s GSoC work and finally resolving #22942 (Deprecate Post by Email)? At least it’s been in a merge-ready patch form since before the 3.8 cycle even started, and just appears to be stuck in the punt-cycle now. Kat dedicated months of (blessed) full-time work, and did an amazing and job on this, and it’s just being wasted now.
      • How about actually removing the link manager (#21307)? It’s been disabled by default since 3.5, and there used to be a progressive plan for having it completely removed and added to the official plugin replacement by 3.7 or 3.8 (and I’d link to that plan, but it’s buried deep in the recesses of IRC logs somewhere in a meeting I can’t find if my life depended on it). @wonderboymusic even had a full patch with a first pass ready for review 17 months ago too. But now that first step that was supposed to happen in 3.6 still hasn’t happened and everyone still just wants to talk about new features in 3.9 instead. Now that it’s disabled, no-one cares, but in case anyone hadn’t noticed, we’re still maintaining code and fixing bugs in the link manager.

      One of my complaints with these types of posts is that even though you did write a patch and created a Trac ticket for this, you haven’t even given it more than a couple weeks to soak before spamming everyone with it on the core P2, something most patch authors don’t have the ability to do. You’re dictating what tickets you think deserve the extra attention and should be a higher priority by announcing it here (and surprise, it just happens to be your own), all while tickets like the ones I mentioned above have been entirely neglected, and honestly, wp-admin SASS was going to get that attention regardless. It didn’t need this post for that to happen.

      Trac is literally a graveyard where patches go to die, and not because they’re bad patches. It’s because no-one will even spend the time to review them, let alone improve, and follow through with them. One of the reasons I’m convinced this happens is because everyone keeps getting distracted by whatever new shiny and exciting feature is being proposed on the P2 here. Why do you suppose you felt the need to repeat everything you covered in the Trac ticket here otherwise? It’s posts like this that are just discouraging anyone from actually taking the time to follow the activity and discussion on Trac itself rather than here. Everyone now feels like they can just post comments here instead, and they do as evidence of the 4 people already discussing it here without anything posted to the ticket still. Ideally, we shouldn’t even need a post here just for a Trac ticket to get some attention.

      • Andrew Nacin 10:09 pm on January 3, 2014 Permalink | Log in to Reply

        Let’s not hijack threads. If you want to have a conversation about this, feel free to bring it up in IRC. I’m always happy to talk.

        Jorbin made this post because to move this forward, it requires a discussion and decision about modernizing our development tools and workflows. That’s a very good use of make/core and it is something we’ve used make/core for for the past six months consistently. In these situations, Trac is more about proof-of-concept and later final implementation, not the higher-level discussion of which direction we want to take things, which touches on the needs and wants of designers and developers, tactics for deployment and testing, how it will impact contributions (methods and barriers), etc etc. Incidentally, Jorbin was also pointed here independently by me, Helen, and Koop, three people who have authored previous development workflow posts.

        Jorbin has been focusing on JavaScript tools and testing for some time now, so his time/focus/energy spent on this has little to nothing to do with any of the other tickets you bring up, and isn’t slowing down anything else.

        The Link Manager is still used by potentially millions of users and I don’t think we’ve spent more than a few commits maintaining it going back two or three years. If we’re going to remove it, we’re probably going to need to install and activate the replacement plugin on upgrade, which is not something we’ve done before and isn’t a fun thought. Post by Email probably requires the same thing. These things aren’t being neglected — 90% of it is done (Link Manager is off by default and there’s a new, better Post by Email plugin out there). It’s the final 10% aren’t priorities because we’re a little trigger-shy about the repercussions of ripping them out.

        In terms of Trac being a graveyard: Sergey made 5,022 comments to Trac in 2013. You made 184. Be the change you wish to see.

        • Bryan Petty 12:32 am on January 4, 2014 Permalink | Log in to Reply

          You know this isn’t the type of discussion that you can just casually knock out over IRC, and that asking me to attempt it is really just the same as asking me to shut up and go away. If that’s the way you feel, just say it. You’re telling me I can’t discuss how I feel about posts like this (on the post itself), but wonder why I don’t leave comments more often. Please don’t condense my project involvement down to comment count, against someone no-one else has ever been able to keep up with, who’s also had commit access for the last year. I wasn’t writing a personal attack against Jorbin.

          We already knew this was going to happen, and built the infrastructure to do it during the 3.8 cycle, there’s nothing left in terms of “modernizing dev tools and workflows” or deciding on any direction it needs to take anymore. We discussed, decided, and implemented all of that entirely already. All that’s left is how the admin SASS is going to be organized, who’s going to do it, and when (not if, and not how). That can all be done on the ticket, and if it can’t, the least Jorbin can do is let the ticket sit for as long as everyone else has to wait for their patches to be reviewed to find out before deciding it was time to escalate it here to pull in more help. Maybe it would be relevant for the P2 if it was about discussing SASS coding conventions going forward, but Jorbin didn’t even mention that.

          Regarding post by email and link manager, I’m fully aware of the implications of the decision to install and activate a replacement plugin on upgrade, and so was everyone else when it was decided that we would still do it before @codebykat‘s project was ever approved. Why would we even bother letting her spend months of work on it if we knew it was never going to be used anyway, especially as opposed to making room for another student with a project we could use? Are you saying her project was completely pointless after all now? Maybe you should tell her that, she’s just been sitting there waiting for a review on the Trac ticket, and no-one has told her otherwise, or explained why it keeps getting punted, so she’s still spending the time refreshing her patch as usual – expecting it to be applied anytime now.

      • Helen Hou-Sandi 10:10 pm on January 3, 2014 Permalink | Log in to Reply

        Some of this is a red herring. The people who would work on the aforementioned tickets/issues are by and large not the same people who would be involved in this kind of initiative. I agree in some ways about splintering discussions and who can initiate a P2 post vs. a Trac ticket vs. a mailing list discussion, but I disagree that this was going to get attention no matter what.

    • Aaron Jorbin 10:34 pm on January 8, 2014 Permalink | Log in to Reply

      During today’s dev chat, the decision to do this was made. After 3.8.1 I will be updating the patch and coordinating with Helen to get it committed.

      Thanks everyone for your comments and feedback!

      Chat – https://irclogs.wordpress.org/chanlog.php?channel=wordpress-dev&day=2014-01-08&sort=asc#m767547

  • Aaron Jorbin 9:10 pm on September 13, 2013 Permalink
    Tags: ,   

    JavaScript Unit Tests for Core 

    Recently WordPress added QUnit as a JavaScript unit testing framework and added its first JavaScript unit tests. I thought I would walk through how to run the tests and how to write tests so that we can increase our JavaScript test coverage. All of these are based upon using the develop.svn.wordpress.org checkout which is where the JS unit tests live.
    (More …)

    • Ryan McCue 1:37 am on September 14, 2013 Permalink | Log in to Reply

      For anyone who’s wondering what the hell is going on on Windows: You have to run grunt via the Windows command line, and you cannot run it via Cygwin. If you do run it via Cygwin, you’ll see random inexplicable errors and missing output. It’s pretty annoying (in fact, it stops me from using Grunt), but you can’t really do anything about it.

    • adamsilverstein 6:17 pm on September 14, 2013 Permalink | Log in to Reply

      Great post, thanks for keeping this moving!

    • K.Adam White 5:50 pm on September 16, 2013 Permalink | Log in to Reply

      For those on Windows, the “msys” shell that installs as “Git Bash” when you download the official Windows build of Git should work fine once you install the Windows build of Node.

  • Aaron Jorbin 5:32 pm on August 25, 2010 Permalink
    Tags: , ,   

    Plugin Developer Handbook Chapter List 

    Thank you to everyone that commented and help me brainstorm what is needed for a good plugin developer handbook. I’ve synthesized that information and have come up with the following chapter list / section plan behind the jump. Please let me know if there is anything you think I missed. Remember, this handbook is designed specifically for the task of Plugin development. It’s not designed to be the end all, be all guide to WordPress. It’s designed to help new plugin developers get to the point that they can build a plugin and assist existing plugin developers with finding the best practices for doing things.

    The next step is going to be to find authors for all of these sections. I’m going to be reaching out to a number of people to help out, but I’d also love to see some people volunteer. Please contact me @aaronjorbin on twitter or jorbin in IRC if you think you might be interested in writing a chapter or section. I’m going to be leaning on many of you, the experienced core developers and plugin developers.

    (More …)

    • Stefano Petroni 5:39 pm on August 25, 2010 Permalink | Log in to Reply

      Can’t wait to read it! :-)
      Thank you!

    • Jane Wells 7:23 pm on August 25, 2010 Permalink | Log in to Reply

      It would be great for volunteer authors to leave a comment on this post rather than using twitter etc. so that we can keep a record here.

    • Alex M. 7:39 pm on August 25, 2010 Permalink | Log in to Reply

      I assume you’ll want me to take oEmbed? If no one else steps up, I can also document some other APIs such as shortcodes, transients, or caching. My freetime is limited though, so don’t heap too much on me. 😉

      • Aaron Jorbin 7:35 pm on August 26, 2010 Permalink | Log in to Reply

        Alex, You were just the man I had in mind for oEmbed. I don’t want to over burden you, but may come back and ask for help on another after I’ve talked to a few others.

    • peterchester 1:22 am on August 26, 2010 Permalink | Log in to Reply

      This is great! We’ve been working on bits and pieces of something like this at our company (Shane & Peter, Inc.) with the intent of ensuring that we all abide by the same coding conventions.

      Is the idea behind this that developers would read the whole thing start to finish or that they would read a couple intro parts and use the rest of it as a look up index?

      • Aaron Jorbin 3:13 pm on August 27, 2010 Permalink | Log in to Reply

        Section 1 is largely going to go over basics and outside of the introduction, should be skippable/skimmable by experienced developers.

        Section 2 will hopefully be read by everyone. Section 3, pretty much the same though skimmable if you’re not storing any data.

        Section 4 will largely be a reference section.

        Section 5 will be used mostly for people releasing plugins publicly…which should be all plugin developers :)

    • mercime 8:21 pm on August 26, 2010 Permalink | Log in to Reply

      Hi Aaron, perhaps in tips or dev section, add list of tools/arsenals to create a plugin. like basic text editor, poEdit, FF with Firebug and Web Dev extensions, etc. Or maybe that’s too basic? :-)

    • Jacob Santos 8:53 pm on August 26, 2010 Permalink | Log in to Reply

      Well, I could probably write the entire 5th section if you need a draft.

      • Aaron Jorbin 9:16 pm on August 26, 2010 Permalink | Log in to Reply

        I’m going to Ping you in IRC one of these days. I think that at least one of the parts of Section 5 will be right up your alley.

    • Aaron Jorbin 9:17 pm on August 26, 2010 Permalink | Log in to Reply

      One Additional Section I forgot to add (Section 6 or maybe Appendix A) will be a list of tips, tricks, and notes from a wide variety of developers. That will be assembled and worked on much later.

    • John P. Bloch 9:44 pm on August 26, 2010 Permalink | Log in to Reply

      I’ve got WP_Rewrite like we discussed.

    • Stephanie Leary 9:53 pm on August 26, 2010 Permalink | Log in to Reply

      I wrote a basic walkthrough of SVN for people who’ve never used SVN before as part of the plugin chapter in my WP book. It has a ton of screenshots using Versions for Mac and Tortoise for Windows. If it would be helpful, you can have it.

      I think I also have the How to Get Help chunk.

    • Brian Layman 5:06 am on August 27, 2010 Permalink | Log in to Reply

      I’m up for the Short Codes entry if you need someone. Or one of the two other sections we’d discussed if needed…

    • Jay Fortner 1:11 pm on August 27, 2010 Permalink | Log in to Reply

      If you need anyone for Actions and Filters or Coding Standards – I’m here.

    • Marjorie Roswell 1:12 pm on September 17, 2010 Permalink | Log in to Reply

      Could this be placed on a wiki, so that names could appear next to the actual chapters? Might make it easier to see what’s left to claim.

  • Aaron Jorbin 8:22 pm on July 22, 2010 Permalink
    Tags: , ,   

    Plugin Developer Handbook Planning 

    I’ve started brainstorming ideas for the plugin developer handbook and have come up with a pretty long list of topics that I think should be covered. Some of these will be chapters on their own, some will be combined together and others still need to be thought of. For right now, the best feedback you could give me is to tell me what I missed and what you think might be out of scope.

    A couple of notes:

    • I tried to include chapters so that both novice and experienced developers will be able use it. Hence ideas such as knowing the difference between the different languages used in WordPress.
    • Some things, while listed, I think will include warnings and language that discourages it. The two that stand out to me are: Custom database tables and Custom Option Pages.

    Alright, now for the list:

    • Introduction
    • Languages of WP – Differences between PHP, HTML, CSS, JS
    • WP Coding Standards
    • Organizing plugin files
    • Planning your plugin
    • Name Spacing
    • Adding Styles and Scripts
    • Actions / Filters
      • How to use them
      • How to add them to your theme so other plugins can use them
    • Shortcodes
    • Widgets
    • Front End Forms
    • Ajax
      • Front end ajax
      • Back End ajax
    • Roles and Capabilities and users
      • Custom caps
      • User Meta
    • Comments
      • Comment Meta
      • interacting with comment filters
    • Options
      • Adding options to existing admin pages
      • Adding your own pages
    • transients
    • Translating / Internationalization
    • Custom Taxonomies
    • Custom Post Types
    • Scheduled events (pseudo-cron)
    • Activation / Removal hooks
    • Interacting with the database
      • Adding Tables / interacting with them
    • Security
      • Kses
      • Escaping
      • Capabilities check
      • Nonces – Props Eric
    • Interacting with remote URLs
      • atom / rss
    • Interacting with WP_Query
    • Media
      • Media and Post relations (Send to editor)
    • Modifying / Creating URLs
    • MultiSite specific Compatibility
    • General Tips / Tricks / Notes (Ideally a tip or two from many different devs)
    • Adding Admin Notices
    • Giving your plugin the WordPress look (Hopefully the style guide will be finished before then).
    • Pluggable Functions
    • Admin Meta Boxes
    • Dashboard Widgets
    • Extending Tiny MCE
    • A Good Development Environment
    • Development Process
    • Mike Schinkel 8:25 pm on July 22, 2010 Permalink | Log in to Reply

      Wow, that’s an incredibly good list. Kudos.

      I think that to improve that list will probably take just working on it to realize what’s missing but otherwise it’s incredible.

    • Rahul Bansal 8:30 pm on July 22, 2010 Permalink | Log in to Reply

      Such a handbook will be a real treat for plugin developers.
      Being in business, I keep hearing from developers that wordpress codex is too primitive and wordpress lacks documentation a CMS need to win enterprise userbase.
      I guess such handbook can fill that void.

    • Eric Marden 8:59 pm on July 22, 2010 Permalink | Log in to Reply

      I’d also cover functions.php. While a theme file, the techniques are largely the same.

      • Aaron Jorbin 9:22 pm on July 22, 2010 Permalink | Log in to Reply

        I think the eventual Theme dev handbook will cover that more (and will share alot of chapters/sections with this handbook)

        • Eric Marden 9:24 pm on July 22, 2010 Permalink | Log in to Reply

          I think its a topic worth touching on in Plugin Dev Handbook, but covering fully in Theme Handbook.

        • Aaron Jorbin 9:27 pm on July 22, 2010 Permalink | Log in to Reply

          How do you think it should be covered? What in do you think plugin devs need to know about theme functions.php files?

        • Mike Schinkel 9:31 pm on July 22, 2010 Permalink | Log in to Reply

          For one, functions.php is a great place to start testing out proof-of-concept functionality that may be later moved into a proper plugin. Discussing that and the process of moving from proof of concept testing to actual plugin might be helpful.

        • Aaron Jorbin 9:50 pm on July 22, 2010 Permalink | Log in to Reply

          I’ve added a section on development enviorment that could probobly cover that unless there is something else I am missing?

          I think I’m also going to add a Development Process section.

        • Mike Schinkel 9:58 pm on July 22, 2010 Permalink | Log in to Reply

          Good idea. Elaborating, it would be nice to talk about setting up a local development environment on at least Windows, Mac OS X and generic Linux.

        • Eric Marden 10:00 pm on July 22, 2010 Permalink | Log in to Reply

          I’d say that it should probably cover:

          • The differences between functions.php and plugin files.
          • What’s available and not available to you in functions.php
          • When you should use it instead of a plugin

          Then point folks to the theme dev hand book.

        • Aaron Jorbin 4:55 am on July 23, 2010 Permalink | Log in to Reply

          Eric – I think the first and the third parts would be good, I think the second is straying a bit too much into theme development and might be out of scope. This is designed to be one in a series of handbooks with the focus specifically on Plugin development. While a lot of the information within this handbook will also be in the theme developer handbook, I’d prefer it not confuse the two too much.

          Mike – That’s exactly what I meant by setting up a development environment. I imagine that section is going to be heavy on links and lighter on content though.

        • Eric Marden 2:26 pm on July 23, 2010 Permalink | Log in to Reply

          Aaron – Sounds good to me. As long as their some mention of it, and pointers to more, I think it will help people avoid confusion and concur that you get into theme land pretty quickly when using the functions.php bridge.

          Mike – I agree with Aaron here, Dev Environment, while useful, is a bit out of scope. Pointing people to some good links is best, but this topic, I feel, should only be touched on in the scope of why its a good idea, not how to make it happen.

        • Mike Schinkel 2:35 pm on July 23, 2010 Permalink | Log in to Reply

          @Eric: While not completely disagreeing I will say that the biggest “hump” I had to get over before I could finally be productive was getting a dev environment set up (I had been on Windows+ASP+IIS+SQL Server for 10+ years so LAMP/WAMP/MAMP was all foreign to me.) After I finally was able to get help getting it all set up (3+ years ago, for Drupal at the time) I was rapidly able to gain relevant skills because each step was such a small step from the one before compare with the initial setup. I’ve also taught a lot of people WordPress over the past 2 years (~100 people) in workshop environments and the most important step for almost all of them is getting the development environment set up. So given how little one can do without it compared to with it and given how big a hurdle it can be to set up I would suggest we at least consider giving it more weight than we might otherwise give it if it were not such a critical path to productivity. JMTCW.

        • Eric Marden 7:22 pm on July 23, 2010 Permalink | Log in to Reply


          While I don’t disagree that a local development environment is a huge boon to productivity and is an important topic, it starts to delve into the area of systems administration – one of the reasons I feel that a lot of new developers struggle with it, avoid it, or don’t even know they should or could have a local server. What I’m suggesting is limiting the topic to just the essentials and letting other sources deal with all of the other variables.

          In other words, it could look something like this:

          • Here’s WAMP (windows)
          • Here’s MAMP (mac)
          • Here’s apt-get (linux)
          • Here’s how to configure a VHOST to serve one WP site.

          As soon as we try to help them worry about multiple virtual hosts, the specifics of configuring Apache, managing the /etc/hosts file for overriding DNS this topic soon becomes unwieldy and given that it is not essential for you to have one to develop a plugin we shouldn’t try to create even a shadow of a full blown HOWTO on the topic.

          Trust me, I’m the guy who has stepped in on a project and wouldn’t write a single line of code until the entire team got a local dev environment installed. But if there’s one thing I know about this topic is that getting the perfect set-up is almost impossible and the way they other guy did it is always “wrong”. Do I hand compile or use a package manager? Install binary components myself and tie them together in the configuration? A virtual machine with ubuntu? Or use a prepackaged all-in-one solution? Even the level of choice in this area, as you can see, can be overwhelming on its own and we haven’t even begun to tell you which steps to follow.

          Another reason to err on the side of simplicity (and letting other sources guide the users more deeply) is that anything put in this handbook will end up generating questions on the forums, #wordpress and wp-hackers and shouldn’t we really be in the business of supporting WordPress and not their (particular) local server?

          My 2 cents,


        • Mike Schinkel 10:34 pm on July 23, 2010 Permalink | Log in to Reply

          @Eric Fair points.  

          One thing that I would personally like to see is it be _comprehensive; that would have helped me so much 2 years ago and I’d like to see others not have to go thru the same. If topics are collectively deemed as being too much of whatever then I’d argue at least that we cover the topic by curating a list of articles and solutions even if they point off WordPress.org. Then, for example, we could find a multiple VHOST article that covers concerns related to WordPress or if one can’t be found then one of us could write one on our blog and link to it. FWIW multiplier VHOSTs were one of the more difficult things to figure out yet one of the ones I cannot image being without today. Ironically it was really not difficult, I just had to learn a few arcane details. those details would make a great article.

          As for the other comment you made let me relate a story and I apologize that it is off topic for the develop handbook. Shortly after graduating college, probably 1992 I attended a presentation to entrepreneurs where the message hit home and has stuck with me for my adult like. In a nutshell the person made the point that if you have something you are “selling” (in our case we are all advocating for WordPress) then it is in your win best interest to make sure the prospective customer has as easy a time being able to acquire and use your solution as possible. If there is anything that would cause prospects to stall and go elsewhere, or simply not “purchase” at all then it is incumbent upon you to handle that problem for them or at least make the problem appear to go away.  

          So yes one can argue that we want to support WordPress only and not help people with their server setups and from a standpoint of purity you would be right. OTOH if we in fact do care about seeing a lot more people adopt WordPress then such perspective may be self-defeating. Note that the solution may not always be to “brute force” it but instead may be to divide and conquer (i.e. maybe we solve the problem by working with web hosts to minimize the problems, educate prospective users on which hosts have the least problems and then provide support for the remaining.) JMTCW.

        • Tim 10:54 pm on July 23, 2010 Permalink | Log in to Reply

          Discussion of Dev Environments, to some degree, would be good. Rather than focusing on specific environments, maybe a better way to approach this section in the handbook would be to encourage standardized ways of reporting what versions of WordPress (version number and single vs. Multi-Site testing), PHP and MySQL a plugin has been tested on. Right now, there’s a “tested up to” tag in the plugin header, but there isn’t a consistent way to report PHP/MySQL version requirements.

          Or perhaps this belongs in a new section covering “Writing a good readme file”?

        • Matt 11:07 pm on July 23, 2010 Permalink | Log in to Reply

          Small handbooks, loosely joined.

        • Aaron Jorbin 1:57 am on July 24, 2010 Permalink | Log in to Reply

          Anything more then a passing reference is going to be too much. I don’t want this devolving into a 800 page coffee table book that no one actually reads.. It’s for WordPress Plugin Development, not system administration. Perhaps there will be another book focused on that.

    • Eric Marden 9:00 pm on July 22, 2010 Permalink | Log in to Reply

      Also don’t forget to talk about nonces. Probably under security and/or options pages.

    • Denis 9:05 pm on July 22, 2010 Permalink | Log in to Reply

      I think you’re missing an important bit: the WP flow, with an outline of the hooks and when they occur, in what order, what they’re used for, etc. And most importantly, how to not interfere with other plugins on the same hook… (eg never call remove_action(myhook, myfunc) on myhook.)

      • Aaron Jorbin 9:26 pm on July 22, 2010 Permalink | Log in to Reply

        I think the API reference is going to more so cover flow. The actions section will definitely cover proper use of actions and priority.

    • Eric Marden 9:25 pm on July 22, 2010 Permalink | Log in to Reply

      Media probably covers this a bit, but overriding the javascript send_to_editor was a recent find of mine and is worth covering. I’m guessing there are other Javascript ‘hooks’ (timymce stuff?).

    • Aaron Jorbin 9:48 pm on July 22, 2010 Permalink | Log in to Reply

      Pluggable Functions
      Admin Meta Boxes
      Dashboard Widgets
      A Good Development Environment

      • Eric Marden 10:09 pm on July 22, 2010 Permalink | Log in to Reply

        • PHP Docblocks
        • Licensing and Distribution
        • Promoting your Plugin
        • Best Practices with JS/CSS (like not using !important in your CSS, etc)
        • PHP Best Practices ( i.e. Coding with E_ALL on, avoiding common Notices/Warnings)
        • SVN
        • Releasing your Plugin on WP.org
        • ReadMe.txt and plugin comment header
        • Data Import/Export
        • Migrations (WP_RELOCATE)

        Obviously we’re getting into the minutiae now, and some of this stuff can be and probably is implied by some of what’s above, but thought I’d offer them up anyway. Also some of this may be running into other hand book territory.

        Is this going to be collaboratively written, and if so where and on what platform?

        • Aaron Jorbin 4:59 am on July 23, 2010 Permalink | Log in to Reply

          I’m not sure if migrations would really fall under the purview of a plugin developer. I think that might fit better for a WordPress administrator book.

          For Import/Export, I assume you mean import/export of plugin data. Correct?

        • Ryan McCue 1:12 pm on July 23, 2010 Permalink | Log in to Reply

          Apologies for the off-topic reply, but what precisely is WP_RELOCATE? I can’t find a reference to it anywhere in code, and there’s only one reference to it on wp-hackers.

      • Eric Marden 2:33 pm on July 23, 2010 Permalink | Log in to Reply

        Ryan – sorry its RELOCATE, documented here: https://codex.wordpress.org/Changing_The_Site_URL#Relocate_method

        Aaron – You may be right. I continue to suggest things from a more holistic WP Developer mind set. Maybe we need a handbook that integrates admin, theme, and plugin from a top down approach, where these topics so far have been a bit more ground up. (small component effecting larger whole).

    • Mike Schinkel 10:01 pm on July 22, 2010 Permalink | Log in to Reply

      Floating an idea. This could turn out to be a killer book if packaged as such, and might catch interest if available at major bookstores from people who might not otherwise dig into the topic. What about coordinating with a major publisher where the proceeds go to the WordPress Foundation? Again, just an idea to consider.

      • Matt 10:44 pm on July 22, 2010 Permalink | Log in to Reply

        We can cross that bridge when we get there. I wish all of the WP books thus far had been under an OS license but most authors aren’t going to have that sort of leverage with their publisher. I had one tell me “books are hard, why would we allow anyone to take the content!” Yes, ma’am, software is hard too. :)

        Now we’re completely off-topic, but here’s a link everyone should read:


        • Mike Schinkel 11:12 pm on July 22, 2010 Permalink | Log in to Reply

          Yep, the idea is definitely premature but I figured it would be better to have in the back of our minds if doing so was an option. FWIW.

        • Stephen R 3:05 am on July 25, 2010 Permalink | Log in to Reply

          There’s an SVN book that is… not sure if it’s open source but they givve it away for free on the web site, or you can buy the physical book from O’Reilly. S not totally without precedent in books.

    • mercime 5:31 am on July 23, 2010 Permalink | Log in to Reply

      Plugin which create table/s in DB to add Uninstall function

      • Aaron Jorbin 11:53 am on July 23, 2010 Permalink | Log in to Reply

        That is part of the reason that people will be encouraged to use the existing data structures whenever feasible, but yes, that will be a part of custom tables.

    • João Pedro Pereira 10:21 am on July 23, 2010 Permalink | Log in to Reply

      Excelent list, Nothing to add besides TEST, TEST, TEST!

    • arena 11:39 am on July 23, 2010 Permalink | Log in to Reply

      Hi ! your list lacks structure.

      Most of the topics are related to the numerous wp api’s

      i would add the following topic
      . admin (menus, admin pages, clean coding (not loading js or css if current admin page is not related to plugin))

      • Aaron Jorbin 12:00 pm on July 23, 2010 Permalink | Log in to Reply

        Actually it does have structure, it’s an unordered list with list items that sometimes contain unordered lists :)

        For menus, I assume you are referring to interacting with the new nav menu items?

        Clean coding will certainly be a part of the WP coding standards and proper use of wp_enqueue_script / style (i.e. adding it to the right hook) will definitely be a part of the adding styles and scripts section.

    • filosofo 3:31 pm on July 23, 2010 Permalink | Log in to Reply

      Who is the proposed audience, and what do you see as the niche for this document in a world of grep, googling, and the Codex? It would be good to determine that before investing too much time in the wrong topics or too many details.

      Languages of WP – Differences between PHP, HTML, CSS, JS

      I don’t know the exact intended audience, but if it’s “developers” by any reasonable definition it should exclude someone who doesn’t know the difference between PHP and JS. That person needs to be doing remedial programming–maybe read Master PHP in 24 Hours or whatever—first.

      • Admin Meta Boxes
      • Dashboard Widgets
      • Extending Tiny MCE

      I suspect that’s the kind of detail that won’t do any potential audience much good. If you’re at the place that you’re ready to extend TinyMCE, you’re just going to google how to do it. If you’re new to WordPress plugin development, being blasted by a firehose of details will probably impress upon you the potential of WP, but it’s unlikely most of those details will stick. Or worse, the wrong details will stick to the detriment of more important ones.

      My suggestions: make the audience to comprise those with a reasonable knowledge of PHP, MySQL, and JS; neither beginners nor those who have an advanced knowledge of WP in particular. The former need more than you could possibly provide, and the latter don’t need your help.

      And don’t think of it as an academic course, in which someone can dedicate a semester to studying every topic. That’s not how most developers with jobs learn. Instead, pick a few truly core concepts, the ones that are necessary and sufficient to getting a typical plugin running. Then you can let code examples hint at some of the other details: they will be enough to spark interest without making the reader feel unduly burdened.

      • Eric Marden 7:31 pm on July 23, 2010 Permalink | Log in to Reply


        I think that this plugin should serve more than just beginners. Even a mention of what’s possible (by covering all of the various extension points in WP) and cross linking to the function reference in the Codex will be a huge help to all developers, beginners and advanced alike. I, for one, am a bit sick of having to grep the code base just to look up a function signature or having to trace the code to discover that there is an undocumented filter buried in the middle of one of the functions that get called – the exact filter I need to write my plugin cleanly. I kind of see this handbook as a part comprehensive overview and part getting started guide.

        However, I do agree that a discussion on the difference between various languages and technologies used in the construction of a WP plugin is unwarranted and does provide a small barrier to entry for this part of the docs. Right now all the Codex has is this: “WARNING: Programming Code Ahead!” or something like that.

        • filosofo 7:43 pm on July 23, 2010 Permalink | Log in to Reply

          I think that this plugin should serve more than just beginners. Even a mention of what’s possible (by covering all of the various extension points in WP) and cross linking to the function reference in the Codex will be a huge help to all developers, beginners and advanced alike.

          Well, I guess it really depends on what the purpose of the handbook is supposed to be (its niche). To me what you’re describing sounds more like an annotated index of the Codex, or maybe even just the Codex already. That would seemingly be only a quantitative, not qualitative change from what’s already available.

        • Aaron Jorbin 2:25 am on July 24, 2010 Permalink | Log in to Reply

          I view this as being a compliment to the API reference, but more focussed on Narrative explanations and explaining full API sections. While the API reference will tell you that register_taxonomy is used to create or modify a taxonomy object, and what arguments it takes, the handbook will explain what you can do with that taxonomy after it’s created.

          Will someone like you, who has a deep knowledge of the code turn to the handbook first? Doubtful. I imagine you’ll find what you need in the code. Might you turn to it if you have never used the HTTP api and want to get an idea of some best practices and a understanding of how you can use that in concert with Simple pie? Perhaps. Will someone building there first through fourth plugin find it useful? Absolutely.

          The reason I have the differences between languages is in part to help weed out the people that aren’t willing to learn more. I don’t view that as being as very long section. I imagine it being similar to http://aaron.jorb.in/blog/2010/01/you-better-know-the-basics/ , but better written. Then a simple: “Not scared to continue? Well onward to Victory!”

          For some of the sections (like TinyMCE editor), I actually think it might be best to keep it simple and point them to a small handfull of plugins that are doing it so that they can read some actual code. That’s open for thought though

    • jeremyclarke 4:56 pm on July 23, 2010 Permalink | Log in to Reply

      This looks great!

      It’s a small detail, but It seems to me that the “Actions/Filters” section should come before “Adding Styles and Scripts”. As far as I know, adding styles/scripts is done through the API so knowing how the API works first is probably a good investment 😉

      I’m pretty sure you would have changed it during the writing but figured I’d mention it as an excuse to tell you the list looks great and I’m excited for the result :)

      • Aaron Jorbin 3:55 am on July 26, 2010 Permalink | Log in to Reply

        The order above was in no way meant to imply the order the chapter would actually come in. It’s more so the order I brainstormed them in.

    • Jacob Santos 8:35 pm on July 23, 2010 Permalink | Log in to Reply

      It would be better to organize it in two or three sections.

      • Plugin System
      • How to Develop
      • WordPress Library Guides

      The Plugin System should include the introduction, what filters and actions are, how they work, how to add action and filters. Why and how they might be added to your themes and plugins.

      How to develop section should include WordPress coding standards, Subversion, WordPress Extend, adding plugins, checking out, how to work with the support and Trac Ticketing. Could also include notes on PHP docblocks, unit testing, and general ui testing.

      The WordPress Library Guides will include the large portion of the guide which would include every individual API section in WordPress and WordPress Admin.

      • Aaron Jorbin 3:59 am on July 26, 2010 Permalink | Log in to Reply

        My next step is actually to synthesize all this feedback and try to come up with a more coherent outline. What you’re proposing is pretty similiar to what I have in mind. Thanks Jacob!

    • bentrem 2:08 am on July 24, 2010 Permalink | Log in to Reply

      Are you setting up to co-author? Cuz I’ve been following DAV since *blush* a long time (see MozDawg on DAV and Docs, notes for which I started shortly after Netscape “released the code”.) Reason I ask: however slow the progress, progress there’s been. Now my first instinct was to shout out “This is a good start on a wiki page!” but I choked it back with something like, “Yaaa … yet.another dusty bit-rotted wiki page”.
      Social dynamics.
      Too bad GWave and GBuzz suck so completely when operationalized.
      p.s. I got started Analogous Techniques next month but my “army of 1″ batteries are flat / dead.

    • Stephen R 3:10 am on July 25, 2010 Permalink | Log in to Reply

      I think this is a really excellent idea. Part of the problem is making sure it will be updated over time and not grow stale == a problem oftentimes in Codex.

      Something you might add: a section on “final polish” — little things like adding the “Setup” link from the Manage Plugins page straight to your settings page. There are lots of little useful touches that aren’t purely core function of the plugin, but just make it a lot nicer in the details.

      • Aaron Jorbin 4:01 am on July 26, 2010 Permalink | Log in to Reply

        That tip is one that I think would be perfect for the General Tips / Tricks / Notes section. At a later date and time I’ll solicit those.

    • Ramon Fincken 1:30 am on July 26, 2010 Permalink | Log in to Reply


      Perhaps handy:
      Scheduled events (pseudo-cron) + Ajax frontend > http://www.ramonfincken.com/permalink/topic187.html

    • Mike Schinkel 3:42 am on July 27, 2010 Permalink | Log in to Reply

      I see you have transients (Transients API?[1]) but I don’t see any reference to the Settings API[2]?

      [1] https://codex.wordpress.org/Transients_API
      [2] https://codex.wordpress.org/Settings_API

      • jeremyclarke 3:01 pm on July 28, 2010 Permalink | Log in to Reply

        I think he just didn’t refer to it as the Settings API but he has:

        * Adding options to existing admin pages
        * Adding your own pages

        I think the first one would be the Settings API. Though its a good point that the section about adding settings pages should refer to the Settings API by name so that its brand is strengthened.

    • Byron 3:34 am on July 28, 2010 Permalink | Log in to Reply

      This Handbook is badly needed. It could seriously raise the average quality of WordPress plugins (my own could have benefitted tremendously when I start out a year-and-a-half ago). If it wasn’t for Vladimir Prelovac’s plugin book, I’d still be trying to start fire with sticks. Will this be open to contributors?

    • Jeff Sayre 3:04 pm on July 28, 2010 Permalink | Log in to Reply

      Aaron –

      Have you seen my article on WordPress action and filter events (hooks)? It could be useful for part of the information in the section on this subject. I have also created a plugin developers’ tool called the WordPress Hook Sniffer plugin. I just released an updated version this morning.

    • Marjorie Roswell 1:03 pm on September 17, 2010 Permalink | Log in to Reply

      Some questions that come to mind: Where should we look for the handbook? Online? In print? When? Will the handbook be available in draft form as its being developed?

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc
Skip to toolbar