Now that your local repo is set up and ready to go, it's time to start working with it. 

Starting from the Right Place

Imagine you made a change to your code, but made a mistake. Now your repo is in a bad state. To help avoid this situation, we use branches. You always want to make changes while on a branch. A branch is a way to have your own working timeline of changes, while leaving the default branch even with the original project. The default branch is called either main or master. It's best to leave main or master clean, and make your changes on a working branch. For more details about branches, check out the Branches? page found in the Adafruit guide An Introduction to Collaborating with Version Control.

Main or Master?

The first thing you need to do is determine is whether the library you are working with is using main or master as the default branch. This is a simple process. First, visit the library on GitHub. Above the repo contents on the left side is a drop down menu that shows all available branches.

It will typically be on the default branch to begin with, but you can verify by clicking on the menu.

Updating the Main or Master Branch

If you just cloned your repo for the first time, you're using the most up-to-date version as your start point. However, if you cloned it a while ago, or this is not your first time contributing, you may not be up to date. So, before you begin, you want to make sure the main or master branch is current.

To create a new branch or move between existing branches, you'll checkout the branch you'd like to switch to. The checkout command allows you to switch to a new branch, by creating it in the process, or to switch to an existing branch.

To update main or master, first checkout main or master to verify you're on the correct branch:

git checkout main

Or:

git checkout master

Next, we're going to utilise the original project remote we created. To get the updates from the remote repo, we're going to use fetch. fetch grabs the the newest version of the remote repo, but does not merge it into the current repo.

Remember, you named the original project's remote repo with the owner's GitHub ID. You'll use this name when you merge the two main branches together. Since I cloned an Adafruit repo, I'll be using adafruit.

To fetch the updated remote, enter the following fetch command, replacing ownerid with the name you assigned to the original project's remote repo:

git fetch ownerid

Now we're going to merge the current data into our local repo. A merge takes the information from one branch and combines it into another. In this case, it's going to take the current version of main or master from the remote repo and combine it with the main or master branch on your local repo. This will bring you even with the remote main or master, and that means you're up to date.

To merge the remote main or master with your main or master, run the following merge command, replacing ownerid with the name you assigned to the original project's remote repo:

git merge ownerid/master

There have been some updates to the remote main or master since I last did anything with this repo. Good thing I updated!

Now your main or master branch is even with the original project's main or master branch and you're ready to create your working branch!

Alternatively, you can simply run git checkout ownerid/main or git checkout ownerid/master (where ownerid is the name you assigned the original project's remote repo) and then continue with the next set of steps. It will not update your main or master branch, but it will ensure that you create your new branch from the most updated version of the repo.

Create Your New Branch

Now we can create a new branch. It's good practice to create a new branch for each new contribution you are working on. I'm working on fixing a bug with audio, so I'll be doing all of it in one branch. However, if I intended to submit a fix for audio and another one for adding a new function to the library, I would want to work on one and then the other in two separate branches. This helps keep reviews simpler and more effective by delineating separate concepts and allowing you and the reviewer to focus on each one properly.

You can name a branch whatever you'd like, however, it's useful to name the branch something descriptive of the work that will be going on within it.

To create a branch, enter the following checkout command, replacing your-branch-name with whatever you'd like to call your branch:

git checkout -b your-branch-name

If you've already created a branch and you'd like to return to it, you can enter:

git checkout your-branch-name

If you'd like to return to the main or master branch, you can enter:

git checkout main

or

git checkout master

Now that you've created your branch, it's time to get to work!

Moving your Local Clone and Fork from master to main

Once the original Adafruit GitHub repository has moved to main, you will want to update your fork to have main as the default branch as well. Run the following commands from command line (in your terminal window):

git checkout master
git pull
git checkout main
git push YourUserID main

git checkout master
git pull
git checkout main
git push YourUserID main

Next, go to your fork on GitHub. The URL of your fork is the same as the Adafruit repo URL, except with your user ID in place of Adafruit. For example, my fork of the Circuit Playground library is found at the following URL:

https://github.com/kattni/Adafruit_CircuitPython_CircuitPlayground

Once there, complete the following steps:

You've now successfully updated your fork to the main default branch. You're ready to continue!