Getting Started with Contribution to Gutenberg

Gutenberg is based on node.js so if you know JavaScript, it will be easier to Contribute to the code base of Gutenberg. This post will enlighten you to the ways and approach to contribute to Gutenberg. 

Pre-requirements 

  1. A computer with a stable Operating System (preferred MacOX or any Linux distribution)
  2. Some Software installation 

Installation 

You need to install the following things before getting started 

  1. Nodejs
  2. Docker
  3. Git

Installing Nodejs
Go to https://nodejs.org/en/ and download the latest version of node and install it. 
You can also install node via terminal. 
For Mac: 
Run the following command:

sudo brew install node

XCode must be installed in your system to install node via terminal. If you do not have homebrew installed, run this command on the terminal: 

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

for Linux:
on Arch Linux: 

sudo pacman -S nodejs npm


on Debina, Mint, Ubuntu: 

sudo apt-get install nodejs npm

on CentOS and RHEL:

sudo yum install epel-release && sudo yum install nodejs npm

To check if node is installed to your system, you can run the following command on your terminal: 

node -v

Let’s install Docker. 

To install Docker, the best ways is to download the file from here and depending on your operating system, run the installer. 

If you are lazy and don’t want to do that much hassle of installing the above things. You can run a script. Before that, you need to clone the Gutenberg repository from Github

Clone Gutenberg repository and set up local the environmet

Make sure git is installed to your system. If not, install git as follow: 

On Mac:

If you have Homebrew installed you can do the following command 

brew update && brew install git

If your HomeBrew is not installed, go to Homebrew website and run the command shown there which is similar to the following command. 

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

And then run the previous command to install git. 

On Linux: 

On Debian or Ubuntu, run the following command : 

sudo apt-get install git

On CentOS: 

sudo yum install git

On Fedora:

sudo yum install git-core

On Arch Linux:

sudo pacman -Sy git

On Windows:

You can go to https://git-scm.com/download/win and download the installer file and install it like the other PC software.

Once you have installed git, docker and node we are almost ready to start contributing. 

There are a lot of ways you can work with your code, I preferrer Terminal. In this tutorial the whole thing will be discussed using Terminal. If you face any problem using Terminal and want to use the other ways, don’t feel shy to comment on the comment section below. 

So, fire up your Terminal and change the directory to a suitable location of your computer. I prefer the Desktop and will create a new folder named GutenDevCode. See the following Terminal for clarification.

Changing the directory and creating a fresh directory

Here cd = change directory
mkdir = make directory ; “mkdir GutenDevCode” will make a folder named GutenDevCode

Now we will clone the git repo of Gutenberg. Remember to fork the reposoitory from the Github website. Follow the following Terminal.

Cloning the Git repo

Here, git clone https://github.com/WordPress/gutenberg.git command will clone the Gutenberg repository inside the GutenDevCode folder. Cloning might take a while depending on your internet speed. So, you can grab a mug of coffee in the meanwhile.  Once the repository is cloned, let’s proceed to the next step.  

Cloning Gutenberg repository : downloading the files

Once your repository is cloned, you will get a message on the Terminal. type ls and hit return to see if the repository is cloned. You can also run du -sh * command to check the file size of Gutenberg. It is close to 44MB. 

Repository cloned successfully 

Now, change the directory to gutenberg using cd gutenberg command. Now you are inside the gutenberg directory. To see all the files and folders inside the gutenberg folder use ls command. 

Inside gutenberg folder

From now on, I will split my screen into few sections to work without hassle. I’m using tmux to split my terminal, you can use other programs if you want or open multiple tabs on the Terminal. 

Getting started

First of all, we will run the ./bin/setup-local-env.sh file with the root permission after the Gutenberg repository is cloned.  Once you run the script, you will be prompted to install the missing things required. 

 ./bin/setup-local-env.sh
In my case, NVM was not installed

Then you need to run the following command to set the path of NVM. 

. $HOME/.nvm/nvm.sh

It might show you an error that you have not installed the latest version of NVM, so you need to install NVM with the following command. 

