Managing your work on Git - olinrobotics/gravl GitHub Wiki

As students join GRAVL and work on projects, they will work closely with the gravl Git repository in order to write, share, and implement code and documentation. In order to do so effectively, there are some procedures that are useful to keep in mind when doing work in Git. If you are new to Git, check out the basics via Lydia Zuehsow's tutorial: (link)

The current standard in GRAVL is to create a new branch for any feature you plan to create. For instance, if you are adding another motor controller to the hind-brain, create a branch called hindbrain_mc. For instructions on doing so, see this Git tutorial: (link)
For practice branching before the real thing, see this interactive online tool: (link)
You'll want a local version of your branch, as well as a remote version in Github. Why do you care about the remote version? For pull requests, of course!

git branch my_branch       # Makes new branch called temp_branch
git checkout my_branch     # Switches working branch to temp_branch
git push origin my_branch  # Links branch to remote repository

The main branch of the GRAVL repository is locked from casual pushes. The branch is locked to ensure that no code is pushed to the main branch that causes it to fail a catkin_make. Essentially, master should always work. With that said, once you are confident in your work, you will want to push your work to master to make it official. To do so:

1. Compile the ids of all of the commits containing the work you want to push. Odds are, you've been trying random things, and master doesn't need all of the extra files and changes you've made, so only list the commits that contain useful information. Look at the Git log for your branch and choose the commits that you want: (link)

git log                   # Shows the commit history for the current branch

2. Make a new branch, name it something suitable for the information you are pushing to master, and connect it to the remote repository (see "Branching" heading for commands).

3. Using cherry picking, move all of the commits you previously listed onto the new branch. (link)

git checkout my_branch   # Switches onto branch my_branch
git cherry-pick c90fd66  # Copies commit c90fd66 into the current branch
git push                 # Syncs changes on your local repo with the remote repo

4. Make a pull request on the Github website and ask someone to review it for you.

In order for a pull request to master to be approved, you need someone to review your code. Please make sure that this is a senior member of the team who has the know-how to fully understand and check your code. If your pull request is more than a trivial update or bug fix, you and your reviewer should sit down and go through the code, checking for understandable variable names, documentation in README.md files, sufficient comments, CMakeLists.txt setup, and other semantics, in order to keep master as clean as possible. Once your reviewer is satisfied with your offering, they will go onto GitHub and approve your pull request, whereupon you can merge your code into master. Please make sure your commit names are sensible and reasonably partitioned. We don't want a repeat of xkcd 1296.

The code is automatically built by Travis in order to know whether or not the code builds before merging. The build is done by using a ROS Docker image as a base, using our dependency management to install dependencies in that image, and invoking catkin_make. In short, most of the leg work is done by docker. All that travis has to do (see .travis.yml) is invoke docker build. See Dockerfile to see the build steps executed for the container.