Changes between Version 1 and Version 2 of DeveloperGuidelines/Git/GCI

Timestamp:

12/04/14 12:39:46 (10 years ago)

Author:

Pat Tressel

Comment:

--

DeveloperGuidelines/Git/GCI

@@ +1 @@
+[[TOC]]
 = Git Procedures for Google Code In =
+
+== Overview ==
+
+In the past, 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:[[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. 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 ==
+
+== 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.