Forking the ZP firmware repo
To start working on the project, your’e going to want to fork our central repository. Forking is the process of making a copy of a repo and storing it on your own github. To do this, head over to https://github.com/UWARG/ZeroPilot-SW and in the top right, click the fork button.
You’ll find that you know have a copy, or “fork” of the ZeroPilot-SW repo in your list of repos.
Cloning the repo
Now that you’ve got the fork, your’e going to need to clone it. That means bringing it in to your local environment. To do this, start by finding a good place for it. I store all my repos locally in a folder named C:\Users\<my username>\repos, but where you store yours is entirely your choice. Now go back to your forked repo (the one that lives in your profile, not the central repo) on github and click on the green “Code” button:
Copy either the https or the ssh link (you can look up git ssh if your’e interested in what the difference is and how to setup ssh). Now, cd into your local repo directory (if your’e on linux, mac, or wsl do this with the terminal. If your’e on windows, do this with git bash). Once in there, run
git clone <the link you just copied>
That gets you the repo. Feel free to cd into it and look around.
Workflow
Ok sweet, so you’ve got the repo. Now how to do actual work ? here’s the process.
1. Make a branch off of the devel branch. The devel branch is our default branch and you shouldn’t modify it locally. Keep it clean so that you never have problems syncing with our central repo. The name of the branch you create can be something relevant to the work your’e trying to do, but it doesen’t matter. Branch names are only a you thing and never show up again once your code gets merged. For this example, supose I’m working auto takeoff. To make my branch, I’d run
git checkout -b autoTakeOff
2. In this branch, do anything you want. Make commits, stash, move around, whatever. Once you finish your work and your’e ready for review, make sure your stuff is committed, and run
git push origin <your branch name> (autoTakeOff, in my case)
That pushes up your changes to your remote repo. The next step is to start a pull request (PR, for short).
3. To make the PR, go over to your github fork. You’l see a “pull request” button right over your repo:
Just click on that, making sure that it’s trying to merge <your branch name> into the central repo’s devel branch. Add a message, follow the instructions, and that’s it! You’ll have initiated a review.
4. So you got some comments and you need to make some changes. Now what ? Well, just add another commit or 2 to your branch and push the same way. Your pull request will automatically be updated with your newest commits.
5. Code got merged. Now what ? Congrats on merging your code. From here, make sure your local devel is updated (more on this in the next section) and go ahead and delete your branch with
git branch -D <your branch name>
6. Make a new branch for the next thing you’re working on and repeat the process anew!
Syncing your local stuff with the newest central stuff
So every once in a while, someone will merge something into the central repository. You’l want to make sure you stay up to date with those changes. So every few days or so make sure you do the following.
As a 1 time step, you’l want to tell your local rep about the central repo. Right now, it really only knows about “origin”, which is the copy of the repo that lives on your own github profile. To tell git about the central repo, you’l need to add a remote repo. You can do that by running
git remote add upstream https://github.com/UWARG/ZeroPilot-SW.git
“upstream” is just a nickname for the central repo (origin is the nickname for your own remote repo).
Sweet, so now you can get stuff from the remote repo. Here are the steps to take to update your local stuff:
1. Inside your local repo, checkout the devel branch and run
git fetch upstream
That brings all the newest central repo files into a local buffer. At this point though, no files have been updated.
2. Next, run
git rebase upstream/devel
This tells git to “apply” all the newest changes to your local devel branch. So at this point your devel branch should look exactly the same as the central repo’s devel branch (unless you committed stuff to devel locally, but don’t do that).
3. Sweet. Now, you’ll want to make sure all your other branches are also updated with the newest stuff. To do that, you’ll have to check out your local branches and rebase them on top of devel:
git checkout autoTakeOff git rebase devel
And at this point, your’e good to go. You’ve got all the newest changes and you can keep working as you did before.
To recap the syncing process:
git checkout devel git fetch upstream git rebase upstream/devel git checkout autoTakeOff git rebase devel
Add Comment