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


Ignore:
Timestamp:
12/04/14 12:39:46 (7 years ago)
Author:
Pat Tressel
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines/Git/GCI

    v1 v2  
     1[[TOC]]
    12= Git Procedures for Google Code In =
     3
     4== Overview ==
     5
     6In the past, we had students send pull requests directly to the main repository. This led to voluminous and frequent
     7interruptions of the folks who approve submissions to the main repository. We would like to avoid this. Our intent is
     8to have mentors do complete code reviews of students' work, and assure that submissions work properly, pass tests,
     9are correctly formatted, have no conflicts, and are mergeable. We would also like to batch the submissions to the
     10main repository -- combine students' work over several days into one already-reviewed bundle, and submit that as one PR.
     11
     12After some head-scratching, discussion, and trial runs with help of GCI students, here is what we are doing.
     13It may sound complicated, but it is designed to avoid issues we encountered with a less formal procedure, in
     14which mentors and students were freely updating from the main repository, without coordination.
     15
     16We will be using a !GitHub repository just for GCI, rather than submitting code directly to the main repository.
     17The GCI repository is:[[br]]
     18https://github.com/edengci/eden
     19
     20Students will still fork the main repository, looking forward to when they will (we hope) be contributing beyond GCI.
     21However, during GCI, they will submit PRs to the GCI repository. In order to avoid chaos, we will temporarily freeze
     22the revision level on which students will work -- we will provide a base branch that students will use to populate
     23their local working branch for GCI tasks. Students will each have their own branch in the GCI repository to send PRs to
     24so reviews and merging of PRs for each student can be done asynchronously.
     25
     26We will also have a staging branch, initially set to the same revision as the base branch, onto which student work is
     27aggregated. As mentors accept pull requests, they will merge them into the staging branch. If there is a conflict at
     28this point, it will be with some other student's work, not with an update from the main repository. The mentor can
     29resolve the conflict (which the student's assistance if needed).
     30
     31Every few days, we will switch to a fresh base branch. Students can continue with PR reviews already in progress on
     32their current branches, but when they are done with that PR, they can rename their current local branch (if they want)
     33and pull a fresh local branch from the fresh GCI base branch. We can rename students' branches in the GCI repository
     34(in case we need to refer to them) or just remove them (if it's safe), and students can push their new branches. At
     35this point, all branch names will be as they were before, and work can continue as before.
     36
     37Also at this point, students' completed PRs are on the staging branch. A designated mentor will prepare the staging
     38branch for a PR to the main repository: If the staging branch is not mergeable, the mentor can pull the staging branch
     39to their local repository, merge from the main repository, fix up conflicts, and push to the staging branch again.
     40(Note rebase is probably not appropriate here, as that would require modifying students' commits. It is better to allow
     41students to have their work visible unmodified.) In any case, the combined code needs to be tested -- both running the
     42test suite and verifying that the changes still work. (To facilitate this, we can have students write what should be
     43done to exercise their change. We can rotate this mentor task, or free up one mentor from other work, and allow them to
     44be the git-meister, as this step may take some time.)
     45
     46Everyone involved -- students with submitted code and the mentors who reviewed it -- can help get that PR accepted into
     47the main repository.
     48
     49== Setup ==
     50
     51== Mentor Workflow ==
     52
     53== Student Workflow ==
     54
     55We will be using a !GitHub repository just for GCI, rather than submitting code directly to the main repository.
     56This will help us conserve the time of the (very busy) folks who have to approve submissions to the main repository.
     57
     58You'll use the GCI repository to use for pull requests.[[br]]
     59https://github.com/edengci/eden
     60
     61But you should still fork the main repository to create your own repository, and then clone your own repository.[[br]]
     62https://github.com/flavour/eden
     63
     64On your local (cloned) repository, set up a "remote" that points to the GCI repository. Open the repository page:[[br]]
     65https://github.com/edengci/eden [[br]]
     66On 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.
     67If 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
     68to !GitHub (this is the "HTTPS clone URL"):
     69{{{
     70git remote add edengci https://github.com/edengci/eden.git
     71}}}
     72Or do this if you are using SSH keys to connect to !GitHub (this is the "SSH clone URL"):
     73{{{
     74git remote add edengci git@github.com:edengci/eden.git
     75}}}
     76
     77A mentor will create a branch with your name or nick in that GCI repository to receive your pull requests. You can get a
     78copy of this branch by doing this (replace abcde with your branch name):
     79{{{
     80git pull edengci abcde:abcde
     81}}}
     82
     83Every few days, we switch to updated branches, and submit a combined PR, with all student work for those days, to the main
     84repository. (Even with this extra step, your commits will have your name on them, and will show up in the main repository.)
     85The mentor reviewing or approving your task should tell you went to switch, but you can ask, to be sure. The mentor will
     86update your branch in the GCI repository. You can rename the branch you were using locally for GCI work, just to be safe:
     87{{{
     88git branch -m abcde abcde_backup
     89}}}
     90Then redo the above pull to get another, updated, branch with your name.
     91
     92The steps to submit your work as a PR are similar to those in the git wiki page linked above -- differences are noted here.
     93* "Squash" your commits into one.
     94* ''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.
     95  (The mentors will rebase from the main repository while they are getting ready to send the combined PR.)
     96* Push your commit to your Eden repository on !GitHub.
     97* Open the !GitHub page for your Eden repository.
     98* Click the "Compare and Create Pull Request" button shown on that commit.
     99* ''This is different:'' The pull request page has a line that shows which repository and branch you are sending the pull request too.
     100  You will need to change both, to the GCI repository and your branch name in the GCI repository.
     101  * There will be a down-arrow next to the repository -- that will give you a list of repositories. Select the GCI repository.
     102  * Then use the down-arrow on the branch -- select your branch.
     103* Create the pull request.
     104* Continue with the code review as usual.