Nick Tchayka for The Agile Monkeys

Posted on Jul 25, 2023

Baby's First Contribution - A GitHub Flow for non-devs

#beginners #github #opensource #vscode

I'm sure that there was at least a single time where you wanted to change a word, a color, a font, a link, or something in a repo.

I'm sure that you are not afraid of doing the change, but of the process that it involves.

Using a text editor
changing code *gasp*
and… *dramatic orchestra sound* creating a pull request.

I know, this sounds scary af, but stay with me, I've streamlined the process for you so you can be doing the changes super easily.

Get to meet Git - Time Machine for code

If you use MacOS you probably know the Time Machine feature, which allows you to go back in time to retrieve a previous version of a file from the past. If you don't, well, apparently computers allow you to travel back in time 🤷 (at least digitally)

Git was one of the first software to popularize this concept, allowing to retrieve previous versions of any text file on a computer, saving all the changes that have been done to that file in what's called a log (like the log of an accountant, or the diary of someone).

The cool part of this, is that you can share this log with other people, so they can check the previous versions that you have done to your files. You can literally email them this log. (Remember all of this was in the early internet era).

What happens if two persons want to do changes to the same files? Git allows you to work in parallel, each timeline of changes is called a branch.

💡 Branches get out of the log, get it? Apparently programmers like bad jokes, but we keep denying it

They usually look like this:

Each circle is a change that someone has done, and the different colors represent the branches.

What if now we want to merge the changes from one branch into the main one? Let's keep reading.

GitHub - A Google Drive for Git logs

You could've been thinking already that emailing the Git log to everyone is a nightmare. Indeed it is, and teams have been doing so in the past.

Thankfully, nowadays we have GitHub, which makes everything super easy.

💡 Hub = place to share stuff, therefore GitHub = Place to share Git things.

GitHub is a platform that allows you to store the Git log of a project in a centralized place, and then it gives you tools so the team can discuss whether a change should be integrated into the main project or not (this is called a Pull Request).

If you don't have one, you should begin by creating an account in GitHub, and sharing the name with one of the team members so they can add you to the company team.

✏️ Note: In GitHub, open source projects are completely public, so if the project you want to contribute to is open source, you can skip the wait of getting added to the team.

GitHub is a very big tool that can have it's own article for an explanation. So we will talk only about making the change that you want.

Making the change

Let's suppose that you want to change a typo on the Docusaurus website of a project.

Open your web browser, and get into the GitHub repository that you want to make the change to.

Once you're here, press the . key in your keyboard. You should go from here:

To here

This new view is called Visual Studio Code. It is a text editor that devs use to code (and edit documentation).

Creating a branch

In order to be able to make a change properly, you need to create a branch.

First, think of a name for the branch (usually it is something like GITHUB-ISSUE-NUMBER/task-title for example 999/create-something-cool).

Now click on the branches button, which is the one saying main on the bottom left of Visual Studio Code:

Click on Create New Branch.

Type the branch name that you thought of, and press ENTER (if you minimize the window the text box will probably disappear and you will have to open this menu again)

It could be possible that it will ask you something about commits and stuff now, just click on Switch To Branch

Doing the actual changes

On the left side bar, you will see lots of folders and files. Locate the one that you want to change.

For our example, where we want to change something from Docusaurus, we will look into the website folder, which is where the documentation related files are usually located.

Let's say we saw a typo in the Getting Started guide and we want to fix it. We would have to navigate to website/docs/getting_started.md and open the file by clicking on it:

I'm going to change the first sentence of the section name Step 0.

💡 Usually technical documentation follows a format called Markdown. This is a way of formatting text in a super nerdy way, but it is a standard that most web tools understand. For example, when you format messages in Slack, you're using (something that is very close to) Markdown. Here you have a cheatsheet.

Once you save the file using Cmd + S. If you did it well, you should have a line marker where you did the changes:

Now to ensure that the changes are uploaded to GitHub, you have to commit them.

💡 Commiting means signing your changes with your name and a description. It is a way of marking who did what in a project.

On the top-left of Visual Studio Code, click on the thing that looks the USB logo, this is called the Source Control View:

Now, describe briefly the changes that you've made in the text box that says message. And click Commit & Push:

If the button went dark, and the message box got cleared, this means that the changes you made were uploaded to GitHub.

Now the last step!

Creating a Pull Request

If you put the mouse near where you see the text Source Control, some icons will appear. Click on the second one, the one that looks like a diagram with a plus sign. This will begin the Pull Request creation process.