The error message failed to authenticate via web browser: Too many requests have been made in the same timeframe. (slow_down) appeared on my terminal, while on the web browser, it indicated that the authentication was successful.

I googled and found some workarounds that I tried, but only one worked like a charm!

After finally solving the tricky authentication issue for GitHub CLI on WSL2, I've put together this guide. It's a complete walkthrough for a solution that works, covering everything from a smooth installation to ongoing management.

Table of Contents

• Prerequisites

• How to Install GitHub CLI on WSL2

• How to Authenticate GitHub CLI on WSL2 with Your GitHub Account

• How to Upgrade GitHub CLI on WSL2

• How to Uninstall GitHub CLI on WSL2

• How to Revoke GitHub CLI Access on GitHub

• Final Words

Prerequisites

Before getting started, ensure that you have these installed on your Windows machine:

• WSL2

• A Linux distro

• Windows PowerShell

• Windows Terminal (optional)

To follow the instructions in this article, you can use Windows PowerShell terminal as an administrator.

Alternatively, if you have Windows Terminal installed, you can use the Linux terminal by clicking the ‘down arrow’ icon at the top and selecting the distro.

How to Install GitHub CLI on WSL2

You can use the installation process described here if you use Ubuntu, Debian, or Raspberry Pi OS (apt) distros. For other distros other than those mentioned here, you can walk through the installation process that's available on the GitHub CLI official docs.

To install GitHub CLI in WSL2:

