You’ll like it more or less, but Gutenberg, the WordPress block editor, is here to stay. The good thing is that being open source you can modify it as you please (if you know how).
Even more, if you find an error in the editor that you think should be resolved, you can either report it, or try to solve it yourself and upload the changes so that we all benefit from them. With this you will be contributing to improve the project as well as your good karma.
Do you know the steps to follow to contribute to the Gutenberg base code? Probably your answer is no. The same thing happened to me and I had to investigate it. So I will explain how to proceed to make it easier and faster for you to understand the whole process and then contribute to improve Gutenberg (if you wish) with your own code as a developer.
There is a lot to do and to improve, but it is at your fingertips to help to solve those problems that you find with the WordPress block editor.
Steps to Contribute to The Development of Gutenberg
Before I start, I’m going to assume that you have minimal knowledge of Git and that you have a GitHub account. If this is not the case, just go create one account and take a look at this tutorial to learn the basics.
Create a Fork of Gutenberg
The first thing you need to know is that the Gutenberg source code is hosted on GitHub in this code repository. The evolution of the project is done there.
This is where you have the Gutenberg code as a WordPress plugin. For each new version of the plugin, the stable version of the code base is transferred to the next version of the WordPress core. And that’s the way to go.
In order to contribute with code to the Gutenberg repository, the first thing we have to do is create a fork in our GitHub account. To do this we click on the Fork button that appears in the upper right corner, which you can see in the previous image.
This will create a repository in your GitHub account with the same features and code as the official one from WordPress. But since it is in an account that you control, you will have access to modify the code and do whatever you want with it. Basically, you have a copy.
Nelio Popups
Fantastic plugin! It’s really easy to create popups as you’re already used to the editor, and all the options it has are really well crafted.
Juan Hernando
Clone The Repository
Now you have your own Gutenberg repository connected to the original. It’s time to download it to your computer and work on it. To do this, open a terminal and execute the following command:
git clone https://github.com/your-user/gutenberg.gitRemember to replace your-user with the username you’re using on GitHub. This will create the gutenberg folder on your computer, downloading all the content of your GitHub repository locally.
Create a New Branch
If you access the new folder you will see that it contains everything that appears in the master branch of the repository (or main branch). You should not touch this branch with modifications, so before you go to modify the Gutenberg code, let’s see how to create a new branch.
If you do not know what a branch in Git is, I encourage you to read this article. Anyway, for what we’re going to do, you just need to know that branches in Git are the way to separate the modifications we make in the code of a repository, to maintain a certain order.
If I want to add a new functionality, I’ll create a new branch whose name identifies what I’m going to do, and then I’ll develop the functionality there. Once finished and when all my modified code is stable, I can merge that branch with the main branch (master, remember) and that’s it.
The Git commands to create a new branch and upload it to the repository are the following:
git checkout -b fix/clone-block
git push -u origin fix/clone-blockThis will create the fix/clone-block branch. Remember to change the name according to what you are going to do. According to Gutenberg’s contributor guide, you must use a name for your branch with prefix and description, such as: [type]/[change].
A good prefix is usually:
add/add a new functionalitytry/experimental functionality, for testing purposesupdate/update an existing functionalityfix/fix a problem
For example, fix/clone-block indicates that we are going to propose a fix when cloning blocks.
Apply Changes to The Code
Now, you have everything ready to open the files with the editor that you like the most and start programming. But before doing that you should know some things…
First, all the Gutenberg code follows a specific style guide that you must also respect. The specific details of how you to write the code are described here.
There are rules for CSS, JavaScript, and PHP. Adhere to these rules or you will surely have problems when getting your code accepted in the official repository.
FYI, in my case the modification I made was to use the lodash.cloneDeep() function in the attributes of a block when you clone a block with wp.blocks.cloneBlock() so that the copy is done in depth, to avoid having a shallow copy of the block we cloned. You can see the changes I made here.
Upload The Changes to The New Branch
Once you have finished, you must commit the changes and upload them to the repository. If you have created new files, you must first add them to the version control with the following command:
git add your-fileAnd, now, it’s time to commit the changes with this command:
git commit -am "Use cloneDeep when cloning a block"Finally, to upload the changes to the repository we have to use the following command:
git pushAfter that, if you go to the repository in GitHub you will see your changes uploaded in the branch that you have created. Perfect! We’re almost there…
Create a Pull Request in The Gutenberg Repository
We already made the changes and uploaded them into our repository. Now what we have to do is warn about the existence of our proposed changes to the developers who are responsible for managing the Gutenberg project.
For our changes to be discussed and approved to be part (or not) of the Gutenberg code base we need to do a pull request. A pull request is a request that the owner of a fork of a repository makes to the owner of the original repository so that the latter incorporates the commits that are in the fork.
To do this we go to our Gutenberg fork repository and click on the New pull request button. This brings us to a view in which to select the branch that we just uploaded with our changes. This will make the comparison with the main branch of the original Gutenberg repository:
When we select our branch in the drop-down selector on the right, as you see in the previous image, GitHub shows us a summary of the changes made in this branch with respect to the original Gutenberg repository.
Then we click on the Create pull request button. This will take us to another view in which we will have to fill in a text with the descriptive information of why we want to make these changes in the repository.
As you see in the following image, we already have a content template that we are asked to fill out:
Basically, you must include a description of your changes explaining what you have done and your reasons. You should also indicate if you have tested the code and how you have done it. You can even add screenshots if necessary.
Do not worry if you do not know very well how to fill it. The people who take care of the Gutenberg repository will help you.
When you are done, click on the Create pull request button so that your pull request is finally public. Now you just have to wait for other reviewers to take a look and eventually approve and merge your code into the official repository.
Keep in mind that this revision may take more or less time depending on many factors. In my case finally my pull request was closed and it did not prosper. But I learned a lot in the whole process. And the reviewers’ comments were always positive and constructive. You can see it here. But I kept working and finally got a pull request approved!
If you think there is something in Gutenberg that must change and you look forward to changing it in the code, now you know what the process is like. Besides, all that I have explained here is not only valid for Gutenberg. Most open source software projects work identically (or very similarly).
Don’t hesitate to contribute. Surely you’ll learn a lot along the way.
Featured image of Mike Erskine in Unsplash.
Leave a Reply