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
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
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
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
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
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
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
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
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
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
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
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
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
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
That works for me.
Andrew Nacin 9:39 pm on August 26, 2010 Permalink
Also, I really like your thoughts on patch requirements, expectations. Thanks!
JohnONolan 9:35 pm on August 26, 2010 Permalink
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
Random quick hits:
Jacob Santos 9:53 pm on August 26, 2010 Permalink
Inline documentation is found at http://codex.wordpress.org/Inline_Documentation
Matt 10:34 pm on August 26, 2010 Permalink
The recently updated:
http://wordpress.org/about/philosophy/
Andrew Nacin 2:09 am on August 27, 2010 Permalink
Thanks! Liking that new page a lot.
scribu 9:40 pm on August 27, 2010 Permalink
Nice, but the page title reads WordPress > About > Requirements
filosofo 5:07 pm on August 30, 2010 Permalink
From the Philosophy page:
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
By way of comparison: https://developer.mozilla.org/En/Developer_Guide
Matt 6:48 pm on August 27, 2010 Permalink
Nice link — it’s a good idea to look at how other projects do this.
Aaron Jorbin 2:38 am on August 28, 2010 Permalink
Along the same lines, this guide for the linux kernel is pretty good: http://ldn.linuxfoundation.org/how-participate-linux-community
bentrem 5:03 am on August 28, 2010 Permalink
One more level of indentation of comments, pls! *G*G
@aaron – nice come back
@Matt – MozF is known to be … inward facing? (I call it Byzantine.) With lessons learned from that grande project along with others such as LDN, FOSS at large, &tc … WP benefits and Automattic adds to its GTD rep?
JohnONolan 9:40 pm on August 26, 2010 Permalink
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.
JohnONolan 9:43 pm on August 26, 2010 Permalink
Maybe some points of contact too, who should you talk to about contributing based on your interests? PHP/CSS/JS/UI/UX/IA/WCAG
Andrew Nacin 9:44 pm on August 26, 2010 Permalink
/BBQ
JohnONolan 9:46 pm on August 26, 2010 Permalink
+1
Mr Mist 9:51 pm on August 26, 2010 Permalink
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
John James Jacoby 9:52 pm on August 26, 2010 Permalink
Ooo like the ‘when to repopen a ticket’ idea.
Andrew Nacin 2:10 am on August 27, 2010 Permalink
Agreed, I can fit that in somewhere.
Andrew Nacin 9:52 pm on August 26, 2010 Permalink
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
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
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
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
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
Just a few broader ones for those new to the process:
Jacob Santos 10:30 pm on August 26, 2010 Permalink
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
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
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
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.”
Matt 2:36 am on August 27, 2010 Permalink
I think that’s a little rude. We can say the same thing in a nicer way.
Andrew Nacin 2:39 am on August 27, 2010 Permalink
I agree with that. I also took it out of context. Also for reference, it’s from http://ometer.com/features.html.
Really liking the new philosophy page though.
Andrew Nacin 2:32 am on August 27, 2010 Permalink
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:
dougwrites 5:59 pm on June 4, 2011 Permalink
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.