Skip to main content

GitKit (Linux Desktop Edition): Learn git and GitHub in Context

Grant Braught, Lori Postner, Darci Burdge, Ruth Lamprecht, Stoney Jackson, Karl R. Wurst

Section 1.4 Staying Synchronized Instructor Notes

At the start of this chapter, the students will have made pull requests for fixes to the "Round 1" issues that they have claimed. When these pull requests are merged into the upstream main branch it will contain changes that are not in the student’s local and origin main branches. That is, the student’s main branches will be out of synch with the upstream main. This chapter deals with how developers synchronize the main branches of their local and origin repositories with the upstream main branch.
The exercises in this chapter have the students perform the following major tasks:
  1. Set an upstream remote.
  2. Pull changes from the upstream main into their local main.
  3. Push their local main to their origin.
  4. Find a "Round 2" ticket in the issue tracker.
  5. Make changes for their "Round 2" issue and upstream them using the forking workflow from Chapter 3.

Subsection 1.4.1 Slide Notes

  1. Slides 2-3.
    A review of the elements of the forking workflow introduced and practiced in Section 2.2 and Chapter 3. Steps 3-9 on slide 3 are repeated for each contribution (e.g. bug fix, new feature). The feature branch should be pushed to the origin and the pull request made sooner rather than later, because it makes the changes available to the project maintainers for review and discussion as they are developed. Some projects will even suggest creating a PR prior to making any changes. Once the PR is created, steps 5-8 can then be repeated for each "nameable unit of work" (i.e. each commit) that is involved in completing the contribution.
  2. Slide 4.
    This diagram shows the state at the start of this chapter. The students have made pull requests for their "Round 1" issues, but those PRs will not have been merged yet. At this point, the instructor can model the actions of a project maintainer and merge a few of these PR’s (see: Subsection 1.4.2).
    In addition to merging a few PRs it is worth also discussing other actions that a maintainer might take at this point, including:
    • Reading the body of the PR to understand what is being proposed. In practice, if the change is more complex than our "Round 1" issues there would be a longer more detailed description expected. A review of the purpose of the "Closes" or "Fixes" line is also appropriate at this point.
    • Looking at the "diff" in the "Changes" tab to get a quick overview of how the contributor has implemented the proposed changes. A maintainer might insert comments directly in the code to request changes or ask questions.
    • "Pulling" a copy of the branch so that they can:
      • Run the program and observe the behavior of the proposed change.
      • Ensure that the proposed change passes all of the automated tests that the project contains.
    • In practice there may be several rounds of feedback from the maintainers and additional changes by the contributor before a PR is ready to be merged into the upstream.
  3. Slide 5.
    This diagram shows the state just after a maintainer has merged some of the "Round 1" pull requests. The key observation here is that the upstream main branch will contain some commits (e.g. blue, and/or pink, and/or lime) that the main branches in the students’ local and origin repositories do not. That is, the students’ copies of the main branch will now be out of synch with the upstream main branch.
  4. Slide 6.
    This diagram shows a developer pulling the changes to the main branch from the upstream repository into their local repository and then pushing them to their origin. This brings their copies of the main branch into synch with the upstream main branch. While it is not strictly necessary to push the main branch to the origin it keeps everything in sync.
    The diagram shows a fast forward merge meaning that the commits in the upstream main branch can simply be added to the end of the local main branch without having a merge commit. This is possible because the commits added to the upstream all build from the "green" commit AND there have been no changes to the local main.
  5. Slide 7.
    This diagram helps to justify the "Only commit to feature branches" rule. It shows the state that could arise if a developer were to make a commit to their local main branch. Here there could possibly be a conflict between the developer’s "fuchsia" commit and the "lime" commit that was added to the upstream main by a maintainer. This potential conflict prevents a fast-forward merge. Thus, by not committing to the local main branch and by using only fast-forward merges, developers can ensure that their copies of the main branch stay in synch with the upstream main. Doing so ensures that every time they create a new feature branch from main they will be starting from the most up to date state of the project.
  6. Slide 8.
    This diagram shows the state after the developer deletes the feature branch from their local and origin repositories. The changes that were contained in the feature branch have been merged into the main branches. Thus, there is no need to retain the feature branch and deleting it reduces clutter. For students, deleting their feature branches can feel like deleting their work and thus they may not want to do so. There is no real harm in them retaining their feature branches.
    It should be emphasized that they should not delete their feature branches before they have been merged into the upstream. If a PR is made for a feature branch and that branch is deleted from the developer’s origin, then the maintainers will no longer have access to the changes.
  7. Note.
    This set of materials may be a little short for a 75-minute class period. The remaining class time can be used to help students who had difficulties creating a PR, who’s PR’s cannot be merged automatically or are missing the "Closes" or "Fixes" lines.

Subsection 1.4.2 To-Do List

  1. If time permits, review the students "Round 1 pull requests as they are submitted and comment on any PRs that are missing a description or a "Closes"/"Fixes" line. Occasionally, a student will also make a PR for an issue that has not been assigned to them, commenting that they should request that the issue be assigned to them as described in Section 2.2.
  2. Prior to this class review the "Round 1" pull requests. Identify some that are suitable as examples of maintainers merging PRs into the upstream.
  3. Demonstrate the activity of a project maintainer by merging a few of the student "Round 1" pull requests. Merging all of the PRs in a class with more than a few students becomes tedious and it is sufficient to do just a few live. The remaining PRs can then be merged after introducing Chapter 4.
  4. Follow up after introducing Chapter 4 with any students who have not yet made a "Round 1" PR.

Subsection 1.4.3 Exercise Notes

  • If a student begins the GitKit activities late they may make their fork and clone after the "Round 1" issues have been merged. This will result in their origin main branch not being behind the upstream main branch. The directions in Section 4.10 of the activity have them reset the HEAD of their main branch to the commit before any "Round 1" issues were merged. Once they force push this change to their origin they will then see that their main branch is behind the upstream main as expected.
  • It is a good idea to check here that the student’s upstream remote points to the correct GitKit-FarmData2 repository. The Kit-tty should have caught this error and directed students on the correct way to set the upstream remote. However, some students have still managed to set their upstream to point to their origin or to the live FarmData2 repository.
  • After synchronizing with the upstream, the students go on to find a "Round2" ticket in the issue tracker. There are only 4 "Round2" issues, so multiple students will be working on each one. This question requests that they comment on the issue they want to work on but should spread themselves across the available "Round 2" issues. If you like you can manually assign each "Round2" issue to all students who commented on it, though this is not necessary.
  • These questions ask the student to use the forking workflow to create a fix for the "Round 2" ticket on which they chose to work. GitHub will indicate that the PRs created by each student for their "Round 2" issue can be merged automatically. This is because even though multiple students are working on each "Round 2" issue, none of them will have been merged into the upstream main at this point. When introducing Section 5.4 the instructor will merge a branch that creates conflicts with all of the student "Round2" PRs.
You have attempted of activities on this page.
PrevTopNext