WordPress.org

Ready to get started?Download WordPress

Make WordPress Core

Tagged: handbooks Toggle Comment Threads | Keyboard Shortcuts

  • Jen Mylo 7:10 pm on November 9, 2010 Permalink
    Tags: handbooks,   

    FYI, Daisy Olsen is going to head up the theme developer handbook. She’s started working on an initial outline/TOC. Anyone want to volunteer in advance to help with it?

     
    • Eric 7:40 pm on November 9, 2010 Permalink | Log in to Reply

      I’ll volunteer in advance to be a sounding board for it.

    • Tim 8:43 pm on November 9, 2010 Permalink | Log in to Reply

      I’ll volunteer to help with writing/editing or anything needs to be done.

    • Jim Doran 9:38 pm on November 9, 2010 Permalink | Log in to Reply

      I’m interested in helping.

    • David Cowgill 11:24 pm on November 9, 2010 Permalink | Log in to Reply

      I’ll volunteer to help Jane. My voice will be from a theme developer’s standpoint. Just let me know when and where.

    • Daisy Olsen 2:13 am on November 10, 2010 Permalink | Log in to Reply

      I’m looking forward to seeing this project take shape. I look forward to working with you all :-)

    • Chip Bennett 3:15 am on November 10, 2010 Permalink | Log in to Reply

      I would be more than happy to help. I would be happy to contribute anything that I can, and am also interested in ensuring that the handbook and the Theme Repository review guidelines are consistent with the handbook, and vice versa. But in any case, I’ll help in any way I can.

    • jim doran 3:55 pm on November 10, 2010 Permalink | Log in to Reply

      I can help, too. Editing, writing, etc. (I tried to post this comment yesterday – hope it didn’t end up in spam).

    • Laurie M. Rauch 10:11 pm on November 23, 2010 Permalink | Log in to Reply

      I would also be interested in helping – writing and/or editing. Please don’t hesitate to contact me. :)

    • Tom 2:28 pm on November 25, 2010 Permalink | Log in to Reply

      I’ve been looking for a way to contribute. Please add me to the list of volunteers.

    • Ed 11:34 pm on January 6, 2011 Permalink | Log in to Reply

      Count me in too. I can assist with writing/editing on anything theme related!

  • Andrew Nacin 8:56 pm on August 26, 2010 Permalink
    Tags: , , handbooks   

    What do core contributors need to know? 

    I’ll be working on an outline for the core contributor handbook in the coming weeks, so I figured I would start a brainstorming session here. Some potential questions to ask yourself:

    • What do core contributors need to know?
    • What would have been great to know when you first started getting involved?
    • What resources (such as pages on the Codex) have you found useful?
    • What do people (including/especially non-contributors) need to know about the development process/cycle/philosophies?
     
    • Ozh 9:05 pm on August 26, 2010 Permalink | Log in to Reply

      Adam’s http://adambrown.info/p/wp_hooks/ is pretty hot

      Emphasis could be made on the Codex, too. I started coding plugins before there was a Codex, which then was pretty empty at its beginning so I never really used it. It’s just recently that I’ve discovered it again, and found it very very useful.

      • Andrew Nacin 9:37 pm on August 26, 2010 Permalink | Log in to Reply

        This comment is arguably better for http://wpdevel.wordpress.com/2010/08/26/api-status-check/. I’ve actually reached out to Adam with regards to his hooks DB, as we hope to integrate a hooks reference as part of the API reference.

      • Brian Layman 9:52 pm on August 26, 2010 Permalink | Log in to Reply

        Unfortunately Adam’s site is causing loads of extra work now as it is still big in Google but his automated code has identified many actions and filters as removed due to fine tweaking. I see people asking about it on wp-hackers and you and I chatted about it one of the reports on it Andrew.

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

          Indeed, which is partly why it would be helpful to have a similar automated reference that is official and more complete. (And can be properly vetted by core folks.)

    • John James Jacoby 9:07 pm on August 26, 2010 Permalink | Log in to Reply

      How to use trac the WordPress way (keywords, tags, etc…)
      What is SVN? What do checkout/update/commit really mean and who can do that and why?
      How create a diff/patch, and how to attach a diff/patch to a trac ticket.
      General blog/chat/trac etiquette and community expectations.
      WordPress coding standards is a helpful codex page.

      There are probably more, but these are my few to start.

    • zippykid 9:09 pm on August 26, 2010 Permalink | Log in to Reply

      1. just a quick reminder on how to search the archives :).
      2. history of some decisions (see #1)
      3. coding standards
      4. contributing etiquette
      5. Triage process

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

        I think #2 is a good idea. There are a few areas that are/were asked repeatedly on the wp-hackers mailing list that would be good to just link to. It wouldn’t mean it is set in stone, but it would provide some reasoning for people on where to leave off when continuing discussions.

    • Kenny Younger 9:22 pm on August 26, 2010 Permalink | Log in to Reply

      I always knew the trac mailing list was available, but it wasn’t until recently that I started subscribing to it that I started to really appreciate the workflow in trac – mainly because it’s now literally at my fingertips (email on my phone).

      I just have gmail filter it off into its own label, so it doesn’t clutter my inbox (I actually do this for all the lists). One of the huge benefits is that I can drop into that label and then very quickly see what tickets are getting heavy commenting/changes. Plus I can star items that I feel I want to pay attention to more so than others.

      Another added benefit: quick searching from my phone for a particular ticket’s history.

      • Andrew Nacin 9:39 pm on August 26, 2010 Permalink | Log in to Reply

        My current workflow is very similar to this, though long ago I spun that label off into its own inbox. Even when I’m at my computer, I often use Gmail search to find tickets.

        Talking about different ways to absorb the firehoses of information, if you are so inclined, is a good idea.

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

      Requirements for patches. Adding / Modifying inline documentation and changing existing documentation when changing requirements. Writing Unit Tests. Expectations of the time for patches to get committed. What to do when there isn’t any feedback? What to do when patches don’t meet expectations.

      What it means when someone from Automattic doesn’t like your patch and therefore doesn’t gain traction. Who’s who at Automattic and WordPress core community that might need to be looked for and debated for certain patches to get in.

      • Andrew Nacin 9:36 pm on August 26, 2010 Permalink | Log in to Reply

        s/Automattic/WordPress core team/. That said, a who’s who is important, especially given the number of committers, contributors, and those who triage.

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

          No, I mean Automattic. They have just as much power, most of the time, as core commit team with what goes into WordPress. There are people at Automattic who have certain areas of expertise and core commit team has historically relied on their opinion over that of the core contributor community members.

          It is helpful to know who these people are without having to go to automattic.com web site and checking. Partly because the name(s) on the web site do not always translate to Trac.

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

          Yes, the first Automattic should have read WordPress core team. The second should have read Automattic and WordPress core team and WordPress core community.

        • Andrew Nacin 10:02 pm on August 26, 2010 Permalink | Log in to Reply

          That works for me.

      • Andrew Nacin 9:39 pm on August 26, 2010 Permalink | Log in to Reply

        Also, I really like your thoughts on patch requirements, expectations. Thanks!

    • JohnONolan 9:35 pm on August 26, 2010 Permalink | Log in to Reply

      Probably need a mini section for designers / front end developers. We can title the section “for dummies” – as Nacin will attest to by the number of questions that I asked him in the early days :)

    • Andrew Nacin 9:35 pm on August 26, 2010 Permalink | Log in to Reply

      Random quick hits:

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

        Inline documentation is found at http://codex.wordpress.org/Inline_Documentation

      • Matt 10:34 pm on August 26, 2010 Permalink | Log in to Reply

        • Andrew Nacin 2:09 am on August 27, 2010 Permalink | Log in to Reply

          Thanks! Liking that new page a lot.

        • scribu 9:40 pm on August 27, 2010 Permalink | Log in to Reply

          Nice, but the page title reads WordPress > About > Requirements

        • filosofo 5:07 pm on August 30, 2010 Permalink | Log in to Reply

          From the Philosophy page:

          There’s a good rule of thumb within internet culture called the 1% rule. It states that “the number of people who create content on the internet represents approximately 1% (or less) of the people actually viewing that content”.

          So while we consider it really important to listen and respond to those who post feedback and voice their opinions on forums, they only represent a tiny fraction of our end users. When making decisions on how to move forward with future versions of WordPress, we look to engage more of those users who are not so vocal online. We do this by meeting and talking to users at WordCamps across the globe, [sic] this gives us a better balance of understanding and ultimately allows us to make better decisions for everyone moving forward.

          (emphasis added)

          Mathematically speaking, it’s unlikely that “we” has spent enough time chatting at WordCamps to engage more than 1% of WordPress users. The counter says 13 million downloads of 3.0 so far. Assuming one user per download, talking to 1% of them for just one minute each would take by itself a full-time job for over a year, with no time to process or organize the results. It would also mean that all the past WordCamps would have had on average a couple thousand unique attendees each.

          More importantly from a statistical perspective, those with the means, the time, and the interest to attend a WordCamp are not likely to compose a representative sample of WP users in general. Nor are they are going to speak many of the hard truths in a WC reception line.

          I’m not just being pedantic; something as fundamental as a guiding philosophy should be accurate and honest. There’s nothing wrong with saying that, when it comes to resolving contentious disputes or setting big-picture goals, the ultimate arbiter is Matt Mullenweg’s judgment, which has served him well so far in numbers of WP users and the financial success of Automattic. Mullenweg keeps his finger on the pulse of WordPress users by meeting with hundreds of them at WordCamps across the world, reading thousands of blog posts, etc.

          Spelling this out would have the additional benefit of avoiding needless frustration for some contributors in controversies like capital_P_dangit, as you could just point them to the philosophy document.

      • bentrem 5:45 pm on August 27, 2010 Permalink | Log in to Reply

    • JohnONolan 9:40 pm on August 26, 2010 Permalink | Log in to Reply

      Further thoughts and questions that took me a long time to learn:

      Who are the core team?
      Who answers to who? What is the hierarchy of power?

      (oh I see that Nacin just added this above)

      What is ETIQUETTE on Trac? I was petrified for months of Trac, not being able to edit stuff is frightening. As is changing the status/priority/anything of a ticket without knowing whether or not it’s the right thing to do.

      How do you apply a patch (in detail, inc info about how to dowload it FROM trac) for testing?

      A template for bug reporting which people can use to create better, more substantial tickets.

    • Mr Mist 9:51 pm on August 26, 2010 Permalink | Log in to Reply

      A really simple guide on how to create a workable patch in various O/S.
      When to re-open a ticket / when not to re-open.
      What to put in the tags fields

    • Andrew Nacin 9:52 pm on August 26, 2010 Permalink | Log in to Reply

      From Ryan: The two most important attributes of a core contributor are brevity and thick skin.

      I’d argue that the brevity can be applied widely: to patches, comments, personal agendas.

      • John James Jacoby 10:08 pm on August 26, 2010 Permalink | Log in to Reply

        Agree with this completely. No one wants to read through a 4 paragraph explanation of a bug. And no one is out to hurt anyone else’s feelings; and if your feelings are hurt, you’re doing it wrong.

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

      25c reads like this: a) as I cited in IRC, ” Boeing’s old “Sequential Thematic Order of Presentation” (STOP)” … time tested and industry-strenght. Else you get caught up in subjective aspects. Gotta have a matrix or tree to hang things from. –ben

    • Brian Layman 9:56 pm on August 26, 2010 Permalink | Log in to Reply

      A default assumption that others know at least as much as you, if not more. This helps you ask why something was coded a particularly way rather than going in with a “this code is bullocks” attitude.

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

        This a good suggestion but hard to do. Sometimes the personality of people (like mine) is to assume everyone doesn’t know what they are doing until they prove otherwise. However, it is very quick to learn who knows what they are talking about verses those who relatively don’t.

    • Andrea_R 10:26 pm on August 26, 2010 Permalink | Log in to Reply

      Just a few broader ones for those new to the process:

      • what do I need to keep tabs on?
      • should I hang out in IRC? When? If I’m contributing on a regular basis, is there an expectation that I should show up for dev chats?
      • after reading all the above resources, who do I turn to if I have a question that needs clarifying?
      • do I need to join particular mailing lists?
      • if I file a ticket, is it expected that I need to also produce a patch? Will it help if I do?
      • Jacob Santos 10:30 pm on August 26, 2010 Permalink | Log in to Reply

        I think dev chats has always to me been a point of contention. Decisions are made there and I suppose they are tentative, but the problems has been that work places usually do not allow for IRC chats that aren’t work related. Generally also, one can not bring up dev chat related topics after the dev chat is finish barring both those who work at jobs restricting access to the IRC chat and those who sleep during the time periods of the chat.

    • Ron 10:32 pm on August 26, 2010 Permalink | Log in to Reply

      I jumped into the deep end of the pool in January. A brief guide to trac (which others have mentioned) would be indespensible, imo.

      Second, for people who are interesting in being actively involved on an ongoing basis, I would strongly recommend that they follow activity in trac and review all the IRC logs for at least a month. The huge benefit to the contributor is that they will become familiar with the “regulars” and how they work together.

    • Ryan McCue 12:47 am on August 27, 2010 Permalink | Log in to Reply

      One essential piece of knowledge is knowing how to get your patches actually committed. I’ve found that the trick is to bug committers until they get sick of you doing so and finally commit it. ;)

      (Seriously though, at least mentioning your patch in #wordpress-dev helps to get it committed)

      • Andrew Nacin 2:12 am on August 27, 2010 Permalink | Log in to Reply

        Justification is also important. I like this from our Release Philosophy page on the Codex: “If you’re too lazy to do the homework and think through the big-picture rationale, I’m too lazy to add the feature. On the other hand, patches that come with well-thought-through rationale are often applied right away.”

    • Andrew Nacin 2:32 am on August 27, 2010 Permalink | Log in to Reply

      Another good thing that takes a while to figure out, is navigating specific aspects and functionality of the codebase, and how that goes into creating patches. A few examples that come to mind:

      • CSS and JS. Don’t minimize. It keeps the patches small, it prevents patches from going stale over an otherwise unrelated change in the file, and it allows the committer to confirm that the file was indeed properly minimized.
      • Images. Attach them to the ticket, preferably the originals too so we have a record of them. (Good for UI group.)
      • Script/db_version bumps. No need to include the bumps in the patch; we can handle them that way we know we got everything.
      • DB upgrades. How it all works is definitely confusing as first. Same with update-core.php.
      • Deprecated functions. Where they go, how we do it, etc. Maintaining full functionality is vital.
      • Also knowing how to test certain aspects of the code, using WP_DEBUG, etc.
    • dougwrites 5:59 pm on June 4, 2011 Permalink | Log in to Reply

      Still taking suggestions? Thank you for doing this!

      General: having patience with the cycle, but also understanding deadlines and when to jump before those points when no longer can get something in.

      Docs: especially contextual help but also inline. Different from other patches?? Best way to package patches (individual files, omnibus sets, also attach text files of what text would look like with changes?). Knowing that writing is rewriting and re-rewriting. Balancing brevity with hitting enough key points.

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

    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: , handbooks,   

    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

          @Mike

          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,

          ~e

        • 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

      Added:
      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: http://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:

        http://diveintomark.org/archives/2009/10/19/the-point

        • 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
      Cheers

      • 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

        @filosofo

        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

          @filosofo
          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

      Nice!

      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] http://codex.wordpress.org/Transients_API
      [2] http://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:

        Options
        * 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?

c
compose new post
j
next post/next comment
k
previous post/previous comment
r
reply
e
edit
o
show/hide comments
t
go to top
l
go to login
h
show/hide help
shift + esc
cancel