Changes between Version 5 and Version 6 of DeveloperGuidelines/Git/GCI


Ignore:
Timestamp:
12/05/14 22:27:46 (7 years ago)
Author:
Pat Tressel
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines/Git/GCI

    v5 v6  
    77interruptions of the folks who approve submissions to the main repository. We would like to avoid this. Our intent is
    88to have mentors do complete code reviews of students' work, and assure that submissions work properly, pass tests,
    9 are correctly formatted, have no conflicts, and are mergeable. We would also like to batch the submissions to the
    10 main repository -- combine students' work over several days into one already-reviewed bundle, and submit that as one PR.
     9are correctly formatted, have no conflicts, and are mergeable. We would also like to batch the submissions to the main
     10repository -- combine students' work over several days into one already-reviewed and tested bundle, and submit that as one PR.
    1111
    12 After some head-scratching, discussion, and trial runs with help of GCI students, here are two options we are considering.
    13 Both are designed to avoid issues we encountered with a less formal procedure, in which mentors and students were freely
     12After some head-scratching, discussion, and trial runs with help of GCI students, here is what seems to be a workable option.
     13It is designed to avoid issues we encountered with a less formal procedure, in which mentors and students were freely
    1414updating from the main repository, without coordination.
    1515
     
    1919
    2020Students will still fork the main repository, looking forward to when they will (we hope) be contributing beyond GCI.
     21
    2122However, during GCI, they will submit PRs to the GCI repository. In order to avoid chaos, we will temporarily freeze
    22 the revision level on which students will work -- we will provide a ''base'' branch that students will use to populate
    23 their local working branch for GCI tasks.
     23the revision level on which students will work -- we will provide a ''staging'' branch that students will pull from
     24when they start work on a new task, and to which they will submit pull requests.
    2425
    25 ''Optionally'', students will each have their own branch in the GCI repository to send PRs to so reviews and merging
    26 of PRs for each student can be done asynchronously, and so students can be released to work on other tasks more
    27 quickly, as they will not encounter conflicts.
     26We will also have a ''base'' branch that shows the revision that was current in the main repository's master branch
     27at the time we start a new aggregations cycle. This is present purely for convenience in identifying the common base
     28revision between the staging branch and the main repository's master branch. Students will not need to do anything with
     29the base branch.
    2830
    29 We will also have a ''staging'' branch, initially set to the same revision as the base branch, onto which student work
    30 is aggregated.
     31(By tradition in some popular git workflows, the master branch remains a mirror of the parent repository. To avoid
     32disturbing that tradition, we can just use different names for our branches.)
    3133
    32 The two options diverge at this point:
     34Since all student work during an aggregation cycle goes to the same staging branch, other students' work will likely be
     35merged into the staging branch while a student's PR is being reviewed, so by the time the PR is ready, there may be a
     36conflict with the other students' work. The mentor will help the student with the appropriate git procedure for rebasing
     37and resolving their conflict. This is much like the normal workflow for submitting to the main repository, so students
     38will get practice with the normal git workflow.
    3339
    34 If we are not using separate student branches, then the target of student PRs will be the staging branch.
    35 In that case, other students' work will likely be merged into the staging branch while a student's PR is being reviewed,
    36 so by the time the PR is ready, there may be a conflict with the other students' work. The mentor will help the student
    37 with the appropriate git procedure for rebasing and resolving their conflict. This is much like the normal workflow
    38 for submitting to trunk.
     40Every few days, we will switch to fresh base and staging branches: rename the current base and staging to (say)
     41base_done and staging_done, and create new base and staging branches from the main repository's master. This is the only
     42point at which coordination with students is needed. Since we don't want to delay preparing the completed code for a PR
     43to the main repository, if there are any PRs in progress, we can close those before we rename the base and staging
     44branches, and ask students to rebase from the new staging and re-open their PR there. As the students may have merge
     45conflicts at this point, we can't automate this.
    3946
    40 If we are using student branches in the GCI repository, then students will do PRs to their individual branches there.
    41 When a mentor accepts a PR, it will be merged into the students branch in the GCI repository. Since no-one else is
    42 updating that branch, there will be no conflict. Mentors will then merge the student's branch into the staging branch.
    43 If there is a conflict at this point, it will be with some other student's work, not with an update from the main
    44 repository. Conflicts should be relatively easy to resolve, as commits should be small. The mentor can resolve the
    45 conflict, with the student's assistance if needed.
    46 
    47 Every few days, we will switch to a fresh base branch. Students can continue with PR reviews already in progress on
    48 their current branches, but when they are done with that PR, they can rename their current local branch (if they want)
    49 and pull a fresh local branch from the fresh GCI base branch. We can rename students' branches in the GCI repository
    50 (in case we need to refer to them) or just remove them (if it's safe), and students can push their new branches. At
    51 this point, all branch names will be as they were before, and work can continue as before.
    52 
    53 At this point, students' completed PRs are on the staging branch. A designated mentor will prepare the staging
     47At this point, students' completed PRs are on the staging_done branch. A mentor will prepare the staging_done
    5448branch for a PR to the main repository: If the staging branch is not mergeable, the mentor can pull the staging branch
    5549to their local repository, merge from the main repository, fix up conflicts, and push to the staging branch again.
     
    7064
    7165=== Branches ===
    72 We can retain the master branch as a mirror of the main (trunk) repository -- it won't be otherwise involved in the GCI workflow.
    73 
    7466Branch "base" is a temporarily frozen revision level that is used to set up new student branches.
    7567
    76 Branch "staging" is the destination for student work. After a student's work is accepted, it is merged into the staging branch.
     68Branch "staging" is the destination for student work.
    7769
    78 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.
    79 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
    80 dispense with student branches, and have them do PRs directly to the staging branch.
     70Both are initially set to the same revision as master in the main repository.
    8171
    82 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
    83 same revision as the base branch.
    8472== Mentor Workflow ==
    8573
     
    10896}}}
    10997
    110 A mentor will create a branch with your name or nick in that GCI repository to receive your pull requests. You can get a
    111 copy of this branch by doing this (replace abcde with your branch name):
     98We are going to collect up student work for several days, and then test it and submit it all together to the main repository.
     99Because of that, we won't update from the main repository during that time. This will fix the problem students saw with having
     100extra commits from the main repository that were not in the GCI repository appear in their pull requests.
     101
     102We are going to use a branch called "staging" to hold students' work, so when you are ready to start working on code, you can
     103pull a copy of this branch to your local repository. This is where you will send pull requests. To get a copy of this branch:
     104
    112105{{{
    113 git pull edengci abcde:abcde
     106git pull edengci staging:your-branch-name
    114107}}}
    115108
    116 Every few days, we switch to updated branches, and submit a combined PR, with all student work for those days, to the main
    117 repository. (Even with this extra step, your commits will have your name on them, and will show up in the main repository.)
    118 The mentor reviewing or approving your task should tell you went to switch, but you can ask, to be sure. The mentor will
    119 update your branch in the GCI repository. You can rename the branch you were using locally for GCI work, just to be safe:
     109You can call your local branch whatever you want. One suggestion is to pull a fresh copy of the staging branch when you are about
     110to 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
     111the previous task is accepted and merged into the staging branch. But it is better not to reuse that branch to avoid unexpected
     112merge issues with new work. If you want to use the same branch name, then you can rename your old branch.)
     113
     114Note, your commits will still have your name on them as author when they get into the main repository!
     115
     116The steps to submit your work are similar to those in the git wiki page linked above -- differences are noted here.
     117* "Squash" your commits into one.
     118* ''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.
    120119{{{
    121 git branch -m abcde abcde_backup
     120git pull --rebase edengci staging
    122121}}}
    123 Then redo the above pull to get another, updated, branch with your name.
    124 
    125 The steps to submit your work as a PR are similar to those in the git wiki page linked above -- differences are noted here.
    126 * "Squash" your commits into one.
    127 * ''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.
    128   (The mentors will rebase from the main repository while they are getting ready to send the combined PR.)
    129122* Push your commit to your Eden repository on !GitHub.
    130123* Open the !GitHub page for your Eden repository.
    131124* Click the "Compare and Create Pull Request" button shown on that commit.
    132125* ''This is different:'' The pull request page has a line that shows which repository and branch you are sending the pull request too.
    133   You will need to change both, to the GCI repository and your branch name in the GCI repository.
     126  You will need to change both, to the GCI repository and the "staging" branch.
    134127  * There will be a down-arrow next to the repository -- that will give you a list of repositories. Select the GCI repository.
    135   * Then use the down-arrow on the branch -- select your branch.
     128  * Then use the down-arrow on the branch -- select "staging".
    136129* Create the pull request.
    137130* Continue with the code review as usual.