What are “commit props”?

As I talk to people outside of WordPress about open source software processes, one thing that always catches attention and gets positive feedback is our method of giving credit to people who contribute to a given release. There are a ton of ways you can contribute to WordPress-the-project, but the thing I deal with in particular is the core software, which runs on release-based cycles. There are commit message guidelines (originally authored by me!), which start with:

Props should be given to all those who contributed to the final commit, whether through patches, refreshed patches, code suggested otherwise, design, writing, user testing, or other significant investments of time and effort.

So what are props? Well, in a commit message you might see something like:

props boonebgorges, melchoyce, helen

What this means is that the person who committed the code has compiled a list of all the people who contributed to that changeset, not merely in terms of code, but any meaningful effort that moves the software forward. Some of this terminology is because we use Subversion and Trac, so to frame it in GitHub-type workflows, this would roughly be the equivalent of doing a squash merge of a PR and adding that line so as not to lose attribution that you might otherwise get with a regular merge. That latter type of attribution is limited to people who’ve managed their way through version control and committed something, typically code. There are limited opportunities for equally critical participants in disciplines like design and writing to get the same kind of credit.

GitHub has a Co-authored-by trailer that makes it possible to give multiple attributions on a commit that is reflected in GitHub profiles. This is really cool! And I think it needs to go further 🙂 It’s a very tedious process to add these trailers, typing them out and gathering names and email addresses. It should be easier for maintainers to be liberal in giving credit to other people who’ve helped along the way – a specific line prefix with a comma-separated list of usernames seems like it would work there as well (in WordPress, commit messages are parsed for those lines to generate the list of credits for a release). There’s still a bit of an issue of giving those props when your commits are very atomic – at what point in all that code do you stop to give a designer credit for coming up with this thing for you to even be coding in the first place? But that starts getting into why I believe in squash merges and that’s better saved for another time.

Attracting and retaining a diverse contributor base is critical to the long-term health of open source projects, especially ones with large user bases, large code bases, and a bunch of different interfaces. Not only is technically being able to give credit an important component of that, but fostering that mindset of “people who write detailed reproduction steps are just as helpful in fixing a bug as somebody who submits some code” has really helped shape valuable maintainers and contributors alike.

What are “commit props”?

Restaurant vs. meal kit vs. grocery shopping (or, WordPress.com vs. Jetpack vs. WordPress.org)

Ryan Sullivan posed a challenge/trick question that got me interested because I like trying to come up with compact plain language explanations. So here’s mine:

This is, of course, not a complete analogy for all aspects of all of the above. It’s all of seven words, come on. It also assumes cultural knowledge of these methods of having a meal, which seems fairly likely for people looking for this delineation. But I think it’s a solid way to start understanding what these three entities are and what they aim to provide you. It does not explain where your stuff lives or how you pay for it (people use rent vs. buy sometimes for this), and I don’t intend for it to do so. Analogies are helpful in providing understanding where knowledge is still considered specialized. They also center references in ways a given person might understand – this analogy probably works well for a relatively-privileged American, but would need adjusting to make better sense to somebody in, say, France (localization, anyone?).

Think of the process of spinning up a website as how you go about acquiring, oh, some dumplings. (Pretend this is cacio e pepe or tacos or a hot dog or whatever kind of food fits into your norm.) Don’t think too hard about what exactly that building process is – most analogies aren’t made to be that specific 🙂

You could go to a restaurant, look through a menu, put in your order, and eat whatever they give you, perhaps customizing your meal slightly with some dipping sauce. Your choices are which restaurant you go to and which dumplings you pick, assuming they even offer a variety at all and that you didn’t pick the restaurant based on the dumplings to begin with. This is like choosing to use WordPress.com for your website – they have curated products that you pick from and you pay them somewhat of a premium for what you want, you don’t necessarily know what exactly is inside, and your customization options are very limited.

On the other end of the spectrum, you could make the dumplings yourself and put all the work into acquiring the ingredients you need. You get way more choice and the accompanying amount of work in having choices follows. Focused on a crunchy ideological farm-to-table approach? Well, you could grow/raise everything yourself, or maybe get some things from a CSA, or find some gluten-free dumpling wrappers, etc. Most people will buy what they need at their preferred grocery store (having already put the effort into finding a grocery store), substituting ingredients rather than going to another store entirely to find what they need, and frequently abandoning the effort entirely in favor of some pizza. If you really know what you’re doing, you’ll head to the Asian supermarket. Oh, and also, written recipes aren’t common practice for dumplings. This is like making a website using the WordPress software itself and its surrounding ecosystem. There’s a lot more knowledge you need to either already have or work to build: which grocery stores/software/hosts have what, what kind of ingredients/themes/plugins you need and what places carry them, reading endless reviews and trying things that don’t work very well along the way. It’s typically a lot more effort and not necessarily all that cost-effective, but you have a better shot at getting exactly what you want. If you can figure out how to put it all together, anyway.

