If you want to fix an issue or enhance others’ GitHub repository, don’t be afraid – it’s fairly simple. I will show by example all the steps that are necessary.
I wanted to add support for two languages (TypeScript and JSON) to a WordPress plugin providing a Code block. You can read more about my choice and configuration in WordPress for developers – displaying source code and review of code sharing services.
Table of contents
I assume you have a GitHub account. If not, create one.
Find the repository
Find the repository you want to fix. I wanted to add new features to WordPress plugin Advanced Gutenberg Blocks, so I visited its page and luckily found this section:
I followed the link to the Github repository hosting the source code for the plugin: https://github.com/maximebj/advanced-gutenberg-blocks.
Make a fork
Click the Fork button to copy the repository to your account:
You will see that now you own the copy and that you forked it from maximebj:
Find an issue to be fixed
Go to the original repository to the Issues tab and check if there is an issue that your contribution will fix. There was none in my case, so I skipped this step.
Look for files
CONTRIBUTING.md and read them carefully. These documents (especially the latter, if exists), describe how other authors can help fixing, what are the procedures, coding style, and so on. These files can be found in the root folder or in
Clone the repository
Once you are ready, you can get the source code – in Git world it is called cloning a repository.
Go to your repository in GitHub, press the Clone or download button and copy the link:
Now open a command shell, go to any folder you will want to host your source code in (there is no need to create a folder for this new project, it will be created automatically) and type
git clone <your-repo-url>:
c:\tmp> git clone https://github.com/lukaszmn/advanced-gutenberg-blocks.git Cloning into 'advanced-gutenberg-blocks'... remote: Enumerating objects: 209, done. remote: Counting objects: 100% (209/209), done. remote: Compressing objects: 100% (123/123), done. remote: Total 4805 (delta 97), reused 172 (delta 78), pack-reused 4596 Receiving objects: 100% (4805/4805), 15.65 MiB | 8.05 MiB/s, done. Resolving deltas: 100% (2957/2957), done.
Go to the created folder
cd advanced-gutenberg-blocks and run an editor here (e.g. Visual Studio Code by typing
c:\tmp> cd advanced-gutenberg-blocks c:\tmp\advanced-gutenberg-blocks> code .
Remember about the guidelines and don’t forget to update
README.md if necessary.
I changed 3 files:
You have to compile the application (if applicable), run test suite (if there is any) and run the application. How? Usually that information is contained in the
README.md file. In mine it stated:
Because my project is a WordPress plugin, I installed the original plugin and only substituted the files I edited.
First verify that only the files you edited are modified by running
c:\tmp\advanced-gutenberg-blocks> git status On branch master Your branch is up to date with 'origin/master'. Changes not staged for commit: (use "git add …" to update what will be committed) (use "git checkout -- …" to discard changes in working directory) modified: classes/Blocks/Code.php modified: public/templates/code.php modified: src/blocks/code/style.scss no changes added to commit (use "git add" and/or "git commit -a")
If all is good, create a commit which will give a name to your changes:
c:\tmp\advanced-gutenberg-blocks> git commit -a -m "Added support for JSON and TypeScript languages" [master 4204252] Added support for JSON and TypeScript languages 3 files changed, 6 insertions(+), 1 deletion(-)
After making the necessary commits, you are ready to send them to GitHub. Type
c:\tmp\advanced-gutenberg-blocks> git push Enumerating objects: 33, done. Counting objects: 100% (33/33), done. Delta compression using up to 2 threads. Compressing objects: 100% (18/18), done. Writing objects: 100% (19/19), 1.76 KiB | 901.00 KiB/s, done. Total 19 (delta 15), reused 0 (delta 0) remote: Resolving deltas: 100% (15/15), completed with 13 local objects. To https://github.com/lukaszmn/advanced-gutenberg-blocks.git 5c84eea..2857236 master -> master
Now verify that the commits went to GitHub. You can verify it quickly in your repository (This branch is … commits ahead of) or you can go to the Commits tab to check all the commits you pushed:
Create Pull Request
You are now ready to ask the original author to include your changes in his repository. This process is called a Pull Request.
Click the Pull request link. In the new page you will be able to compare your branch with the original repository under different angles, and finally, confirm to Create pull request.
Write a title and some description with an explanation of your changes (remember – this is all that the author will see and it may determine whether they will consider your change or reject it at start). Confirm once again and you are done.
You will see your Pull Request created in the original repository. Time to wait for discussion about it!
If the original author approves, rejects or comments on your Pull Request, you will get a notification.
What to do with your forked repository? You can keep it or delete it; you can find some discussion in a StackExchange thread.
If you’d like to learn a more advanced case with branching and refreshing repository, read GitHub Fork & Pull Request Workflow.