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 and tested bundle, and submit that as one PR.

After some head-scratching, discussion, and trial runs with help of GCI students, here is what seems to be a workable option. 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 staging branch that students will pull from when they start work on a new task, and to which they will submit pull requests.

We will also have a base branch that shows the revision that was current in the main repository's master branch at the time we start a new aggregations cycle. This is present purely for convenience in identifying the common base revision between the staging branch and the main repository's master branch. Students will not need to do anything with the base branch.

(By tradition in some popular git workflows, the master branch remains a mirror of the parent repository. To avoid disturbing that tradition, we can just use different names for our branches.)

Since all student work during an aggregation cycle goes to the same staging branch, other students' work will likely be merged into the staging branch while a student's PR is being reviewed, so by the time the PR is ready, there may be a conflict with the other students' work. The mentor will help the student with the appropriate git procedure for rebasing and resolving their conflict. This is much like the normal workflow for submitting to the main repository, so students will get practice with the normal git workflow.

Every few days, we will switch to fresh base and staging branches: rename the current base and staging to (say) base_done and staging_done, and create new base and staging branches from the main repository's master. This is the only point at which coordination with students is needed. Since we don't want to delay preparing the completed code for a PR to the main repository, if there are any PRs in progress, we can close those before we rename the base and staging branches, and ask students to rebase from the new staging and re-open their PR there. As the students may have merge conflicts at this point, we can't automate this.

At this point, students' completed PRs are on the staging_done branch. A mentor will prepare the staging_done 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

Branch "base" is a temporarily frozen revision level that is used only to record the revision after which the staging branch diverged from the main repo.

Branch "staging" is the branch students should pull, to get a local branch for new tasks, and is the destination for student pull requests.

Both will be periodically set to the same revision as master in the main repository.

Mentor Workflow

Normal code review

Aggregation cycle

Student Workflow

Normal process

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

We are going to collect up student work for several days, and then test it and submit it all together to the main repository. Because of that, we won't update from the main repository during that time. This will fix the problem students saw with having extra commits from the main repository that were not in the GCI repository appear in their pull requests.

We are going to use a branch called "staging" to hold students' work, so when you are ready to start working on code, you can pull a copy of this branch to your local repository. This is where you will send pull requests. To get a copy of this branch:

git pull edengci staging:your-branch-name

You can call your local branch whatever you want. One suggestion is to pull a fresh copy of the staging branch when you are about to start a new task. (You can keep any old branch you were working on for previous tasks, or delete it after your pull request for the previous task is accepted and merged into the staging branch. But it is better not to reuse that branch to avoid unexpected merge issues with new work. If you want to use the same branch name, then you can rename your old branch.)

Note, your commits will still have your name on them as author when they get into the main repository!

The steps to submit your work 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 -- instead, rebase *from the staging branch* -- the same branch you will send the pull request to.

  git pull --rebase edengci staging
  

• 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 the "staging" branch.
  • 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 "staging".
• Create the pull request.
• Continue with the code review as usual.

Aggregation cycle

Every few days, we will send your completed work to the main repository. In order to do this, we will need to freeze work on the staging branch, so we can use that for a pull request to the main repository. So if you happen to have a pull request open to the staging branch when this happens, we will temporarily close your pull request. Then after we have made a new staging branch with the latest updates from the main repository, we will ask you to rebase your work from the new staging branch, and open a new pull request there. The command to rebase is identical to the one above (that you would do if there is a conflict during your code review).

• Continue with the code review as usual.