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

Timestamp:

12/05/14 22:27:46 (10 years ago)

Author:

Pat Tressel

Comment:

--

DeveloperGuidelines/Git/GCI

@@ -7 +7 @@
 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.
+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 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
+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.
 
@@ -19 +19 @@
 
 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.
+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.
 
-''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 ''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.
 
-We will also have a ''staging'' branch, initially set to the same revision as the base branch, onto which student work
-is aggregated.
+(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.)
 
-The two options diverge at this point:
+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.
 
-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.
+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.
 
-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
+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.
@@ -70 +64 @@
 
 === 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.
+Branch "staging" is the destination for student work.
 
-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.
+Both are initially set to the same revision as master in the main repository.
 
-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 ==
 
@@ -108 +96 @@
 }}}
 
-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):
+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 abcde:abcde
+git pull edengci staging:your-branch-name
 }}}
 
-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:
+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 branch -m abcde abcde_backup
+git pull --rebase edengci staging
 }}}
-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.
+  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 your branch.
+  * Then use the down-arrow on the branch -- select "staging".
 * Create the pull request.
 * Continue with the code review as usual.