Jetpack is like all these meal kit start ups (think: Blue Apron) – they aim to allow you to have that DIY experience on your own terms, but with a lot more curation and guidance. If you’re not familiar with these meal kit services, well neither am I, but the idea is you get shipped a box of ingredients for a specific meal and then you make it at home with your own pots and pans and salt and whatnot. You have more opportunity to customize since you’re doing things yourself, but it does require that you understand the basics of cooking in order to achieve a desired result. Experienced cooks roll their eyes at the idea that people would need or want such a thing, and yet here we are. Jetpack is something like that: it ships a bunch of stuff you will probably need to get a website going in an attempt to demystify and simplify the process. Developers frequently deride it and have a hard time understanding why it’s helpful or how. Oh, and you know, the whole start-ups-love-personal-data-and-subscription-models thing.

Making a website is complicated and confusing, in no small part because there’s so much terminology and it’s not a part of what we consider a part of a typical routine the way going to a grocery store is. However, chances are ever-higher that something you do or will do will involve or significantly benefit from having a web presence. There’s something to be said for gaining literacy in this area early on in school – learning to code is not what’s important, but rather what is the web and how does it work. (We should be teaching more practical literacy in general like managing personal finances but that’s not a topic for this blog.) I hope this is a helpful perspective and jumping-off point for teaching and learning as we try to make the web a little more approachable for all, and I’m sure people will come up with interesting extensions to this analogy.

Somewhat related: I bet it’s not a coincidence that so many front-end developers get into bread making.


I’m working on a theme for public distribution


First, I think it’s important for me to understand the .org theme submission process. I have no idea if I’m really going to end up with a representative experience, but I’m going to try. I’m already confused about something though: am I definitely 100% allowed to submit a child theme? One of the requirements listed is “able to have child themes made from them” but grandchild themes are not a thing.

More than that, though, is that I have this theory that highly targeted themes are going to be a better entry point to WordPress than the current landscape of multipurpose/do-it-all themes. This particular experiment probably won’t generate much in the way of solid data on its own, I think making one myself is a reasonable place to start.

WordPress in its current state does a lot of assuming that you are going to stick to it no matter what, from themes with significant initial setup to having to understand that plugins add functionality (to say nothing of finding those plugins). This matches a lot of how WordPress’s usage has grown so far – through evangelism and hired implementation, both of which come with some amount of motivation to bend WordPress to do what’s needed even if it’s not clear it really can or should be. Meanwhile, if you’re just getting started with making a website and do a search for solutions, chances are pretty low you’re just going to choose WordPress from a pile that includes Squarespace and Wix, both of which do a significantly better job of showing people how exactly they can do what you want (verticals).

One of the things that’s influenced a lot of how I think about building websites without code is the time I spent teaching Digital Portfolio for Musicians (encompassing digital materials and presenting them via websites) after I graduated from the Eastman School of Music and took a job there as a web developer. This was from 2008-2011, which looking back, was the start of a big shift from “make X tool work for what I’m doing” to “search for X tool that does exactly what I want”. I’m sure there are plenty of takes as to what specifically you can attribute that change in mindset to (mobile apps, maybe), but whatever it is, it makes sense. Technology is no longer a novel tool that we bend ourselves to accommodate; it’s now an assumed layer that should just work for you.

If I’m trying to build a website for myself as a musician, I’m not going to think “okay let me browse through 800 themes filtered by some layout and technical feature criteria that I don’t really understand and see if one of these maybe looks like something I can make into a site I can barely visualize in the first place”. I’m going to search for something that clearly shows how I make a musician website, probably via a targeted demo and good marketing copy. And I’ll probably ask my friends, most of whom are probably going to recommend whatever tool is currently popular in our niche (Squarespace today; once upon a time Dynamod).

Now, searching for a WordPress theme specifically is already a dialed-in audience, so again, who knows what kind of data I’ll really get right now. But over time, perhaps the existence of more targeted themes, with good descriptions and demos (starter content!) that lead into a far less time-consuming customization process (as opposed to a complete building process) will help more people to understand that WordPress can work for them.

