I have been a contributor to WordPress since 2014. I serve as Deputy on the Community team, and as team rep for Bock-Editor Enduser documentation team. I am also a roockie contributor on the Gutenberg GitHub repo for WordPress’ block editor.
Earlier this week, Mark Uriane asked me to review a PR, that fixed an issue, I found. It was the first time someone asked me for a review via the GitHub process. I wanted to mark that day and retrace the steps of my Gutenberg GitHub journey.
I have not contributed any code to Gutenberg. My first and only Pull Request (PR) was a correction on a handbook file.
This post is for all people, who would like to contribute to Gutenberg, but don’t know how. I want to encourage starting their journey, too.
There is a learning curve on all things Gutenberg on GitHub, mostly because of the Git lingo. Below I started a Glossary.
Set your GitHub account
Create issues on Gutenberg
On January 27, 2018, I filed my first Gutenberg issue(#4711). To date, I filed 48 issues, 36 are closed, 12 are still open on this repo.
There are four templates to choose from. Security issue need to go some place else.
The editor will convert your formatting into Markdown and you can drag and drop screenshots and other graphics into the space. For our company repositories, I have become a fan of the checklist feature.
For demonstrating the issues, I often use videos or animated GIFs, recorded with Recordit.
Create a Pull Request (PR)
Creating a PR doesn’t have to be about code. It could also be updates to documentation pages that are tracked in the Gutenberg repository. However, you still need to go through the Git Workflow and it can be quite daunting. My one and only PR is from March 12, 2018. I updated a link in the documentation.
Join the Triage Team
“Triage is the practice of reviewing existing issues and pull requests to make sure they’re relevant, actionable, and have all the information they need. Anyone can help triage, although you’ll need to be a member of the triage team for the Gutenberg repository to modify an issue’s labels or edit its title.”Block Editor Handbook / Contributor Guide / Triage
On August 14, 2020, I joined the Triage Team for the sole purpose to identify issues and PRs that need consideration for the Block Editor End User Documentation team, lovingly called the 🐝-docs team. I am exploring a whole process for this.
For now, I do not attend triage meetings, and don’t triage issues beyond finding the issues and PRs for “UserDocumentation”. I just don’t have the time to do more.
My first PR Review
Earlier this month, I did a testing sprint on the Twenty-Twenty-One theme, while I was setting up this site.
Mark Uraine is a designer at Automattic, WordPress contributor and my co-host on the Gutenberg Changelog podcast. He worked on dark styles updates to blocks, so they are better usable on themes with dark backgrounds like this one. On one of his PRs, fixed my issue “Some block features are rendered with invisible ink with dark backgrounds.” Columns and Table outlines didn’t have enough contrast to be seen on the dark background. Mark requested a review of his PR to make sure it fixed the issues I was seeing.
As mentioned above, that was the first time I had a request for a review, so I needed to find out what I had to do to test a PR. Pull Requests are created in separate branches of the repo. It’s code that hasn’t been released yet and needs to be tested before it merges into the master branch.
Paal Joachim Romdahl wrote good to follow instructions for this next step on my Gutenberg GitHub journey.
Check out the PR Branch
I already had a Gutenberg master repo clone on my system. I started with check out of the PRs branch:
git checkout update/dark-mode-for-specific-blocks – this copied the branch (PR) to my local version of gutenberg.
I already went through
npm install and
npm build and now needed to spin up a WordPress local install.
Spin up local WordPress environment
npx wp-env start starts a wp-env instance within the Gutenberg folder. It ran into some error. I needed to start Docker Desktop first. Then it downloaded WordPress. It was ready for me to test the PR on my local WP development environment site via http://localhost:8888/ Just in case, I forget, use admin/password for WP admin access.
This also had me look up the difference between npm and npx.
For alternative way to organize the local WordPress environment, Michael Arestad gives you a detailed insight into his Gutenberg setup.
Back on GitHub, I added my review comment. Thank God, it doesn’t “count toward mergeability”! I can’t imagine the havoc I could wreak if I had merged capabilities.
And there was a checkmark next to my name in the list of reviewers of the PR. Yay.
Testing Gutenberg from Master branch
Gutenberg has a bi-weekly release cycle, which mean every two weeks, you get an update of the Gutenberg plugin into your WordPress instance, and if you subscribed to automatic updates, you don’t have to do anything. On Monday, the team prepares a release candidate version and then two days later the new plugin version is released.
Another way to contribute to WordPress and Gutenberg is taking part by testing pre-release versions. Until a couple of weeks ago, testing Gutenberg from the master branch wasn’t easy.
On October 15, 2020, I started a new project on Gutenberg Times to provide a download of the Gutenberg plugin, built from the master branch.
For this project I do the following:
- I need to keep my fork in sync with the WordPress repository.
- Here is the documentation on how to set it up and also how to keep it updated.
git merge upstream/master -m 'build **'command adds all the changes from the WordPress/gutenberg repository to my local master branch.
- Modify the gutenberg.php file to update the version
- run the build plugin script
npm run build:plugin-zip
- Upload to Gutenberg Times and release it to the fork of Gutenberg on my GitHub account
I worked with Andy Fragen, the maintainer for the WordPress Beta Tester Plugin, to interface with the GitHub Updater plugin. We implemented a proper mechanism to update existing sites on November 2nd, 2020.
The new process:
It’s live now!
Contributing to Gutenberg
Anne McCarthy wrote wonderful compass for navigating the Community you are about to start to join.
Good First Issues
For inspiration on what your first code contribution could be, browse the Good First Issues list. These are issues hand-curated by Gutenberg developer specifically for new contributors to tackle.
Marcus Kazmierczak posted step-by-step instructions in his post “Good first issue on Gutenberg”.
Many issues need a second pair of eyes to do some additional testing to confirm and provide more details on Issues filed. The triage team flags those with the Needs testing label
Good First Review
Testing is also part of the PR Review process and Gutenberg developers flag specific PRs as Good First Review.
That’s it for now! I will work on the Zip from Master plugin next month and continue the work on the Block Editor End User documentation team.
Please leave a comment or DM me on WordPress Slack @bph to discuss parts or all of it. Don’t be shy. I wrote this to encourage people with getting involved with Gutenberg contributions.