[[TOC]]
= 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 are two options we are considering.
Both are 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:[[br]]
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.

''Optionally'', 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, and so students can be released to work on other tasks more
quickly, as they will not encounter conflicts.

We will also have a ''staging'' branch, initially set to the same revision as the base branch, onto which student work
is aggregated.

The two options diverge at this point:

If we are not using separate student branches, then the target of student PRs will be the staging branch.
In that case, 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 trunk.

If we are using student branches in the GCI repository, then students will do PRs to their individual branches there.
When a mentor accepts a PR, it will be merged into the students branch in the GCI repository. Since no-one else is
updating that branch, there will be no conflict. Mentors will then merge the student's branch 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. Conflicts should be relatively easy to resolve, as commits should be small. The mentor can resolve the
conflict, with 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.

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:[[br]]
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.[[br]]
https://github.com/edengci/eden

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

On your local (cloned) repository, set up a "remote" that points to the GCI repository. Open the repository page:[[br]]
https://github.com/edengci/eden [[br]]
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.