Introduction to GitHub

Creating your own repository

What is a Repository

A repository in GitHub contains a collection of files associated with a project, including the project's revision history.

Creating a new repository

1. From the CHIME/FRB Collaboration GitHub page (https://github.com/CHIMEFRB), click on the Repositories tab to obtain a list of all of the repositories available from the CHIME/FRB team.

   

2. From this page, click on "New repository" - the green button in the upper left.

   

3. Here we can fill out the details of the repository. Let's start by naming it, for your first repository we will name it username_onboarding, where username is replaced with your username. This repository will be an area for you to safely learn how to use GitHub during your onboarding.

4. Below the repository name is an area to provide a description of the repository. This description will be visible from the page listing all of the repositories administered by the CHIME/FRB Collaboration, so that users have an idea of the repository's purpose before clicking on it. Let's put "Learning space for {your-name}" here.

   

5. Next is the visibility settings for the repository, which we shall leave set to private. The checkbox to add a README file will automatically add a README.md file to your repository, this is where you can describe your project in detail using Markdown. The .gitignore file tells GitHub which files you do not want to track as you record the changes to your project.

6. Finally, at the bottom of the list, we are able to select a license that we want to apply to our repository. For this repository, we are going to select the MIT license, which effectively states that anyone can use or modify the software but the author takes no responsibility nor do they provide any support. Other popular open source licenses include Apache 2.0 and GPLv3 (more info on license).

Cloning Repository

Cloning a repository is the process of downloading a copy of a remote repository, such as those hosted on the CHIMEFRB GitHub page, to our local system. To the cloned copy, local changes can be made to the repository and they can be saved by committing changes. Once the changes are ready to be shared with others, they can be pushed to the remote repository - we will cover what committing and pushing are later.

In order to clone a repository, navigate to the repository that you would like to clone on GitHub. In this case, you will navigate to your personal repository.

First click on the green "Code" button, then copy the HTTPS URL. Open a terminal, navigate to the directory that you would like to copy the repository to, next enter this command into your terminal followed by the URL.

Format

git clone {url}

Result

git clone https://github.com/CHIMEFRB/tjzegmott-learning-space.git
Cloning into 'tjzegmott-learning-space'...
remote: Enumerating objects: 28, done.
remote: Counting objects: 100% (28/28), done.
remote: Compressing objects: 100% (22/22), done.
remote: Total 28 (delta 7), reused 8 (delta 2), pack-reused 0
Unpacking objects: 100% (28/28), done.

Add Issue and PR templates

Pull request (PR) and issue templates are tools that encourage the standardisation of information submitted when a contributor opens an issue or PR in a repository.

To create these templates for our onboarding repository, first, change directory using:

% cd {your-username}_onboarding

Depending on which options you ticked when creating your repository, it will either be empty or it could have some of the following files:

% tree -a
.
├── .gitignore
├── LICENSE
└── README.md

The templates for GitHub are placed in a special directory, called .github - the dot means that this directory doesn't show with regular ls commands without the -a flag. Within the .github directory, pull request templates are place here and issue templates go within the ISSUE_TEMPLATE subdirectory. Which once they are made, and the templates are inside, should look something like this:

tree -a
.
├── .github
│   ├── ISSUE_TEMPLATE
│   │   ├── bug_report.md
│   │   ├── feature_request.md
│   │   └── template.md
│   ├── PULL_REQU4EST_TEMPLATE.md
│   └── PULL_REQUEST_TEMPLATE.md
├── .gitignore
├── LICENSE
└── README.md

The creation of these directories and files can be done in the terminal, but in this guide we are going to create them using the GitHub website.

Issue Template

1. Within the repository that you wish to create an issue template for, click on the Settings tab.

2. Scroll down to the Features section, under Issues click the green "Set up templates" button.

3. Select the kind of issue template you wish to create. GitHub provides editable standard templates for Bug reports and Feature requests, or for a blank slate select Custom template.

4. Once satisfied with the templates, click the green "Propose changes" button. This will cause the Commit changes bar to appear, allowing an extended description of the changes made. Finally, press the "Commit changes" button, this creates two directories: .github and within that ISSUE_TEMPLATE.

Use this to make two issue templates in your repository, one for features and the other for bugs.

Pull Request Template

1. Within the .github directory of your repository, click "Add file", then "Create new file".

2. Name the file PULL_REQUEST_TEMPLATE.md.

3. In the text box below, enter your Markdown formatted pull request template - see below for an example.

4. Finally, scroll down, complete the description and press "Commit new file".

Example PR template

### Description
Please include a summary of the changes, and any relevant context and dependencies.
_Linked issue_: #

### Type of change
Please check the relevant option(s).
- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
- [ ] 🌟 New feature (non-breaking change which adds functionality)
- [ ] 🛑 Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] 📝 This change requires a documentation update

### Please check if the PR fulfills these requirements:
- [ ] My code follows the style guidelines of this project
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] I have added/updated tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

### Does this pull request introduce breaking changes?
No | Yes, the breaking changes are as following:

Pulling and pushing changes

The way that your local repository interacts with the remote repository on GitHub, is to push and pull changes (upload and download respectively). So now that we have made changes and committed them on GitHub, we should download, pull, those changes to our local version of the repository. Navigate to your repository on your machine, and within the {your-username}_onboarding directory, execute the following:

Format

% git pull

Output

# TODO: Add output

You have now downloaded the changes that you made on GitHub to your local repository. It is just as easy to upload changes made locally to GitHub, simply replace pull with push!

Committing changes

Changes that are made within a repository are saved using commits, you may have noticed the final green button that you pressed used this terminology, "commit new file". This becomes particularly prominent when working locally. To understand this, let's go to your terminal window, navigate to your repository ({your-username}_onboarding), and modify a file. Let's add "Hello world!" to the README.md, using:

% echo "Hello world!" > README.md

To see the current git state, enter the command:

% git status

On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

This tells us that there have been changes to the file README.md, but that they won't be saved using a commit. This is because files must be 'staged' to be included in a commit. This is a useful feature, when you are modifying several files, but only want to commit changes to a few of them. To stage our README.md file, use the command:

% git add README.md

If we now check the current git state again, we should see the following:

% git status

On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified:   README.md

You can now see that the changes are ready to be commited. To commit the changes, we would just enter: git commit -m "docs(README.md): added greeting to readme". You have now committed your first changes using the command line! Now upload them to GitHub, using what you've learnt above.

Next step

In the next step, you will learn how to write commit messages using Commitizen. This will simplify the process and guide to write well formatted messages. When you are happy with the content on this page, you can move on.