Contributing Guide

Table of Contents

• 1. Setting up your Environment
• 2. Creating an Issue
• 3. Creating a New Branch
• 4. Submitting a Pull Request
  • 4.1. If you edited markdown files
• 5. Reviewing a Pull Request
• 6. Amending a Pull Request

1. Setting up your Environment

1. Set up Git on your computer.
   • You can find a guide here.
2. Clone the repository.
   • Options for cloning can be found by clicking the Code ▼ button under the Code tab of the GitHub repository.

There are lots of IDEs available, but I recommend using Visual Studio Code because of its vast selection of plugins.

3. Download and install Visual Studio Code.
4. Launch Visual Studio Code.
5. Navigate to the Marketplace by clicking Extensions on the left menu bar or typing Ctrl+Shift+X.
6. Install GitLens from the Marketplace.
7. Navigate to the Settings page by clicking Manage → Settings on the left menu bar or typing Ctrl+,.
8. Check the Git: Allow Force Push checkbox.
   

2. Creating an Issue

Issues are a way of reporting bugs/improvements and assigning the workload between all the members of the team. All work done by the team should have an associated issue.

1. Navigate to the Issues tab of the GitHub repository.
2. Click New Issue.
   
3. Write a clear, concise title for the issue.
4. Write any information relevant to the issue in the description, such as
   • A more detailed description of the issue
   • Steps for reproducing (if it's a bug)
   • Error logs
   • Screenshots
   • Images
5. Add relevant labels to the issue. The most common labels are
   • bug - if something isn't working as intended
   • enchancement - if a new feature is being implemented
   • documentation
6. Click Submit New Issue.
   

3. Creating a New Branch

To begin working on an issue, the first step is creating a new branch to work on. If you intend to work on something that does not yet have an issue made for it, create a new issue first.

1. Assign the issue to yourself.
   
2. Navigate to the Source Control page by clicking Source Control on the left menu bar or typing Ctrl+Shift+G G.
3. Pull the main branch to get the latest version.
4. Create a new branch off of the main branch.
5. Name your new branch "<macID>/<description>".
   
6. Switch to your new branch.

4. Submitting a Pull Request

4.1. If you edited markdown files

1. Navigate to the Marketplace by clicking Extensions on the left menu bar or typing Ctrl+Shift+X.
2. Install Markdown All In One and Markdown PDF from the Marketplace.
   
3. If you edited any section title, run Markdown All In One: Update Table Of Contents in the terminal (Ctrl+Shift+P).
4. If you added or removed any sections, run Markdown All In One: Add/Update section numbers, then Markdown All In One: Update Table Of Contents in the terminal (Ctrl+Shift+P).
5. Run Markdown PDF: Export (pdf) in the terminal (Ctrl+Shift+P).

Once your code is ready to be merged, push it to remote repository and create a pull request.

1. In Visual Studio Code, navigate to the Source Control page.
2. Stage and commit your changes. Your commit message should include
   
   • The issue number
   • A clear, concise title describing what was changed
   • If needed, a body explaining the changes in more detail
3. Publish your branch to the remote repository.
   
4. In GitHub, create a pull request for the branch.
   • The title and description should auto-fill.
5. Add the review label.
   
6. Ask other contributors to review your pull request and approve it if looks good.
7. Once your pull request gets approved and all review are resolved, merge the branch to main.
   • Once your branch is merged, it is automatically deleted.
8. Once your pull request is merged, close the associated issue.

5. Reviewing a Pull Request

Reviewing a pull request is the best way to double-check another person's work. Branches need a certain number of approvals on their pull request before they can be merged to main.

1. In GitHub, familiarize yourself with the issue associated with the pull request.
2. Look over the changes on the pull request.
3. Optionally, checkout a branch in Visual Studio Code to poke around on it locally.
   
   • In Visual Studio Code, navigate to the Source Control page.
   • Click … → Checkout to....
   • Select the desired branch.
4. In GitHub, create code reviews in the Files changed tab of the pull request for any problems you see.
   
5. If everything looks good, approve the pull request.
   • As a common courtesy, do not merge a pull request unless you are the author.

6. Amending a Pull Request

Sometimes you need to make additional changes after you've created a pull request.

1. In Visual Studio Code, navigate to the Source Control page.
2. Stage your additional changes.
3. Click … → Commit → Commit Staged (Amend).
   
4. A tab named COMMIT_EDITMSG will open. Here you can choose to also amend the commit message. Save and close this tab when you are done.
   
5. Click … → Pull, Push → Push (Force).
   

Your additional changes should now be reflected in your existing pull request under the same commit.