GitHub contribution by Pull Request – crash course

GitHub contribution by Pull Request – crash course

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.

GitHub account

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.

Guidelines

Look for files README.md, 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 .github folder.

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.

Edit files

Go to the created folder cd advanced-gutenberg-blocks and run an editor here (e.g. Visual Studio Code by typing code .):

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: classes\Blocks\Code.php, public\templates\code.php and src\blocks\code\style.scss.

Verify

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.

Commit

First verify that only the files you edited are modified by running git status:

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(-)

Push

After making the necessary commits, you are ready to send them to GitHub. Type git push

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!

Happy end

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.

Leave a Reply

avatar
  Subscribe  
Notify of