I’m working on a theme for public distribution

Including even more people at contributor days

What if WordCamp attendees could sign up for user testing slots at contributor days?

What if we managed to build up device testing labs for testing sessions?

What if more meetups ran feature testing and feedback sessions? (I’ve done this with Eric Lewis and we got a lot out of it.)

Seems like we’d not only get a lot of valuable information to use to improve WordPress, but we’d also be able to include people who know enough about using WordPress to be at an event in the first place but might not think of themselves as “contributors”. And, of course, all kinds of people can write, run, and observe the tests, too.

Including even more people at contributor days

I live-tweeted a theme change and you’ll never guess what happens next

I summarize some thoughts, is what happens next. But you know what would be even better than that, is if we all looked at making these better and identifying even more problems. Some of the notes below seem like they probably translate into really good first/early contributions for both design- and development-oriented people.

  • Better ways of matching thoughts (keywords) with actual themes. Maybe that’s better tagging, or multiple screenshots to show more views that might match what I was looking for, etc.
  • There are no themes I found that did creative things with a mix of post formats, e.g. longer prose posts mixed with a bunch of photos in individual posts like on my blog. I didn’t expect to find anything that catered to that specifically, but wow did everything look the same. Somebody noted that there sure were a lot of good themes for showing off your phone.
  • The split between managing installed themes and adding new ones is really awkward in practice. Inline installing has helped a bit when adding new themes, but it’s not great. (This often applies to plugins, too.)
  • There’s no feature filter for installed themes, only a name search which is pretty useless if you don’t remember theme names.
  • Said feature filter could really use some microcopy and interaction work.
  • Adding themes in general has some UX oddities that could use work.
  • .org theme previews suck (this is widely known). .com’s are quite nice from what I’ve seen. The previews also help me narrow down thoughts about what I really want. I don’t want a theme that does it all, I want a fairly narrow theme that can strongly be what I need instead of doing it weakly or forcing me to do a lot of work to get it there.
  • .org themes should be able to have more than one associated author.
  • Widget area migration guessing is still awkward, although I guess still better than dumping all widgets out when switching a theme. Menus don’t migrate at all, which is strange considering that menus are generally more uniform in placement/use and are actually built as discrete groups.
  • Menu Locations with separately built menus are confusing in practice.
  • Some live previewing actions are REALLY slow and I have no idea why or what I’m waiting for.
  • There are still a bunch of dead ends in the customizer as it stands, and visual edit links for things like widgets would be so, so nice.
  • Post formats (un)structured data, I don’t want to talk about it.
  • Notices telling me to do XYZ to “finish” an update are slightly alarming and if that notice disappears when I click on whatever link it gave me, I probably won’t remember what it said.
  • Plugin and theme conflicts are awful and I have no idea how general users get through them.

Theme disconnect and discontent

Since I’ll be leading the 4.7 release cycle, I’ve been doing a lot of thinking about what it might look like. Really, I’ve been doing a lot of thinking about bigger projects and longer roadmaps in general, but 4.7 is pretty good motivation to kick things off.

One of the wishlist items I’ve heard throughout my five years of core contributing has been NUX – new user experience. So many abandoned sites, so much frustration in getting a site looking the way you want it to, so let’s fix it! Except that NUX is hugely broad (and itself can be thought of as N-UX and NU-X), and while individual bits have been worked on here and there (e.g. pointers), I wouldn’t exactly call it a unified effort toward a shared goal.

The part of NUX that I would like to start tackling in 4.7 is initial site setup, which also ties in with theme setup, whether that’s initially for a site or on theme switch. My premise here is that a user should be able to go from a fresh install of WordPress to being ready to show somebody else their site in a unified experience that allows for live, non-destructive previews. Initial questions that spring to mind are:

  • Where exactly do we define the start and stop of the setup phase to tackle right now?
    Perhaps post-theme selection through when you first feel comfortable sharing the site with somebody else, e.g. “check out what I’m working on”.
  • What might somebody have already in mind when they start the process of setting up a new site?
    These might be things like a general visual idea (typically inspired by a site or general trends), existing media (photography, videos), contact form, and so on.
  • How do different people conceptualize the structure of a website?
    When I taught digital portfolios for musicians, the most successful analogue was a hierarchical outline. Some people don’t think about it at all, and that’s okay, too.
  • What goes through somebody’s mind as they pick the next thing they want to change about their new site?
    For instance: I want the title of my site to look like this, now I want a logo next to it, now I want this image behind all of that, and then under that would be a menu that goes to pages with these titles, and then over there I want my contact info, etc.
  • What currently exists in WordPress that supports this goal?
    Customizer, site icon, site logo, custom header, custom background, featured images, nav menus, widgets, ???
  • What currently blocks users from accomplishing this in WordPress?
    Activating a theme might not make it look anything like the screenshot or demo you saw. Adding pages to nav menus currently requires you to leave the customizer, make a page (which confronts you with a content area that you may not be ready to think about yet), and then go back to add it. Or, add a fake link and remember to go back and change it later (and that’s for a user who understands custom links and making fake ones, etc.). Multi-part pages don’t have any sort of standard or even common editing experience. Shift-click to edit an element (which is over in a side panel) is a hidden feature with no visible hint.
  • What are other services/software projects doing in this regard? What’s working or not working for them and why?
    Time to do some market research. 🙂

