Git Procedures for Google Code In

Overview

Once Upon a Time, we had students send pull requests directly to the main repository. This led to voluminous and frequent interruptions of the folks who approve submissions to the main repository. We would like to avoid this. Our intent is to have mentors do complete code reviews of students' work, and assure that submissions work properly, pass tests, are correctly formatted, have no conflicts, and are mergeable. We would also like to batch the submissions to the main repository -- combine students' work over several days into one already-reviewed bundle, and submit that as one PR.

After some head-scratching, discussion, and trial runs with help of GCI students, here is what we are doing. It may sound complicated, but it is designed to avoid issues we encountered with a less formal procedure, in which mentors and students were freely updating from the main repository, without coordination.

We will be using a GitHub repository just for GCI, rather than submitting code directly to the main repository. The GCI repository is:
​https://github.com/edengci/eden

Students will still fork the main repository, looking forward to when they will (we hope) be contributing beyond GCI. However, during GCI, they will submit PRs to the GCI repository. In order to avoid chaos, we will temporarily freeze the revision level on which students will work -- we will provide a base branch that students will use to populate their local working branch for GCI tasks. Students will each have their own branch in the GCI repository to send PRs to so reviews and merging of PRs for each student can be done asynchronously.

We will also have a staging branch, initially set to the same revision as the base branch, onto which student work is aggregated. As mentors accept pull requests, they will merge them into the staging branch. If there is a conflict at this point, it will be with some other student's work, not with an update from the main repository. The mentor can resolve the conflict (which the student's assistance if needed).

Every few days, we will switch to a fresh base branch. Students can continue with PR reviews already in progress on their current branches, but when they are done with that PR, they can rename their current local branch (if they want) and pull a fresh local branch from the fresh GCI base branch. We can rename students' branches in the GCI repository (in case we need to refer to them) or just remove them (if it's safe), and students can push their new branches. At this point, all branch names will be as they were before, and work can continue as before.

Also at this point, students' completed PRs are on the staging branch. A designated mentor will prepare the staging branch for a PR to the main repository: If the staging branch is not mergeable, the mentor can pull the staging branch to their local repository, merge from the main repository, fix up conflicts, and push to the staging branch again. (Note rebase is probably not appropriate here, as that would require modifying students' commits. It is better to allow students to have their work visible unmodified.) In any case, the combined code needs to be tested -- both running the test suite and verifying that the changes still work. (To facilitate this, we can have students write what should be done to exercise their change. We can rotate this mentor task, or free up one mentor from other work, and allow them to be the git-meister, as this step may take some time.)

Everyone involved -- students with submitted code and the mentors who reviewed it -- can help get that PR accepted into the main repository.

Setup

Repository

A separate repo has been created:
​https://github.com/edengci/eden

Branches

We can retain the master branch as a mirror of the main (trunk) repository -- it won't be otherwise involved in the GCI workflow.

Branch "base" is a temporarily frozen revision level that is used to set up new student branches.

Branch "staging" is the destination for student work. After a student's work is accepted, it is merged into the staging branch.

Each student has a branch that is used for code reviews. The purpose of separate branches is so the target branch won't change during the code review. If we find that this is not a problem, or if we want students to have the experience of fixing up conflicts (with other students' work) then we can dispense with student branches, and have them do PRs directly to the staging branch.

Periodically, we will update the base branch to current trunk, rename the staging branch to "to_trunk", and make a new staging branch at the same revision as the base branch.

Mentor Workflow

Student Workflow

We will be using a GitHub repository just for GCI, rather than submitting code directly to the main repository. This will help us conserve the time of the (very busy) folks who have to approve submissions to the main repository.

You'll use the GCI repository to use for pull requests.
​https://github.com/edengci/eden

But you should still fork the main repository to create your own repository, and then clone your own repository.
​https://github.com/flavour/eden

On your local (cloned) repository, set up a "remote" that points to the GCI repository. Open the repository page:
​https://github.com/edengci/eden
On the right, there will be a box that says "SSH clone URL" or "HTTPS clone URL" -- that will be the URL to use for your new remote. If you are using git from the command line, cd to your local eden repository, and do this if you are using a password to connect to GitHub (this is the "HTTPS clone URL"):

git remote add edengci https://github.com/edengci/eden.git

Or do this if you are using SSH keys to connect to GitHub (this is the "SSH clone URL"):

git remote add edengci git@github.com:edengci/eden.git

A mentor will create a branch with your name or nick in that GCI repository to receive your pull requests. You can get a copy of this branch by doing this (replace abcde with your branch name):

git pull edengci abcde:abcde

Every few days, we switch to updated branches, and submit a combined PR, with all student work for those days, to the main repository. (Even with this extra step, your commits will have your name on them, and will show up in the main repository.) The mentor reviewing or approving your task should tell you went to switch, but you can ask, to be sure. The mentor will update your branch in the GCI repository. You can rename the branch you were using locally for GCI work, just to be safe:

git branch -m abcde abcde_backup

Then redo the above pull to get another, updated, branch with your name.

The steps to submit your work as a PR are similar to those in the git wiki page linked above -- differences are noted here.

• "Squash" your commits into one.
• This is different: Don't rebase from the main repository -- you started with the right revision from the GCI branch, so don't need to update. (The mentors will rebase from the main repository while they are getting ready to send the combined PR.)
• Push your commit to your Eden repository on GitHub.
• Open the GitHub page for your Eden repository.
• Click the "Compare and Create Pull Request" button shown on that commit.
• This is different: The pull request page has a line that shows which repository and branch you are sending the pull request too. You will need to change both, to the GCI repository and your branch name in the GCI repository.
  • There will be a down-arrow next to the repository -- that will give you a list of repositories. Select the GCI repository.
  • Then use the down-arrow on the branch -- select your branch.
• Create the pull request.
• Continue with the code review as usual.