โญ First Code Contributionยถ

If youโ€™re fully new to GitHub, we know it can be pretty daunting to start. We encourage you to check out our Quickstart for GitHub page to learn more about what it is and getting started.

For this guide, weโ€™ll help you on your first code contribution working with GitHub using the terminal. You could also use GitHub Desktop as an alternative, a guide to which is available in the Quickstart for GitHub page.

Important

To begin, ensure you have git installed

Clone a Repositoryยถ

Cloning is essentially similar to copying and pasting a directory from GitHub to your personal computer; youโ€™re pulling the remote GitHub repository down to your local machine. Weโ€™ll walk through the steps of cloning here.

1. Open the Terminal.

2. Move from your current working directory to where you want to clone the GitHub repository.

Use cd to change directory location. Use ls to view files and other folders inside a directory. Here, you can see I moved to the personal directory - as in ~ or $HOME - before navigating to the folder we called Git.

cd ~ && ls

And see the output, for example, on macOS.

Applications	Movies
Music           Library
Desktop		Pictures	
Documents	Public
Downloads

Now navigating to the folder.

$ cd Documents/WBG/Git/ && ls
docs-twitter 

Tip

You can type in the first few characters of a directory name in the terminal and press tab to autocomplete the name.

3. Copy the remote repository URL and paste it in the terminal.

In this example, Iโ€™m interested in using and contributing to the mapillary-api.ipynb file in the examples folder under datapartnership/docs-mapillary (private). To pull it from GitHub to my personal computer, Iโ€™ll need the git clone command and the URL of the docs-mapillary repository.

To obtain the URL, select the green Code button in the respository and then click the clipboard icon next to the URL to copy it:

../_images/quickstart-first-code-contribution-cloning.png

Fig. 7 Cloning a Repositoryยถ

Weโ€™ll paste it into the terminal:

git clone https://github.com/datapartnership/docs-mapillary.git

And see the output:

Cloning into 'docs-mapillary'...
remote: Enumerating objects: 42, done.
remote: Counting objects: 100% (42/42), done.
remote: Compressing objects: 100% (33/33), done.
remote: Total 42 (delta 8), reused 34 (delta 3), pack-reused 0
Receiving objects: 100% (42/42), 3.60 MiB | 9.77 MiB/s, done.
Resolving deltas: 100% (8/8), done.

Tip

You can connect to GitHub using SSH instead

Checking your current directory again, you should see the copy of the repository in your folder:

$ ls
docs-twitter
docs-mapillary

You now have the repository on your local machine! ๐Ÿ™Œ๐Ÿฝ

Branch a Local Respositoryยถ

After cloning the repository, you should create a branch to which youโ€™ll add and commit your changes before pushing โ€“ or sending โ€“ them to the original GitHub remote repository.

1. First, make sure youโ€™re in the correct git repository. In this case, I would navigate all the way to my cloned docs-mapillary folder:

cd ~/Documents/WBG/Git/docs-mapillary

2. Use the following command to see the branches inside the repository:

git branch 

You should see the output * master. The asterisk indicates youโ€™re in the main (master) branch. So far, thatโ€™s the only branch you have in the repository.

3. Create a new branch by using git checkout -b {name of new branch}:

git checkout -b mapillary-examples

The git checkout command is used to switch from one branch to another. In this case, weโ€™re using it with -b to create a new branch and switch to it (-b creates the new branch). Alternatively, you could use git branch {name of new branch} to create a new branch and subsequently use git checkout {name of new branch} to switch to it.

If you use git branch again, youโ€™ll see the asterisk has moved, meaning youโ€™re now in that new branch:

$ git branch
* mapillary-examples
master

Run Examples Locally with Jupyter Notebookยถ

In this example, Iโ€™m using Jupyter Notebook via Anaconda as my code editor.

../_images/quickstart-first-code-contribution-jupyter-1.png

1. Open up Jupyter Notebook and navigate from your dashboard to the directory holding your cloned repository.

../_images/quickstart-first-code-contribution-jupyter-2.png

2. Once inside the directory, go into the examples folder and select the .ipynb file you want to run.

../_images/quickstart-first-code-contribution-jupyter-3.png

The file will pop up in a new tab.

../_images/quickstart-first-code-contribution-jupyter-4.png

3. Run the code and make any changes you want to the file.

4. Shutdown the notebook.

Once youโ€™ve finished making changes to the code, save your file with the floppy disk icon in the tool bar. You can now close the tab and go back to your Jupyter dashboard. Select the file, then click Shutdown once the yellow button appears.

../_images/quickstart-first-code-contribution-jupyter-5.png

Staging & Pushingยถ

1. Check the status of the modified files.

Itโ€™s good practice to first use git status to see which files youโ€™ve modified and those you have yet to add and/or commit to the respository:

git status

The git status command will return a list of your modified files and/or untracked files (those youโ€™ve added to the respository in your local machine that were not in the remote repository). Itโ€™s useful for verifying where the files you want to add and commit are staged.

2. Add and commit your file to the branch:

git add mapillary-api.ipynb

Alternatively, if you wanted to add all untracked and modified files to commit to the remote repository, you could instead use a period: git add .

Now commit with a good description of what changes you made:

git commit -m "Add API examples and documentation"

3. Push the branch to the remote respository:

git push -u origin mapillary-examples

Open a Pull Requestยถ

Finally, you want to make a pull request so that an admin knows youโ€™ve made changes and want to contribute to the main file. After running the git push -u origin {branch name} above, you should have seen in the output โ€œCreate a pull request for โ€˜{branch name}โ€™โ€ with a url in the terminal.

1. Copy the url and follow the link in your web browser.

../_images/quickstart-first-code-contribution-pull-request-1.png

2. In the โ€˜Open a pull requestโ€™ page, leave a comment on the modifications you made to the repository. Then click the green โ€œCreate pull requestโ€ button.

../_images/quickstart-first-code-contribution-pull-request-2.png

The request will be sent to an admin who can review and provide any feedback prior to committing your version to the main branch.

๐ŸŽ‰ With that, youโ€™re done! Thank you so much for your contribution! ๐ŸŽ‰