nvm install lts/*

You should not use the root privilege for installing NVM unless needed. 

You will also install some packages after running ./bin/setup-local-env.sh . 

Please note that your docker must run at the time of executing the above command. Otherwise, it will return an error. 

If you’re developing themes, or core WordPress functionality alongside Gutenberg, you can make the WordPress files accessible in wordpress/ by following these instructions instead:

  1. If this is your first time setting up the environment, run DOCKER_ENV=localwpdev ./bin/setup-local-env.sh instead of ./bin/setup-local-env.sh
  2. If you’ve already had the previous environment set up, you need to start fresh, and you can do that by first running docker-compose down --rmi all. After that, you can repeat step 1.
  3. If you turn off your computer or restart Docker, you can get your local WordPress dev environment back by typing docker-compose -f docker-compose.yml -f docker-compose-localdev.yml up. If you just run docker-compose up, you will get the vanilla install that doesn’t expose the WordPress folder.

If everything was successful, you’ll see the following ASCII art:

Welcome to...

,⁻⁻⁻·       .                 |
|  ،⁓’.   . |---  ,---. ,---. |---. ,---. ,---. ,---.
|   | |   | |     |---' |   | |   | |---' |     |   |
`---' `---' `---’ `---’ '   ` `---' `---’ `     `---|
                                                `---'

The WordPress installation should be available at http://localhost:8888 (UsernameadminPasswordpassword). Inside the “docker” directory, you can use any docker command to interact with your containers. If this port is in use, you can override it in your docker-compose.override.yml file. If you’re running e2e tests, this change will be used correctly.

To bring down this local WordPress instance later run:

docker-compose down

If you’d like to see your changes reflected in this local WordPress instance, run:

npm install
npm run dev

Alternatively, you can use your own local WordPress environment and clone this repository right into your wp-content/plugins directory.

Next, open a terminal (or if on Windows, a command prompt) and navigate to the repository you cloned. Now type npm install to get the dependencies all set up. Then you can type npm run dev in your terminal or command prompt to keep the plugin building in the background as you work on it.

On A Remote Server

Open a terminal (or if on Windows, a command prompt) and navigate to the repository you cloned. Now type npm installto get the dependencies all set up. Once that finishes, you can type npm run build. You can now upload the entire repository to your wp-content/plugins directory on your web server and activate the plugin from the WordPress admin.

You can also type npm run package-plugin which will run the two commands above and create a zip file automatically for you which you can use to install Gutenberg through the WordPress admin.

Workflow

A good workflow for new contributors to follow is listed below:

  • Fork Gutenberg repository
  • Clone forked repository
  • Create a new branch
  • Make code changes
  • Commit code changes within the newly created branch
  • Push branch to forked repository
  • Submit Pull Request to Gutenberg repository

Ideally name your branches with prefixes and descriptions, like this: [type]/[change]. A good prefix would be:

  • add/ = add a new feature
  • try/ = experimental feature, “tentatively add”
  • update/ = update an existing feature

For example, add/gallery-block means you’re working on adding a new gallery block.

You can pick among all the tickets, or some of the ones labelled Good First Issue.

The workflow is documented in greater detail in the repository management document.

Testing

Gutenberg contains both PHP and JavaScript code and encourages testing and code style linting for both. It also incorporates end-to-end testing using Google Puppeteer. You can find out more details in Testing Overview document.

Managing Packages

This repository uses lerna to manage Gutenberg modules and publish them as packages to npm.

Creating a New Package

When creating a new package, you need to provide at least the following:

  1. package.json based on the template:{ “name”: “@wordpress/package-name”, “version”: “1.0.0-beta.0”, “description”: “Package description.”, “author”: “The WordPress Contributors”, “license”: “GPL-2.0-or-later”, “keywords”: [ “wordpress” ], “homepage”: “https://github.com/WordPress/gutenberg/tree/master/packages/package-name/README.md”, “repository”: { “type”: “git”, “url”: “https://github.com/WordPress/gutenberg.git” }, “bugs”: { “url”: “https://github.com/WordPress/gutenberg/issues” }, “main”: “build/index.js”, “module”: “build-module/index.js”, “react-native”: “src/index”, “dependencies”: { “@babel/runtime”: “^7.0.0” }, “publishConfig”: { “access”: “public” } }This assumes that your code is located in the src folder and will be transpiled with Babel.
  2. .npmrc file which disables creating package-lock.json file for the package:package-lock=false
  3. README.md file containing at least:
    • Package name
    • Package description
    • Installation details
    • Usage example
    • Code is Poetry logo (<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>)

Maintaining Changelogs

Maintaining dozens of npm packages is difficult—it can be tough to keep track of changes. That’s why we use CHANGELOG.mdfiles for each package to simplify the release process. All packages should follow the Semantic Versioning (semver) specification.

The developer who proposes a change (pull request) is responsible for choosing the correct version increment (majorminor, or patch) according to the following guidelines:

  • Major version X (X.y.z | X > 0) should be changed with any backward incompatible/”breaking” change. This will usually occur at the final stage of deprecating and removing of a feature.
  • Minor version Y (x.Y.z | x > 0) should be changed when you add functionality or change functionality in a backward compatible manner. It must be incremented if any public API functionality is marked as deprecated.
  • Patch version Z (x.y.Z | x > 0) should be incremented when you make backward compatible bug fixes.

When in doubt, refer to Semantic Versioning specification.

Example:

## v1.2.2 (Unreleased)

### Bug Fix

- ...
- ...
  • If you need to add something considered a bug fix, you add the item to Bug Fix section and leave the version as 1.2.2.
  • If it’s a new feature, you add the item to New Feature section and change version to 1.3.0.
  • If it’s a breaking change you want to introduce, add the item to Breaking Change section and bump the version to 2.0.0.
  • If you struggle to classify a change as one of the above, then it might be not necessary to include it.

The version bump is only necessary if one of the following applies:

  • There are no other unreleased changes.
  • The type of change you’re introducing is incompatible (more severe) than the other unreleased changes.

Releasing Packages

Lerna automatically releases all outdated packages. To check which packages are outdated and will be released, type npm run publish:check.

If you have the ability to publish packages, you must have 2FA enabled on your npm account.

Before Releasing

Confirm that you’re logged in to npm, by running npm whoami. If you’re not logged in, run npm adduser to login.

If you’re publishing a new package, ensure that its package.json file contains the correct publishConfig settings:

{
	"publishConfig": {
		"access": "public"
	}
}

You can check your package configs by running npm run lint-pkg-json.

Development Release

Run the following command to release a dev version of the outdated packages, replacing 123456 with your 2FA code. Make sure you’re using a freshly generated 2FA code, rather than one that’s about to timeout. This is a little cumbersome but helps to prevent the release process from dying mid-deploy.

NPM_CONFIG_OTP=123456 npm run publish:dev

Lerna will ask you which version number you want to choose for each package. For a dev release, you’ll more likely want to choose the “prerelease” option. Repeat the same for all the outdated packages and confirm your version updates.

Lerna will then publish to npm, commit the package.json changes and create the git tags.

Production Release

To release a production version for the outdated packages, run the following command, replacing 123456 with your (freshly generated, as above) 2FA code:

NPM_CONFIG_OTP=123456 npm run publish:prod

Choose the correct version based on CHANGELOG.md files, confirm your choices and let Lerna do its magic.

How Can Designers Contribute?

If you’d like to contribute to the design or front-end, feel free to contribute to tickets labelled Needs Design or Needs Design Feedback. We could use your thoughtful replies, mockups, animatics, sketches, doodles. Proposed changes are best done as minimal and specific iterations on the work that precedes it so we can compare. If you use Sketch, you can grab the source file for the mockups (updated April 6th).

Contribute to the Documentation

Documentation is automatically synced from master to the Gutenberg Documentation Website every 15 minutes.

To add a new documentation page, you’ll have to create a Markdown file in the docs folder and add an item to the root-manifest.json.

@wordpress/component

If you’re contributing to the documentation of any component from the @wordpress/component package, take a look at its guidelines for contributing.

Reporting Security Issues

Please see SECURITY.md.

Localizing Gutenberg Plugin

To translate Gutenberg in your locale or language, select your locale here and translate Development (which contains the plugin’s string) and/or Development Readme (please translate what you see in the Details tab of the plugin page).

A Global Translation Editor (GTE) or Project Translation Editor (PTE) with suitable rights will process your translations in due time.

Language packs are automatically generated once 95% of the plugin’s strings are translated and approved for a locale.

The eventual inclusion of Gutenberg into WordPress core means that more than 51% of WordPress installations running a translated WordPress installation will have Gutenberg’s translated strings compiled into the core language pack as well.