WordCamp US 2019 - SiteGround Booth Sponsor hall

A #nocode Contributor Journey on the WordPress Gutenberg GitHub Repo

Dark Mode

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.

Screenshot: GitHub profile of Birgit Pauli-Haack username @bph

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.

Screenshot: New issue choices on Gutenberg Repository

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

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.

Screenshot: mapk requested review from bph, youknowriad and jasmussen
Snippet from PR Dark mode UI updates

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.

Screenshot: PR approval with comment and note: "only review by reviewer with write access count towards mergeability"

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.

Screenshot: List of Reviewers

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!

Screenshot on WP Admin plugins page, showing plugins GitHub Updater and Gutenberg Nightly

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

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.