With 4.7 being the final release of the year, Twenty Seventeen is also on my mind, which aligns nicely with this focus area. I have some pretty strong personal feelings about what I want it to be like, but no matter what, here’s what I want it to represent and enable for others:

  • Theme demos on .org that actually best showcase that theme. This may be static home page, specific content, layout selections, and so forth.
  • Initial option/content/whatever setting upon theme activation, so that users get the look they saw and have some prompts for what kind of content might go where. This is super tricky for a number of reasons and I think we’d want to approach it in a restricted way so that best practices have time to develop before more creative approaches appear and get copied.
  • If some kind of multi-part page is present (seems highly likely in the current climate), at least an initial exploration of the best experience for editing that in various contexts.

One of the things that was really interesting in 4.6 was the response to the proposal for creating page stubs while editing nav menus in the customizer. A lot of concerns seem to center around mixing of content and appearance editing in the customizer, and the recurring theme of worrying that the customizer is eating WordPress‡.

In regards to the mixing of what’s being edited, I don’t believe that the majority of WordPress users or even a significant percentage of us make a distinction between “content” and what our sites look like. Essentially, for most there is but a singular “this is what’s on my website”. That’s not to say that there isn’t a difference technically, and certainly for developers it’s much more evident (although nav menus and widgets still seem to be a gray area). As always, I’m happy to be wrong, but I’m also confident that I’m not.

Bottom line, what I want is to close the gap between what a user is expecting a theme to look like and what it actually looks like on their own site. Someday soon I’d also like to close the gap between what a user has in their head and finding a theme to match. If this sounds like some things that Matt’s been saying, well, we do actually talk to each other 🙂 I’ve got plenty of other things I want to have happen in 4.7, and I’m sure as things get rolling next month people will bring up tons of great ideas and bugs that need fixing, but actually planning some kind of product feature and roadmap seems like a good thing to start doing.

‡ As for the customizer eating WordPress: it’s not. But! I understand where that comes from. User trust is centrally important to WordPress – shared philosophies and its success alike. When it comes to what’s on a website (appearance and content), one of the best ways to gain and keep user trust is to provide non-destructive live previews. Right now in WordPress, TinyMCE can serve that for content, but that’s largely the area of the customizer, and that’s why things keep creeping into it – because that ability to try out changes without them showing up before you’re ready or otherwise being “punished” for them is incredibly important. But it might not be the customizer in its current form forever, and in fact, it probably shouldn’t be.

Theme disconnect and discontent

Development Philosophy: Confidence

It’s really easy to get caught up in implementation details. I do it and watch people do it all the time. When I’m working on things, and especially when I’m stuck in a rut, I think to myself: “How can this make a user feel more confident?” This is relevant even when there’s no UI involved – a user can be a lot of different things. For instance:

  • Local autosaves of post content help users feel confident that they can choose to write directly in the editor without fear of data loss. (You can still write somewhere else, that’s cool. I happen to like the WYSIWYG.)
  • Not having shared terms helps users of both code and UI feel confident that changes to one taxonomy term won’t unexpectedly affect another.
  • Widgets in the customizer remove the element of “save and surprise” on a live site. The customizer as a whole is grounded in easing that friction.
  • Embed previews help creators feel confident about the appearance and content of their site.
  • Automatic background updates help site owners feel confident about the security of their site.

Right now, I think new-to-WordPress-admin users never get a chance to build that confidence. What can we do for them, while not hindering those who already have that confidence? We want to surprise and delight – but that means delightful surprises, not jarring ones.

Development Philosophy: Confidence