gutenberg (this link opens in a new window) by WordPress (this link opens in a new window)
The Block Editor project for WordPress and beyond. Plugin is available from the official repository.
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
Signing up for GitHub is the easy first step. You can do it right on the homepage. I must have started my GitHub account some time in 2012 as my first fork was code from a speaker at NCDevCon 2012
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.
Before we head deeper into the GitHub Journey, here are short descriptions of terms. You can skip over it continue the journey with Pull Request
Glossary
Git – Git is a distributed version-control system for tracking changes in source code during software development. (Wikipedia)
GitHub – GitHub, Inc. is an American multinational corporation that provides hosting for software development and version control using Git. It offers the distributed version control and source code management functionality of Git, plus its own features. (Wikipedia)
Issues are bugs or enhancements tickets reported from users, and contributors take on to solve via a specific PR.
Fork – is a copy of a repository (repo) that is now in your GitHub account, rather than the WordPress account. Here are instructions on how to keep your fork in synch with the WordPress repo.
PR is a Pull Request – contribution to the files in the repo. Issues that resulted into a PR will be closed when the PR is part of a future release.
Once the PR is reviewed, a committer will merge it into the main branch here called “main” or “trunk”.
God is that hard not to use any jargon. Let’s unpack this a bit further.
Repo = short for GitHub repository; the space where all the code of a product, plugin or module lives.
Committer = contributor who has the rights to merge code from other developers into the main branch
Merge – workflow to merge new code into the right places with other code.
Review = a review of the submitted code. The person who submits a PR can mention specific persons to review their submission and comment or approved it for future release. Sometimes multiple reviewers and reviews are needed to prepare code for a merge into the main branch and to make it into the next release
Main Branch – That’s where all the code from different contributors comes together and is used to issue new software releases. For the Gutenberg Repo that main branch is called “main”, other WordPress repos named their main branch “trunk”, see also Twenty-Twenty-one Theme repository
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
The command 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:
- 1) download from Gutenberg Times,
- 2) install GitHub Updater to get automatic updates.
It’s live now!
Contributing to Gutenberg
If you want to learn more about contributing to the block editor, the best place to start is the Contributor Guide for Gutenberg and join the WP Slack space, channel #core-editor.
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”.
There is also a Twitter Bot tweeting new @Good First Bugs from the Gutenberg repo as well as from WordPress core trac.
Needs Testing
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.
The Contributor Guide has more notes Code Review and Design 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.
Leave a Reply