WordFest 2021 Talk by Birgit Pauli-Haack
Ways a non-developer can contribute via the GitHub repository.
Example: WordPress Gutenberg. Learn some lingo, creating and commenting on issues, search labels and work on finding solutions by commenting on design, and functionality. You don’t have to be a developer to contribute to WordPress.
A very important session showing that you don’t have to be a developer to be an important contributor.
— Maciek Palmowski, WPOwl
The talk was live-streamed on January 22, 2021, at WordFest Live. Below is the pre-recorded segment of the talk. We also had a 15-minute Live Q & A around Gutenberg in general, but it seems that part did not get recorded.
On my personal dev blog, I post a few months ago a blog post recounting my journey on GitHub.
Mentioned Resources and Links
- WordPress 5.6 Core Stats: contributions by country & company
- Open source: Better solutions and a more inclusive society
- Live Q & A: The Making of Open-Source Story by Yoast with Blocks
- Why Contributing to WordPress Benefits Everyone!
- How to get started
- Developer Documentation: Contributor Guide
- Anne McCarthy: How to do triage on GitHub
- Repository Management
Birgit Pauli-Haack: So thank you for being here with me. This is a bit weird doing a talk like this online. If I were talking at an in-person WordCamp, we would be in the smallest room, and could have it quite interactive and have other contributors share their journey as well. So, considering how hard it is to volunteer time, especially after 2020 with working from home, and the childcare challenges, and care for older parents or worse. The latest version of WordPress 5.6 had over 600 contributors. I’m grateful that this new talk was accepted at WordFest, and I want to thank the organizers, volunteers, speakers and sponsors for making it happen. And thank you all who are interested in contributing to WordPress or at least learning more from contributors.
So come work on this open source software used by hundreds of millions of users. So on the site make.wordpress.org, there are over 18 teams that have their blog there, and all the handbooks and how the team works. Not every team contributes code, and every coding team has a great need for people who don’t know how to contribute code. But all project managers can test features, facilitate meetings, discuss new features or processes, and organize meetups and speak at WordCamps.
Why contributing? First, there’s the business case. In our web development business at Pauli Systems, we have been using WordPress for a decade now and made good money with it, and we worked with the software without any licensing fees or any monetary upgrade costs in a community of very generous people.
Working on the project, gave us an even deeper appreciation for the work and the people behind the project. We are all standing on the shoulders of giants. Contributing to WordPress is part of giving back as much as I can. Others wrote about it, most recently the team Yoast produced a great long read about how open source brings better solutions and a more inclusive society. Apart from some street credit in form of badges, contributing to WordPress brings me personal joy, too. The last five years have been very inspiring and I learned so much for my personal growth and how to lead and work remotely as well as meeting people around the world. The kindness, patience, and professionalism is reassuring even if the rest of the world descends in chaos, fear, uncertainty and doubt.
I consider many teammates friends, and as soon as we get back into in-person meetings, there will be a hugfest. The marketing team, also a Nocode team, published a longer post about why contributing to WordPress benefits everyone, or also why contributors give their skills for free. Let me leave that for an introduction into generally contributing. You were promised a case study on Nocode Contributor Journey on the WordPress GitHub Repository for Gutenberg. So let’s get to the meat of the matter.
The Gutenberg/Block Editor team belongs to the larger core team. It’s the team developing the Block Editor and the Site Editor. I often get the question, “What’s the difference between the Block Editor and Gutenberg?” So per se, there isn’t really a difference. So you can think about the Block Editor is what’s in WordPress or WordPress core, and Gutenberg is the plugin where it’s developed. Gutenberg is also the idea of a larger revamping of the whole WordPress experience. The WordPress core releases are every three to four months and the Gutenberg developers, however, release a new version for the plugin every two weeks. So when the next WordPress release comes around, all the features and fixes the plugin received since the last major release, will be merged into the core code base.
So for WordPress version 5.6, that was released in December, it incorporated the plugin versions 8.6 to 9.2. So Gutenberg team has regular meetings in their Slack channel on Wednesdays, 9:00 AM Eastern, 6:00 AM Pacific, sorry, West Coast people and it’s 1400 UTC. The Slack channel is separate from core, it’s #core-editor slack channel. There are also meeting notes posted on the make.wordpress.org core blog, so /org/core. And apart from meetings, most Gutenberg developers communicate on GitHub. So, let’s get started.
Situations. What are the situations when I create issues? Whenever I encounter a bug or annoyance or inconsistencies, most of the time I stop what I’m doing and I create the issue, or I make a note of it so I can go back to that. I also test new features for an article. So, if I want to write about the Block Directory, I definitely want to test it before that and once in a while, I run into issues there and write up a bug report. I also do release testers, so Release Candidates from the plugin.
And then the last but not the least is, any idea I have on future feature improvements and that’s when I feel a different approach might make a feature much more helpful for power users, or if something is missing that I find. So, let’s look about some examples. Don’t worry, I will not discuss the merit of the issues, or just go deeper into Gutenberg code or something like that, I want to show you what paths and engagement they can take.
The first example is about bugs and annoyances when I click on this link. It works, excellent. I have to have it, at the right my bullet points is a normal paragraph and then when I’m done with all the bullet points, I convert them to a list. And up until summer of 2018, I found it very easy to do this in the Block Editor and with the next version for this, I encountered that it wouldn’t work anymore.
When you’re scrolling through this, that one was pretty fast resolved. Matias gave me a hint that I can do this now through the transform button that was back then just introduced. So that was easy, right?
So the next one was also a bug, but it had to do with the Meta Box. And so the Meta Box would scroll up to the top of the editor instead of staying put on the bottom of it and it seems that there are still quite a few people who were able to replicate it. Joen kind of said, “Oh, I was able to reproduce, so that was all good.” But then he also said that while debugging this, he found that that was actually an upstream issue from a plugin. This issue was closed, but then here was the issue at the Yoast GitHub repository, so I was able to follow along there and then tested again when the new Yoast plugin was then released. So those two were all bug reports, but then I also test new features.
And the first example here is for the widget screen. So it was just recently last in October, the calendar block triggered an error, developers reproduced it and labeled it with a calendar widget, and screen, and debug and bug. And then what happened was that in October, it was reproducible and then just a few days ago, Robert Anderson also tested it again, if this is still something that needs to be taken care of, and obviously, that has now moved to development.
For the test Release Candidates, I have two examples, warning of a missing file which was almost instantly resolved because it was a Release Candidate, and a day later there was the plugin fix and another one was…. In this one that was issued, the audio block did a disappearing act in the editor and that was also fixed.
You can imagine that it has increased the quality of the plugin when these kinds of bugs are caught before the final release. But it was hit and miss for me to be able to test the Release Candidates because there are only two days in between. Since mid-December, they changed the frequency of it, and so now it’s a seven-day period and we can do some more consistent testing of the Release Candidates.
And then I do Feature Improvements issues and this one might interest a few. So the keyboard shortcut to switch to HTML editing on a block level. There’s a shortcut keyboard to change the whole editor from visual to code similar to the classic editor where you have your text and the visual kind of tabs. But I found with a block-based idea, I’m normally not going through the whole code of a whole post.
If I want to fiddle with HTML of a block, it’s mostly block-based, so I suggested to have that implemented because it would ease the flow of things as well. And although menu items actually have keyboard shortcuts, so it would also fall into the consistency of that. Well, I suggested as of September 2018, and there was a lot of engagement there, cool idea that really make sense, Mattias got involved. But still in December, so in November, there was some discussion about it, and there were quite a few who tried it and then didn’t get finished with the PR or with the code base. So I hope that sooner or later, a developer finds time to work through this to get this going. But that’s a classic example that even if you have a good idea, it does not always make it into a developer’s head, so we always also need to find a developer for actually implementing those features.
The last one that I’ll share with you is a Feature Improvement that you might want to help support, that’s a user triggered search in the Block Directory. So right now in the Block Directory, if you already have a block for a keyword, you are not able to see what else is in the Block Directory, you only see what’s on yours. So we went through, and this is pretty normal for feature requests that you first kind of need an idea of clearly how to actually implement that. And so, I posted a few screenshots kind of mock-ups where I put the button, and there were some ideas, and then the designers chimed in and also had some ideas. They are a little bit more fancy with their mock-ups, and then there’s some discussion going on and more mock-ups when they’re there and then it stalls a bit.
The last comment was September 2nd, and I started a couple of weeks ago to discuss it again, or just put another comment in there and, lo and behold, Kelly Dwan actually worked on something like that and already has a working design now, so this is cool. See, you can really influence how things are working when you are a little bit more engaged in the GitHub repository.
So these were quite a few examples on how someone who isn’t part of the developer team can contribute quite a bit to the development of WordPress. So, before you raise an issue, you might want to consider the following: isolate the issue to the core Block Editor, or plugin or the Gutenberg plugin. The icon that you see there is actually the icon of the health check and troubleshooting plugin which is fantastic to help you with that.
Check that out, because it will allow you to switch on a site, it can be a production site, but because it’s your admin, only for you, you can switch up all plugins and all themes and just enable the Gutenberg plugin and already have a test site, and your visitors and your fellow editors will see your site like it was. So we’ll use that plugin quite a bit, but it might help you with this as well.
And then the next step would be to search on existing issues. You can use labels and keywords. As you saw, there are some labels for blocks and labels for features that you can drill down into the Gutenberg repository, and then use the bug report issue template and that has five components.
One is, put a description of what you find and that description should be concise, but also comprehensive, so you need to strike a balance there. But the more details you put already in the pros, the more someone who reads it can kind of put themselves into your shoes and figure out what might go wrong, and also where you’re coming from, what you’re trying to do and what you’ve found, and then list the steps to replicate the issue. In order to do this right, you actually need to know how that thing happens. What are the steps that got you to that? And that’s one of the most difficult things to actually nail down so somebody else can have the same experience, but it’s a critical thing. So others can also reproduce the problem and then they can decide where the attack vector is and where the code needs to change.
What of course always helps is a screenshot or a screencast and then it has another section there that’s the expected behavior. It helps really mentally after I go through the steps, okay, this is what happens, I try that too. So what is it exactly that the person expected to happen? And it helps to reiterate that and show how you think this can be best solved.
And then the last part, the fifth part is, your environment information, what operating system you use, what browser you use, and which version. Also, if you use the WordPress core without the plugin, or a plugin, and the Gutenberg plugin and then also which version of the plugin. So when you go to the repository, and go to new issues and then click on bug report, that’s when you see the section–describe the bug, how to reproduce expected behavior screenshots and then the editor version, the desktop. And then, if you are on a smartphone, also what device and operating system and another iteration reports security issues not on GitHub, go to the WordPress hacker one program, report them there, because this is public information, and security issues should not be publicly disclosed before a fix is available. So this would be the plugin report issue template.
Okay, so how do you get started? You need a WordPress or it’s just a checklist to make sure that you have everything. You need a wordpress.org account and the links pointed to the places where you can do that. You do need to create a GitHub account, and then you also need to create a WordPress Slack account, and then connect your WordPress profile to your GitHub account, that is so you get all the credits for it.
In my profile I have here the GitHub account, when I go to edit profile I can revoke access. So there’s a GitHub username, and you should be logged in to both of them so you can directly connect the two. Jon Derosiers has also published a post on the core block about how that happened and all that.
So after creating issues, the four variations, you can stop there. You can just do that all day long or once a week and nobody will tell you what to do. This is all self-motivated and self-driven. You probably are expected to actually answer some of the questions as they come up on the GitHub repository, there’s a notification set up, but what comes next? What could you do afterwards? So, the first one would be, check out the labor needs testing. What does it entail?
What does it entail — the needs testing? It would entail that you’d go to the issues, read the description and then go through the steps here, too, and figure out if you are also seeing the same occurrence. If you do, share your information, share that you can reproduce it so someone as a developer is more sure that that is actually what needs to be solved, it’s not caused by something else that’s an underlying issue or something like that.
You could also participate in discussions. So, this is a fascinating place for me and I do productive procrastination on that quite a bit and fascinated by the discussions about possible solutions for a new feature or an enhancement. And sometimes that’s all that is in the discussions, but sometimes I actually have an opinion or a different idea and I share it, I chime in. And more often than not, my ideas might not make it into the final version of a new feature, but I always feel hurt that no aspects of my idea were considered, and I find great satisfaction with it.
So an example could be improving the list block, so do we need more versions of that? And how those are going to be and any discussions like that, you don’t have to chime in, you just can read it, but I appreciate really how much thought in every issue goes and how many people have ideas or already have tested that, or have a working example implementation of that. Like here, Jeffrey Carandang has already something in his blogging.
And so, it’s really interesting to read through some discussions and if you don’t have an opinion, you don’t have opinion, but sometimes you have, and this is a moment where you can actually be heard, have your opinions made known, even if it doesn’t turn out that way entirely, but you bring yourself in and the team is very patient, and it’s very considerate and very thoughtful about how to answer to some suggestions. So, it’s definitely another way to contribute, and you can join the triage team.
So the triage team is an open group of people who label all the issues and shepherd them more or less through that process. You can read up about that on the contributor’s handbook. So that’s certainly another way to contribute and can join. You need additional permission to do that. And they tell you how, and follow that link, it shows you what is entailed on the Triage Team, and what the expectations are, and how they’ll meet and all that.
Now, if you need a broader focus on value working in a group on certain things, there is also the FSE means Full-Site-Editing Outreach Program, that’s run by Developer Relations Manager or Wrangler, Ann McCarthy. It’s geared towards people who build sites for others, but don’t write code. We get scripting tests for the author versions and then share our experience. You meet everyone in a separate Slack channel, it’s kind of a way to figure out if the people that would use it get everything they need.
It’s about not only the site editing flow, do the interfaces make sense, or you’re getting confused? Do you know how to go from one section to the other section? But also, how would you migrate themes over to the new way to do this? Or can you mix and match the old way with the new way and all that kind of things will be discussed there. So it’s a small group and it’s an experiment, that’s the first outreach program that WordPress has, so it’s quite an interesting way to also contribute to really work on the bleeding edge of a great feature that will change how WordPress or how people interact with WordPress and build their sites, definitely.
So, that’s all I have for you today. Of course, I’m looking forward to your questions now. You can stay in touch with me on the WordPress Slack, or on Twitter DMs, or Private Messaging or Direct Messagings are open. You can email me at email@example.com or follow the @gutenbergtimes Twitter handle. You can also find all our live Q&A shows on the Gutenberg Times YouTube Channel, and if you want to keep up with what’s happening on a weekly basis, we release a weekend edition of hand-curated links from the community and from the team. And as I said, the slides are at bit.ly, bit.ly/wordfest21. All right, thanks so much and back to you.