1. Run this command:

    (type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
        && sudo mkdir -p -m 755 /etc/apt/keyrings \
        && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
        && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
        && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
        && sudo mkdir -p -m 755 /etc/apt/sources.list.d \
        && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
        && sudo apt update \
        && sudo apt install gh -y
   

2. Type your Linux password when you get prompted.

3. Ensure the GitHub CLI is installed by running gh --version command. If the installation is successful, you should see something like this in your terminal:

    gh version 2.76.2 (2025-07-30)
    https://github.com/cli/cli/releases/tag/v2.76.2
   

How to Authenticate GitHub CLI on WSL2 with Your GitHub Account

Before you can use GitHub CLI, you must first authenticate it. You will get an HTTP 401: Bad credentials (https://api.github.com/graphql) error message if you run any GitHub CLI command without authenticating.

To authenticate GitHub CLI with your GitHub account:

1. Run the gh auth login command in your terminal.

2. You will receive several prompts, and you need to choose the methods you prefer. Here’s what I selected in each prompt:

    ? Where do you use GitHub? GitHub.com
    ? What is your preferred protocol for Git operations on this host? HTTPS
    ? How would you like to authenticate GitHub CLI? Login with a web browser
   

   After answering all prompts, you should get the message to copy a one-time code as shown below. You don’t need to copy the code at this point.

    ! First copy your one-time code: XXXX—XXXX
   

3. Press ‘Enter’. It automatically opens the "Device Activation" page on your browser.

4. Click the green ‘Continue’ button.

   

   GitHub should ask you to enter the code displayed on your terminal, as shown in the screenshot below. But here’s the trick! Don’t paste any code, and don’t close the browser. Let’s first get back to your terminal.

   

   Now you might get this error message on your terminal:

    grep: /proc/sys/fs/binfmt_misc/WSLInterop: No such file or directory
    WSL Interopability is disabled. Please enable it before using WSL.
    grep: /proc/sys/fs/binfmt_misc/WSLInterop: No such file or directory
    [error] WSL Interoperability is disabled. Please enable it before using WSL.
   

5. Press Ctrl + C to stop the process if it's still running, or let it stop by itself. Once it's stopped, you should see this message:

    failed to authenticate via web browser: Too many requests have been made in the same timeframe. (slow_down)
   

6. Run the gh auth login command again and repeat the process to select the methods of your choice. This time, when it asks you to press ‘Enter’, don’t press it.

7. Copy the latest code and return to the "Device Activation" page that you left open in your browser.

8. Paste the code that you copied and click the green ‘Continue’ button.

9. Click the green ‘Authorize github’ button after GitHub redirects you to the “Authorize GitHub CLI” page. You should now see the message “Congratulations, you're all set!”

10. Get back to your terminal and press ‘Enter’. Doing so triggers these actions:

    • It automatically opens a new “Device Activation” page in your browser. You can safely ignore this.

    • In the terminal, you first see the error message as in step 4. Don’t do anything and wait for a little bit. Then, you get:

        ✓ Authentication complete.
        - gh config set -h github.com git_protocol https
        ✓ Configured git protocol
        ! Authentication credentials saved in plain text
        ✓ Logged in as YOUR-GITHUB-USERNAME
        ! You were already logged in to this account
      

And GitHub CLI is now successfully authenticated!

Credit goes to username “ikeyan” on GitHub for their GitHub CLI authentication solution!

How to Upgrade GitHub CLI on WSL2

It’s always a good practice to regularly check for package and dependency updates, and upgrade to the newest version when it’s available — this includes GitHub CLI. To check for updates and upgrade the version of GitHub CLI:

1. Run the sudo apt update command in your terminal. This command fetches the list of available updates.

2. Type your Linux password when you get prompted.

3. If you need to upgrade your GitHub CLI, run sudo apt install gh. This command installs the newest version of GitHub CLI.

4. Type your Linux password when you get prompted.

Now your GitHub CLI has the newest version.

How to Uninstall GitHub CLI on WSL2

If one day you feel like you don’t need to use GitHub CLI anymore, you can uninstall it by following these steps:

1. Run the sudo apt remove gh command in your terminal.

2. Type your Linux password when you get prompted.

3. Press ‘Y’ to continue the uninstall process.

GitHub CLI is now uninstalled from your WSL environment.

How to Revoke GitHub CLI Access on GitHub

After uninstalling the GitHub CLI, you might think your account access is gone, but it's not. The authentication you granted is still active. If you don't plan on using the CLI again, it's a good practice to revoke this access.

Here's how to do it directly from your GitHub account:

1. On your GitHub account, click your profile picture on the top right and click ‘Settings’.

   

   2. On the left side bar, find ‘Integrations’ and click ‘Applications’.

      

   3. Click the ‘Authorized OAuth Apps’ tab on top.

      

   4. Find GitHub CLI and click the ‘three dots’ icon next to it.

   5. Click ‘Revoke’.

      

   6. Confirm it by clicking the ‘I understand, revoke access’ button.

Now, GitHub CLI doesn’t have access to your GitHub account.

Final Words

🖼️ Credit cover image: undraw.co

Thank you for reading! Last, you can find me on X and LinkedIn. Let's connect! 😊

When you write a long blog post or an article with independent sections, consider adding a table of contents. It can help your readers understand your article's content and know what's coming. Providing hyperlinks to each title in the table of contents helps readers navigate between the sections they want to check out.

Having a table of contents in your articles also benefits you as a writer. First, you can easily see the flow of your article. Another benefit is that it can increase your blog's traffic. If your readers have a great experience reading your article, they will likely bookmark and return to it.

Some publications use Ghost to write and publish articles on their website, and freeCodeCamp is one of them. In this article, I will walk you through how to add a clickable table of contents to your article on Ghost.

Table of Contents

• Understanding Headings
• How to Add a Table of Contents
  • Step #1 - Create a List of Headings
    • Create a List of One-Level Headings
    • Create a List with Subheadings
  • Step #2 - Inspect a Heading and Find the id
  • Step #3 - Add the Link
    • Add a Link to a Heading
    • Add a Link to a Heading in HTML
    • Why Does the Link Not Work?
• Final Words

Understanding Headings

Before we jump into how to add a table of contents, let's take a moment to understand "headings" because I will use this term going forward.

Headings are titles of sections and subsections that are displayed on a website.

There are six levels of headings based on the importance of the section.

Levels of headings – H1 - H6

Following best practices, a page on a website should only have one heading level 1 (known as h1). It is the main title of the page. In your case, it'll be the main title of your article. (In this article, it's "How to Add a Table of Contents to Your Article on Ghost".)

So, writing an article on Ghost (or any other publication platform) leaves you with h2 to h6 for your section and subsection titles. And you can use as many of them as you need depending on the hierarchy and organization of your content.

How to Add a Table of Contents

You can create your table of contents whenever you want – before you write, during the process, or after you finish writing your article.

But you can only add the link to each chapter or section title after writing your article. This is because you'll need to know exactly how the text of the headings will appear in order to link to them properly, as you'll see below.

In this guide, I'll show you how to build a ToC in HTML, which allows you to add subheadings in addition to main headings/section titles.

Step #1 - Create a List of Headings

You can create a table of contents with a list of one-level headings (h2) or include the subheadings (h3 to h6) if you want to.

You can also choose how you want to format your list:

• Unordered List: A list with bullet points.
• Ordered List: A list with numbers.

Create a List of One-Level Headings

Follow these steps to create a one-level headings list:

1. Insert a new line.
2. Type a dash (-) or an asterisk (*) for the unordered list. Or, type a number and add a period — for example, 1. — for the ordered list.
3. Hit the spacebar.
4. Add the title.
5. Click enter to add a new item in the list.

Add an unordered and an ordered list.

Note: You can skip the next section and go directly to "Step #2 - Inspect a Heading and Find the id" if you want.

Create a List with Subheadings

If you wish to create a list with subheadings (nested list), you must use HTML to format it manually, as Ghost doesn't have nested list options built into the editor.

First, you need to add the HTML card:

1. Start on a new line.
2. When your cursor is on the new line, you will see a plus (+) icon button in the circle on the left. Click this button.
3. Click the "HTML" option.

A plus sign and an "HTML" option on Ghost.

Afterward, you will see the HTML card, as shown in the image below.

HTML card on Ghost.

Now, let's start adding the list of your headings and subheadings.

Add an HTML unordered list (<ul></ul>) or an ordered list (<ol></ol>) element.

<ul></ul>

or

<ol></ol>

To add the list of your headings, add a space between the ul or ol tags. Put the cursor between the tags and hit enter twice.

<ul>

</ul>

Then, add list elements (<li></li>) in the empty line between the opening and closing ul or ol tags. Add these list elements based on the number of your section titles.

<ul>
    <li></li>
    <li></li>
    <li></li>
</ul>

Afterward, put each of the titles between the li tags.

<ul>
    <li>Heading 2 - Part 1</li>
    <li>Heading 2 - Part 2</li>
    <li>Heading 2 - Part 3</li>
</ul>

To add subheadings, repeat all the steps. But now, you should put the ul or ol element inside the li element(s) that hold the section title. Here's how to do it:

1. Place your cursor between the end of the section title and the </li> tag, then click enter.
2. Click enter again to add a space and add an ul or ol element for the subheadings.
3. Add an ul or ol element in the new line, put the cursor between the tags, and hit enter twice to add a space.
4. Add li element(s) in the new line between the ul or ol tags.
5. Put the subsection title between the li tags.

Creating a nested list in HTML.

Below is an example of a table of contents with subheadings in HTML.

<ul>
    <li>Heading 2 - Part 1
        <ul>
            <li>Heading 3</li>
            <li>Heading 3</li>
        </ul>
    </li>
    <li>Heading 2 - Part 2
        <ul>
            <li>Heading 3
                <ul>
                    <li>Heading 4</li>
                </ul>
            </li>
        </ul>
    </li>
    <li>Heading 2 - Part 3</li>
</ul>

And the result will look like this:

A list of section and subsection titles.

Step #2 - Inspect a Heading and Find the id

After creating the list, it's time to add the links to the titles in your table of contents.

But first, you need to find the id attribute of your heading using preview mode by inspecting the title with your browser's (Chrome or Firefox) developer tools.

So, let's open your preview mode:

1. Click the gear icon on the top right of your Ghost editor.
2. Click the "Preview" link beside the "Post URL" input.

The "Preview" link is in the "Post settings" on Ghost.

Now that you are in the preview mode, right-click your mouse. You will see some options. Click the "Inspect" option to open the developer tools.

"Inspect" option on Chrome.

In the developer tools, let's click the button with a box and arrow icon on the top left to select a heading element on the page and inspect it.

"Select an element in the page to inspect it" button in the developer tools on Chrome.

Hover over a title and click on it. It will highlight the element you want to inspect in the developer tools. Inside the heading element (h2 to h6), you will see an id (shown with a red line in the image below).

Inspect a heading with developer tools on Chrome.

Double-click on the value inside the quote marks of the id and copy it. You will use it to add the link to the title in the table of contents.

Note:

• If you created a list of one-level headings, head to the "Add a Link to a Heading" section.
• If you made a list with subheadings, go to the "Add a Link to a Heading in HTML" section.

Step #3 - Add the Link

Add a Link to a Heading

To add the link, return to your table of contents in the Ghost editor. Then, follow these steps:

1. Highlight the title that you want to add the link to.
2. Click the chain icon.
3. Type a hashtag (#) in the input field and paste your copied id value.

So, it will be like this:

Highlighting a list and a chain icon on Ghost.

#understanding-headings

After you refresh the preview page, check if the link works. It should take you to the target section when you click the title's link. If not, read the "Why Does the Link Not Work?" section.

Add a Link to a Heading in HTML

First, let's return to your Ghost editor and go to the li element that holds the title in the table of contents.

Then, wrap the title inside an anchor element (<a></a>) and add href="" attribute in the opening tag.

<ul>
    <li><a href="">Understanding Headings</a></li>
</ul>

The anchor element creates a hyperlink, and the href attribute is the placeholder for the link's destination.

Now, you will add the link's destination. Type a hashtag (#) and paste the id value you've copied inside the double quotes of the href.

<ul>
    <li><a href="#understanding-headings">Understanding Headings</a></li>
</ul>

Repeat all the steps to add a link for each title.

Below is an example of section and subsection titles with links in HTML:

<ul>
    <li><a href="#understanding-headings">Understanding Headings</a></li>
    <li><a href="#adding-a-table-of-content">Adding a Table of Content</a>
        <ul>
            <li><a href="#step-1-create-a-list-of-titles">Step #1 - Create a List of Titles</a></li>
        </ul>
    </li>
</ul>

After refreshing the preview page, you can now check if the link works by clicking it. If it doesn't work, read the next section.

Why Does the Link Not Work?

If you click a link in your table of contents and it goes nowhere or redirects you to a "404 Page not found", return to the preview page. Refresh it, and try to click the link again.

If it still does the same, you need to check the link in the Ghost editor.

Sometimes, it can be a typo where you change the title but still need to update the link. Or there is a missing hashtag (#) in the link.

Final Words

If you liked and found this article helpful, please share it with others. You can find other works on my blog. Let's connect on X (formerly Twitter) or LinkedIn.

Hey {username}, we've merged a PR before yours. Please resolve the merge conflicts so we can review and merge your PR.

Have you ever received that kind of message from a maintainer while waiting for your pull request to be reviewed and merged? And then, you're panicking because you don't know what to do? Or maybe you're thinking of closing your pull request, redoing everything from scratch, and opening a new pull request?

Well, the good news is you're not alone.

In this article, I will show you how to keep your remote and local branches up to date. I'll also walk you through resolving merge conflicts in GitHub and VS Code.

Table of Contents

• Prerequisites
• Understanding Merge Conflicts
• How to Keep the Branches Up to Date
  • How to Update the main Branch in Your Forked Repository
  • How to Update Your Local Branch
• How to Resolve Merge Conflicts
  • 1. Resolving Merge Conflicts on GitHub
  • 2. Resolving Merge Conflicts in VS Code
• Final Words

Prerequisites

To follow along with this tutorial, you'll need the following:

• A GitHub account.
• VS Code installed on your machine.

Understanding Merge Conflicts

Merge conflicts usually occur when two commits have changes in the same line(s) of the same file(s) from two different branches. Sometimes, it can also happen when someone edits a file, and another person deletes it.

The thing is, Git can't resolve the conflict itself. It needs your help to decide which changes need to be kept.

When there's a merge conflict, you will see a notification in your pull request on GitHub that the branch has conflicts that must be resolved. Maintainers can't merge a pull request when merge conflicts happen. That's because the merge button is deactivated until the conflicts are resolved.

Warning on a GitHub's pull request: This branch has conflicts that must be resolved

How to Keep the Branches Up to Date

Keeping your branches up to date is crucial. Habitually updating your remote and local main and working branches is highly recommended.

The best times to update your branches are:

• before you create a new branch to work on an issue,
• after you commit your last changes and before you push them to the remote repo,
• while you are waiting for your pull request to be reviewed.

When a pull request gets merged while you wait for yours to be reviewed, there will be a warning in your pull request. It tells you that your branch is behind the upstream (original) repository's main branch.

Warning on a GitHub pull request: This branch is out-of-date with the base branch.

How to Update the main Branch in Your Forked Repository

1. Go to your forked repository on GitHub.
2. Click the "Sync fork" button.
3. Click the green "Update branch" button.

"Sync fork" and "Update branch" buttons on GitHub.

After you update the branch, you will see a notification on the top that your branch is up to date.

A notification on GitHub: This branch is up to date with organization-name/repository-name:main.

How to Update Your Local Branch

Now, your remote main branch has been updated. Let's update your local branch from your terminal.

Step #1 - Go to Your Working Branch

In your terminal, navigate to your working branch with this command:

git checkout branch-name

Step #2 - Pull the Changes

Pull the latest changes from the main branch of your origin (forked) repository to your local branch.

git pull origin main

Step #3 - Push the Changes

Push these changes to your remote branch. If you need to resolve conflicts, you must fix them before you can push your changes.

git push

How to Resolve Merge Conflicts

You can only start to resolve the merge conflicts after your working branch is up to date. There are two ways to resolve the conflicts:

1. On GitHub
2. In your VS Code

1. Resolving Merge Conflicts on GitHub

Resolving the conflicts directly on GitHub is only possible when the cause of the conflicts is that there are changes in the same line(s) of the same file(s) from two different branches. For any other type of conflicts, you must resolve them locally in your code editor.

Follow these steps to resolve conflicts directly on GitHub:

Step #1 - Click the "Resolve conflicts" Button

First, go to the upstream repository on GitHub. Then, click the "Pull request" tab. Find and open your pull request, and scroll down.

Towards the end, you will find the "Resolve conflicts" button.

A notification of "This branch has conflicts that must be resolved" and a "Resolve conflicts" button on GitHub.

Step #2 - Take a Closer Look at the Conflicts

After clicking the "Resolve conflicts" button, you will be redirected to GitHub's conflict editor.

GitHub's conflict editor

You can see the file(s) that has conflicts on the left sidebar. On the top bar, you can find the number of conflicts in the file. And in the file itself, there are conflict markers <<<<<<<, =======, and >>>>>>>.

The lines between <<<<<<< branch-name and ======= are your changes. Anything between ======= and >>>>>>> main are the changes from the main branch of the upstream repository.

You need to look at the conflicts and decide which one you want to keep or if you need to make entirely new changes.

Step #3 - Resolving the Conflicts

After you decide how you want to resolve the conflicts, delete the conflict markers <<<<<<<, =======, >>>>>>>. Then you can make the changes. If there are several conflicts in the file, scroll down and resolve them before you mark them as resolved.

Once you resolved all conflicts, click the "Mark as resolved" button at the top bar.

"Mark as resolved" button on GitHub.

If there are conflicts in another file(s), go to the file by clicking the file name at the left sidebar. And then repeat the same steps to resolve the conflicts.

Step #4 - Click the "Commit merge" Button

After all conflicts in all conflicting files have been marked as resolved, a green "Commit merge" button will appear on the top right. Click the button to commit your changes.

A "Commit merge" button on GitHub.

2. Resolving Merge Conflicts in VS Code

After you pulled the latest changes from the main branch of your forked repository, you will see line(s) between the conflict markers <<<<<<<, =======, and >>>>>>>.

You will also see the options for resolving the conflicts:

• Accept Current Change: When you want to keep only your changes.
• Accept Incoming Change: When you want to keep only the changes from the main branch.
• Accept Both Changes: When you wish to keep yours and the incoming changes.

Merge conflicts on VS Code.

The line(s) between <<<<<<< HEAD (Current Change) and ======= are your changes. And anything between ======= and >>>>>>> hash-numbers (Incoming Change) are changes from the main branch of your forked repository.

Follow these steps to resolve the conflicts in VS Code:

Step #1 - Resolving the Conflicts

Take a closer look at the conflicts between the conflict markers. Then, you need to decide how you want to resolve the conflicts.

• You can manually delete the markers <<<<<<<, =======, >>>>>>> and make the changes.

OR

• You can choose and click one of the acceptance options on the top and modify the changes based on your needs.

Undo the Merging

If at one point you feel confused and want to undo the merge and redo everything from scratch, run the git merge --abort command before committing your changes. It will abort the merge and return your file to the state before the conflicts.

Step #2 - Commit Your Changes

Once you finished resolving the conflicts, you must commit your changes. Run this command to automatically stage and commit the changes:

git commit -am "Your message"

Understanding git commit -am Command

The command git commit -am is different from running git add . followed by git commit -m.

Running git add . will add all files (including newly created files) to the staging area. While adding the -a flag to the git commit, it will automatically stage any files you have committed before. It includes staging deleted tracked files but will not stage newly created files.

So, combining the -a with -m flag to git commit allows you to skip the staging phase and directly write the message for the commit.

Step #3 - Push Your Changes

Now, you can push your changes to the remote branch with the following command:

git push

Final Words

If you liked and found this article helpful, please share it with others. You can find other works on my blog, and let's connect on X (formerly Twitter) or LinkedIn.

You might think, "You can't count that as an open source contribution. That's a joke!"

I had the same thought myself — until recently. Getting my feet wet in open source was daunting, yet I got through it. And looking back, I learned a ton from that first contribution.

As a newbie who didn't know anything about open source, I learned how to communicate with the maintainers, how to work with Git and GitHub, and how to create a pull request. It was a big learning curve!

That is one of the reasons why I wrote this guide: to make your journey in contributing to open-source projects smoother and less daunting.

In this guide, I'll walk you through the basic Git and GitHub workflow when contributing to open-source projects. I'll also explain how to synchronize your forked and local repositories with the original repository and how to resolve merge conflicts when you encounter one.

Without further ado, let's get started!

Table of Contents

• Prerequisites
• Are all GitHub Projects Open Source?
• How to Fork a Repository
• How to Clone a Repository
• How to Create a New Branch
• How to Add Changes to the Staging Area
• How to Commit Changes
• How to Synchronize Changes
• How to Resolve Merge Conflicts
• How to Push Changes
• How to Create a Pull Request
• Final Words

Prerequisites

To follow along with this tutorial, you'll need the following:

• A GitHub account.
• A code editor like VSCode installed on your machine.

Are all GitHub Projects Open Source?

When you're interested in making contributions, you should make sure that the project you're interested in is open source. You can't assume that all projects on GitHub are open source.

In this section, I will share what you should check to know if a project is open source.

The License

The license is the first thing you want to check. A project on GitHub is not an open source unless it has a license.

In most jurisdictions, a project without a license is automatically licensed as "All Rights Reserved" by its owner. It means that no one may use, modify, or redistribute anything in the project without the permission of the owner. If you ignore it, they can legally sue you.

You can find the license in a file called LICENSE. You'd usually see in the "About" section of the repository.

An MIT license in the "About" section on the right sidebar of a repository on GitHub

The Contribution Guide

Most open-source projects are ready to receive contributions when it has a contribution guide. This guide contains everything you should know about how to contribute to the project, from opening an issue to creating a pull request. From the code of conduct to the expected communication style.

The procedures and requirements for contributing to open-source projects may differ from one to another. You always want to read and follow the guide when contributing to a project.

Usually, you'll find a section about the contributing guide on the README. But if you can't find it there, look for a file called CONTRIBUTING.md or anything similar.

Hacktoberfest Topic

Hacktoberfest is a yearly event in October sponsored by DigitalOcean to support open source.

To participate in this event and get your pull requests reviewed and counted, you should check whether a project is involved in Hacktoberfest before contributing.

A project participating in the event should have a hacktoberfest topic that you can find tagged in the "About" section of the repository's main page.

The "About" section on the right sidebar of a repository with hacktoberfest as one of the topics — Credit: AliceWonderland/hacktoberfest

How to Fork a Repository

So, you're ready to contribute to a repository of your choice. The first thing that you should do is to fork the repository.

Fork means creating a copy of a repository in your GitHub account.

You always want to fork a repository because most open-source project owners don't authorize contributors to push changes directly to their repositories.

By convention, your forked repository is called the origin repository, while the original repository is the upstream repository. I will use these aliases from now on to differentiate them.

At the repository's main page on GitHub, click the Fork button at the top right:

Fork button on GitHub

It will redirect you to the "Create a new fork" form. You can leave the inputs as it is. Then, click the green "Create fork" button at the bottom.

A Create a new fork form with a green Create fork button on GitHub

This will create a copy of the repository in your GitHub account.

How to Clone a Repository

After forking the repository, the next thing to do is to clone it.

Cloning a repo means creating a copy of a repository in your local environment. You should clone your forked repository when contributing to an open-source project.

Here are the steps to follow:

Step #1 - Navigate to the forked repo

Navigate to your forked repository with these steps:

• Click your avatar on the top right.
• Click Your repositories on the dropdown menu.
• Click the repository that you want to clone to open it.

Then click on the green <> Code button. Copy the HTTPS URL by clicking the copy icon.

To ensure that you are cloning the forked repository, you should see your GitHub username in the link. For example:

https://github.com/<github-username>/<repository-name>.git

That is:

User's avatar on GitHub

Dropdown menu on GitHub that highlights Your repositories

A green <> Code button and a HTTPS URL of a repository followed by a copy icon on GitHub

Step #2 - Clone the Project Locally

In your terminal, run the git clone command along with the URL that you copied:

git clone <copied-url>

You can navigate to the project's directory with this command:

cd <project-name>

How to Create a New Branch

The best practice in open source is to create a new branch whenever you are going to work on an issue. A new branch isolates your changes and keeps the main branch clean.

Run this command to create a new branch and navigate to it:

git checkout -b <branch-name>

Although you can give a branch any name, you should follow conventions related to naming a branch. A branch name usually refers to the change that you make. For example, feature/add-dark-mode or bugfix/broken-link-to-about-page.

Now you can start to make changes in your new branch.

How to Add Changes to the Staging Area

Let's say you've finished working on changes. Before committing, you must first add them to the staging area.

This step allows you to keep your changes while you can still modify them before committing. It also lets you choose which change(s) you're ready to commit.

Adding changes to the staging area is often seen as a less critical step. But that's not true. This step allows you to change your mind before committing. Because once you commit your changes, you add a piece of story to the project's history.

How to Add Single or Multiple Files to the Staging Area

When you want to add one or multiple files — but not all — to the staging area, run this command:

git add <file-name-1> <file-name-2>

For example:

git add README.md CONTRIBUTING.md

The command above adds the README.md and CONTRIBUTING.md files to the staging area.

When you add nested files(s) to the staging area, you want to add the path(s) to the file(s). If you can't figure out the exact path, running git status will help give you the status of the files that contain your changes.

Here is how to do it:

Run git status in your terminal. You will see something like this:

git status showing paths to three modified files on the VSCode terminal

Copy the path and run the git add command along with the path(s) to the file(s):

git add <path-to-file-1> <path-to-file-2>

Here is an example of adding paths to two files based on the screenshot above:

git add app/routes/__frontend/resources/index.mdx app/routes/__frontend/resources/developer-resources/open-source/index.mdx

How to Add All Files

When you want to add all files to the staging area, run this command:

git add .

This adds all the files with changes to the staging area.

How to Commit Changes

To commit means to record your changes. That is why a commit requires a message as the record. Over time, commits will tell the story of the project's history. So, a clear and descriptive commit message is essential.

What you should know when committing your changes:

• Add and commit your changes often. The best time to add and commit your changes is every time you finish making a meaningful change, even if it's a small change. Committing your work once completed also prevents your changes from being carried over to other branches.
• Use a clear and descriptive message. "Change the background color from black to dark blue" is more descriptive and easy to understand by everyone than "Fix style".

To make a commit, run this command in your terminal:

git commit -m "Your message"

Here is an example of a single line commit:

git commit -m "Fix the link to the About page"

And here's a commit with multiple lines:

git commit -m "Fix the link to the About page
Fix the typos in the About page"

How to Synchronize Changes

When you are working on changes, there is a possibility that the main branch on the upstream repository has already merged in some pull requests. So, the state of the origin and your local repositories at this time will no longer be the same as the upstream.

For this reason, you should always update your local working branch so you'll push the same state as the upstream repository.

How to Update the origin Repository

First, go to the origin repository on GitHub to check if it's up to date with the upstream.

You can push your changes when no change exists in the upstream repository.

To know if the origin repository is up to date, you'll see a message that says, "This branch is up to date with " on the main page of the repository, as shown in the screenshot below:

An up-to-date branch in the origin repository on GitHub

But when there are changes, you will see a message that says, "This branch is X commit(s) behind ".

A message indicating a branch in the origin repository is eight commits behind the upstream repository on GitHub

To update the origin repository:

1. Click the Sync fork dropdown button.
2. Click the green Update branch button.

The Sync fork and Update branch buttons on GitHub

After it's updated, you will see a "Successfully fetched and fast-forwarded from upstream " notification at the top.

A notification "Successfully fetched and fast-forwarded from upstream" on GitHub

How to Pull Changes

Now that your origin is up to date with the upstream repository, it's time to pull the changes and update your local one.

Pull is a way of getting new changes from the remote to the local repository.

To pull the changes, ensure that you are on your working branch. You can do so by running git status:

git status showing a branch name

Run the git pull command to pull the changes from the main branch in the origin repository:

git pull origin main

You can now push your changes if you don't need to resolve conflicts.

How to Resolve Merge Conflicts

After updating your local repository, you might encounter conflicts that you must fix before you can push your changes.

It's common to encounter these conflicts in open source projects. Merge conflicts usually occur when there are changes in the same line(s) and file(s) from two different branches.

When a conflict arises, you will see options for accepting changes on top of your workspace in VSCode. You will also see another change(s) different from yours — the incoming change.

Options to accept change, the current change, and the incoming change on VSCode

How to Fix Merge Conflicts

You can choose from different options when you want to resolve a conflict:

• Accept Current Change: When you wish to keep your changes only.
• Accept Incoming Change: When you want to accept only the incoming changes that aren't yours.
• Accept Both Changes: When you want to accept your changes and the incoming changes.

You can still fix things if necessary after choosing the desirable action.

After resolving the conflicts, you can then add your changes to the staging area and commit them.

Since you'll add and commit changes in an existing file, you can run this command to do both actions at the same time:

git commit -am "Your message"

How to Push Changes

Now, it's time to push your changes. This means moving changes from the local to the remote repository.

You always want to push your changes to the origin repository. To do that, run this command in your terminal:

git push origin <branch-name>

There's a possibility that you may get this error message:

git push message "fatal: The current branch <branch-name> has no upstream branch."

You can copy, paste, and run the command in the error message in your terminal:

git push --set-upstream origin <branch-name>

Alternatively, you can run this command:

git push -u origin <branch-name>

How to Create Pull Request

A pull request — commonly called a PR — is a way to notify others that a branch with changes has been pushed to a remote repository.

After a pull request is opened, maintainers can review and discuss your changes. They can ask you to make more changes before they can merge your pull request or merge them immediately into the main branch.

How to Create a Pull Request

First, go to the upstream or origin repository on GitHub.

Then click the green Compare & pull request button to redirect to the Open a pull request form:

The green Compare & pull request button on GitHub

Then fill out the pull request form. If there's a pull request template, complete all required areas to help maintainers review your changes.

If there is no pull request template, you can write the pull request in a structured manner. Consider this when writing your pull request:

• A short, clear, and informative title.
• A clear description of the changes.
• The link to the related issue. For example, "Closes #456".
• Screenshots or screen recordings when necessary.

Lastly, click the green Create pull request button at the bottom to create a PR.

The green Create pull request on GitHub

Final Words

Contributing to open-source projects can be daunting and make you feel intimidated at the beginning. But like other skills, with continuous practice, you will become better.

Besides understanding Git and GitHub, there are non-technical aspects of open source that you should know too.

And once you get the grip, open source can be so much fun!

If you liked and enjoyed this article, please share it with others. You can find other works of mine on my blog, and let's connect on X (formerly Twitter) or LinkedIn!

Although they are as important as the technical sides, the non-technical ones often get overlooked. In this article, I will share the essential non-technical things you should know when contributing to open source projects.

What are the Important Files in a Repository?

In this section, we'll talk about some of the important files you'll likely come across when contributing to an open source project.

The README.md File

When you're interested in contributing to an open-source project, you should always read the README.md file — commonly called README — to familiarize yourself with the project.

The README.md file is the face of the project, containing everything essential. You'll usually find most, if not all, of these sections in a README:

• The project's description.
• The technology used for the project.
• Instructions on how to install, run, and use the project.
• The project's license.
• The code of conduct.
• How to contribute to the project.
• The expected communication style (through issue and pull request comments, GitHub discussion, chat service apps such as Slack or Discord, and so on).

The CONTRIBUTING.md File

Next, you must know the rules to follow in order to contribute to a project. The procedures and requirements for contributing may differ between projects. For example, in some projects, you're required to comment on an issue before it gets assigned to you, while others allow you to assign an issue to yourself.

The CONTRIBUTING.md file serves as a contribution guide. It explains the community's rules and expectations from their contributors, from creating an issue to creating a pull request.

In most cases, you'll find a contribution section in the README. But if it's not included in the README, you can find it in a file named CONTRIBUTING.md or anything similar.

The LICENSE File

You can't just assume that all projects on GitHub are open-source and that their codebase is freely available.

"In most jurisdictions, any code or content is automatically copyrighted by the author, with all rights reserved, unless otherwise stated." (Source: Open source licenses: What, which, and why)

"All rights reserved" means that no one may use, modify, or redistribute anything in the project unless the owner gives you permission to. If you ignore it, they can legally sue you. So, a project on GitHub is only open source if they have a license that specifies that.

You'd usually find a license section on the README, in the "About" section of a repository. It is found in a file called LICENSE.

An MIT license in the "About" section on the right sidebar of a repository on GitHub

The CODE_OF_CONDUCT.md File

You should habitually read the community's Code of Conduct (COC). The COC is the house rule of the community. It is there for a reason: to maintain a safe, welcoming space for contributors. Following the COC will prevent you from getting banned from the community and the project.

You can find the COC in a file called CODE_OF_CONDUCT.md, in the "About" section on of the repository. Most times, it's also included in the README and contributing guide.

Code of Conduct in the "About" section on the right sidebar of a repository on GitHub

Ethics in Open Source

Check for Duplication

Let's say you install and run a project on your local machine and encounter a bug. Or you read through the docs and find a missing step. You might want to raise an issue to address it.

Before doing so, you must check if a similar (open and closed) issue or pull request has been raised to avoid duplication. Enter possible keywords in the search bar on top of the issue or pull request page on GitHub to check for possible duplication.

Search bar on top of the issue or pull request page on GitHub

For example:

is:issue is:open docs

is:pull request is:closed button

Checking for duplicates will help prevent your issue or pull request from getting turned down by maintainers.

Ask for Permission before Working on an Issue

One of the essential ethics in open source is asking for the maintainer's permission to work on an issue unless stated otherwise in the contribution guide. Asking for permission helps the maintainers in controlling and avoiding duplicate pull requests.

You only want to work on changes and create a pull request after you get the green light from a maintainer. If you ignore this part and go ahead to work on the changes, your pull request will likely be ignored or turned down. This is because the issue may have been assigned to someone else already, or the issue may not be their priority at that moment.

Either way, it would be a loss for you. So, what should you do when asking for permission?

1. Check if the issue has already been assigned

You can see if an issue has been assigned by looking at the "Assignee" column when you open the issue tab in the GitHub repository or on the right sidebar when you open the issue.

Assignee column on the issues page on GitHub

Assignees section on the right sidebar of the issue page on GitHub

2. Check the comment threads

You also want to make sure that someone has not already asked the maintainers to assign the issue to them. If they haven't gotten any response, then the maintainers have probably not seen the comment. You should also check other information in the threads to understand more about the issue.

3. Leave a comment to request for an issue you want to work on

You can say, "Hi, I want to work on this issue. Can you assign it to me?" Or, "I see this issue has been assigned, but I haven't seen any activity here in a while. If you still need help, can I work on this?"

4. Wait until the maintainer replies to your message

If they (the maintainer(s)) say you can have it and assign it to you, then you can start working on the issue and, in the end, create a pull request.

What is the Good First Issue Label?

Labels on GitHub are tags that pass information about the type or the status of an issue or a pull request. A good-first-issue is a label considered appropriate for beginners by the project's owner and maintainers.

I once created an issue about a broken link. I explained the bug and the steps contributors must take to resolve it.

I also mentioned that this issue is beginner-friendly, so we want to leave it for beginners who wish to contribute to the project. After passing the review from the maintainers, the issue was labeled as a good-first-issue.

The sad part was that people who deliberately took the issue were not beginners.

If you already have some experience, please consider leaving this label. It is meant for beginners in open source or the technology used in the project.

Good Communication and Patience

Always use clear and polite words to communicate with maintainers and other contributors. Remember that async communication is prone to loss in translation and miscommunication.

If you need more clarification on something, ask the maintainers. Don't make assumptions. You can ask questions in the issue or pull request comments. Some communities also have a GitHub discussions board that you can find on the top bar, while some use chat service apps like Slack or Discord to share ideas and ask questions or clarifications.

Discussions tab on GitHub

A maintainer may ask you to fix something in your pull request or ask for clarifications using a straightforward sentence. Short and direct messages mostly happen because they are busy. They must be fast and effective in replying to messages. Don't take it personal as this may lead to poor communication or even lead to losing your chance at contributing.

Most of the maintainers and contributors in open source are volunteers. That said, they have life and other duties outside of the project. So, when you're contributing, you need to have patience. Don't ask maintainers to immediately answer your question or merge your pull request.

Write Issue and Pull Request in a Structured Way

Some open-source communities provide templates on GitHub for opening an issue or creating a pull request. But when they don't, consider writing them in a structured manner. It would be handy for everyone to see the details and help maintainers review and merge pull requests.

How to Write a GitHub Issue

Here are some things to consider when writing an issue:

Use clear and descriptive titles: By reading a clear and descriptive title, everyone can understand the issue. For example, "fix: Link to the About page leads to 404".

Search for similar issues: Check open and closed issues to see if there is a similar or identical issue as yours. If you don't find any, then include in the description that you've checked and did not find any similar issues. This step is essential to avoid any duplication.

Description of the issue: Describe the issue as straightforward as possible.

Expected behavior: Describe the expected behavior of an issue.

Actual behavior: State the actual problematic behavior that causes the issue.

Reproduce the problem: What steps do we need to take to reproduce the problem? It would be helpful for everyone to run the same steps and test it out. Here's an example:

1. Go to this link.
2. Click this button.
3. This is what is happening.

Screenshots or screen recordings: Provide some screenshots or screen recordings if necessary. It is usually beneficial for UI issues.

Suggest a solution: If you have a solution in mind, you can give a suggestion. But if you don't, it's okay too. You are not expected to have a solution when you raise an issue.

Here's an examples that uses the points listed above:

<!-- Issue title -->
# fix: Link to the About page leads to 404

<!-- Issue body -->
## Description

When I went to the About page, I got a 404.
I have searched and didn't find any similar issues.

## Expected Behavior

We should see the About section when we go to the About page.

## Actual Behaviour

When we go to the About page, we see a 404 page.

## How to Reproduce

1. Go to the https://website.com.
2. Click the About tab.
3. You will see the 404.

## Screenshots

![404 in about page](link to the image)

## Suggestion

Fix and use the correct link to the About page.

How to Write a Pull Request

Here are some things to consider when writing a pull request:

Use a short, clear, and informative title**: For example, "fix: Link to About page".

Use a clear description of the fix**: For example, "This pull request fixes the link to the About page that previously led to 404."

Link to the related issue: Include the link to the related issue. For example, "Fixes #123".

Screenshots or screen recordings: Provide some screenshots or screen recordings that shows the issue before and after the fix if necessary.

Here's an example that uses the structure above:

<!-- Pull request title -->
# fix: Link to About page

<!-- Pull request body -->
## Related Issue

Fixes #123

## Description

This PR fixes the link to the About page that previously led to 404.

## Screenshots

### Before

![404 in about page](link to the image)

### After

![About page](link to the image)

Good to Know: Contributing to Open Source is Not All About Code

I often hear that people — especially beginners — hesitate to contribute to open source because they need more skills or time to help with code. However, contributing to an open-source project is involves more than just code.

There are many non-technical ways to contribute to a project and its community, such as:

• Opening an issue when you see a bug or room for improvement.
• Reviewing issues and pull requests.
• Improving the project's documentation.
• Answering questions.
• Throwing ideas around the project.
• Onboarding new contributors.
• Mentoring other contributors.
• Writing a blog post or creating a video about the project.
• Promoting the project on social media, and many more!

Final Words

Contributing to open-source projects is not all about understanding Git and GitHub. Some non-technical things are important for you to know, too. I hope this article helps.😊

If you liked and enjoyed this article, please share it. You can find other works of mine on my blog, and let's connect on X (formerly Twitter) or LinkedIn!