[concept] Rationale for Github pull request

[dorawyy]

Create a pull request

• Pull requests can only be opened if there are differences between your branch and the upstream branch. You can specify which branch you'd like to merge your changes into when you create your pull request.
• If you don't have write access to the repository where you'd like to create a pull request, you must create a fork, or copy, of the repository first. For more information, see "Creating a pull request from a fork" and "About forks."

  Changing the branch range and destination repository

• By default, pull requests are based on the parent repository's default branch.
• If the default parent repository isn't correct, you can change both the parent repository and the branch with the drop-down lists.
• You can also swap your head and base branches with the drop-down lists to establish diffs between reference points. References here must be branch names in your GitHub repository.

Pull request from a fork

• Collaborating with issues and pull requests
• Creating a pull request from a fork
  • it mentioned that when making pull request between forks, the pull request creator can choose whether to allow the upstream repo owner make commits on the fork or not.

• Defining the mergeability of pull requests

  • protected branch

    

  • status check

    • developers can set up protected branches, which means every commit pushed to that the protected branch ( base branch in pull requests) has to pass all status checks
    • Types of required status checks : strict/loose/disabled
    • Enabling required status checks: make use of the Status API
    • About branch restrictions
    • About required reviews for pull requests

[dorawyy]

Findings

• Changing the base branch of a pull request
  • After a pull request is made, the base branch can still be changed, but the head branch cannot be changed
• Committing changes to a pull request branch created from a fork
  • Generally speaking, as the owner of the upstream repo, you don't have access to the pull request branch (from the fork); However, the person who made the pull request can grant you access to commit on his/her pull request branch
  • Also, you can make a fork of the forked repo, then make commit on your fork of the forked repo, then pull request to merge commits to the forked repo.

[dorawyy]

Addressing merge conflicts in pull request

Types of merge conflicts

• competing line conflict (aka, content modification conflict);
• removed file merge conflicts (aka, modification/deletion conflict).

About merge conflicts

• You must resolve the conflict before you can merge the branches.
• You cannot merge your pull request branch on GitHub until you resolve the merge conflict
• To resolve merge conflicts, you have two options
  • merge on Github if the conflict is a competing line conflict
  • merge locally on command line for any type of conflicts, namely (1)competing line conflict(aka, content modification conflict); (2) removed file merge conflicts(aka, modification/deletion conflict).

Resolving a merge conflict on GitHub

• Only competing line conflicts can be resolved on Github, all other merge conflicts have to be resolved locally via command line ( -- for pull request proposer)
• When all conflicts are resolved, clock Commit merge in Github merge tool, this will merge the entire base branch into your head branch (pull request branch)
• Then, the pull request can be further merged.

Resolving a merge conflict using the command line

• dealing with non-fast-forward errors. If another person pushed to the same branch s you, you need to fix by fetching and merging before pushing

  
  git checkout lcoal_branch

fetch & merge

git fetch origin git merge origin remote_branch

or pull directly

git pull origin remote_branch

[dorawyy]

Merging a pull request

Anyone with push access to the repo can complete the merge.

If the pull request does not have any merge conflicts, you can merge it on Github. If the pull request does have merge conflicts, or if you'd like to rest the changes before merging, you can check out the pull request locally and merge it using the command line.

If you decide you don't want the changes in a topic branch to be merged to the upstream branch, you can close the pull request without merging.

Checking out pull requests locally

• Basically, follow the command line instruction here (is the instruction of option1, merge pull request)

  (as can be seen from the screenshot above, forbids fast-forward merging with --no-ff param)

Modifying an inactive pull request locally

• An inactive pull request is one whose owner has either stopped responding, or, more likely, has deleted their fork.

• If a fork was deleted, the pull request can still be merged. However, if you want to make changes to a pull request and the author is not responding, you'll need to perform some additional steps to update the pull request.

• Once a pull request is opened, GitHub stores all of the changes online for you. In other words, commits in a pull request are available in a repository even before the PR is merged. That means you can fetch an open pull request and recreate it as your own

• Anyone can work with a previously opened pull request to continue working on it, test it out, or even open a new pull request with additional changes. However, only collaborators with push access can merge pull requests.

With issueID/ pull request ID, anyone can recreate all commits inside belonging to the issue/pull request

• Step1: find the ID number of the inactive pull request.

• Step2: In terminal, fetch reference to the pull request based on ID, creating a new branch in the process

  # format:
  git fetch origin pull/ID/head:BRANCH
  # example: 
  git fetch origin pull/60/head:PullRequest60

• Step3: checkout a branch based on the pull request

  
  # format:
  git checkout BRANCH

example:

git checkout PullRequest60

**Details of Pull Request #60:**
![1510366664050](https://user-images.githubusercontent.com/16771854/32685312-8bb2376a-c643-11e7-821b-eed4d26f8242.jpg)
**Commits containing inside Pull Request #60:**
<img width="1161" alt="screen shot 2017-11-10 at 6 21 01 pm" src="https://user-images.githubusercontent.com/16771854/32685340-f8c6c21c-c643-11e7-8d5a-0d4e2f8aeeb5.png">
**Commits of the newly created branch `PullRequest60`(corresponding to pull request #60):**
![wx20171110-183038](https://user-images.githubusercontent.com/16771854/32685407-5c97f652-c645-11e7-9c05-cb57804280da.png)
**Comparing with commits history of `PR1`(base branch of the pull request):** 
<img width="948" alt="wx20171110-183541 2x" src="https://user-images.githubusercontent.com/16771854/32685446-61ecc640-c646-11e7-91af-81c8e88a26b7.png">

* Step4: Now, you can do anything you want with this branch. You can run some local tests, or merge other branches into it, including `master`. **Make any modifications!**

* Step5: When ready, you can push the branch to remote, and create a new pull request from it.

[dorawyy]

Merging a pull request on GitHub

• Option1: retaining all the commits in a feature branch;
• Option2: squashing all commits into a single commit
• Option3: rebasing individual commits from the head branch onto the base branch.

Merge all of the commits into the base branch

• To merge pull requests, you must have write permissions in the repository.
• Actually do a n-way merge with --no-ff param:

  git checkout BaseBranch
  git merge HeadBranch --no-ff

  

Squash and merge your pull request commits

• The pull request's commits are squashed into a single commit.
• Pull requests with squashed commits are merged using the fast-forward option.
• Requirements:
  • you must have write permissions in the repository,
  • and the repository must allow squash merging.

Rebase and merge your pull request commits

• all commits from the head branch (or pull request branch) are added onto the base branch individually without a merge commit

• Requirement:

  • you must have write permissions in the repository,
  • and the repository must allow rebase merging

• The rebase and merge behavior on GitHub deviates slightly from git rebase.

  • Rebase and merge on GitHub will always update the committer information and create new commit SHAs;
  • whereas git rebase outside of GitHub does not change the committer information when the rebase happens on top of an ancestor commit.

• You aren't able to automatically rebase and merge on GitHub when:

  • The pull request has merge conflicts.
  • Rebasing the commits from the base branch into the head branch runs into conflicts.
  • Rebasing the commits is considered "unsafe," such as when a rebase is possible without merge conflicts but would produce a different result than a merge would.

• If you still want to rebase the commits but can't rebase and merge automatically on GitHub you must:

  • Rebase the topic branch (or head branch) onto the base branch locally on the command line
  • Resolve any merge conflicts on the command line.
  • Force-push the rebased commits to the pull request's topic branch (or remote head branch).

[dorawyy]

Comparing commits across time (Compare View)

• Every repository contains a Compare view, which allows you to compare the state of your repository across branches, tags, commits, time periods, and more. The compare view provides you with the same diff tooling that the Pull Request view does.

• To get to the compare view, append /compare to your repository's path.

• Link to the compare view of the current repo: https://github.com/dorawyy/git-merge-conflicts-test/compare

• Every repository's Compare view contains two drop down menus: base and compare.

  

• base should be considered the starting point of your comparison, and compare is the endpoint.

• During a comparison, you can always change your base and compare points by clicking on Edit.

Comparing branches

• The most common use of Compare is to compare branches, such as when you're starting a new Pull Request. You'll always be taken to the branch comparison view when starting a new Pull Request.
• To compare branches, you can select a branch name from the compare drop down menu at the top of the page.
• Here's an example of a comparison between two branches.

Comparing tags

• Similarly, you can compare across tags made for project releases. Comparing against tags is a great way to assemble release notes between different versions of your project.
• Instead of typing a branch name, type the name of your tag in the compare drop down menu.
• Here's an example of a comparison between two tags.

Comparing commits

• You can also compare two arbitrary commits in your repository. Comparisons between commits are made by providing either the full SHA hash or the short seven-character code.
• Here's an example of a comparison between two commits.

Comparing across forks

• You can compare your base repository and any forked repository. This is the view that's presented when a user performs a Pull Request to a project.
• To compare branches on different repositories, preface the branch names with user names. For example, by specifying octocat:master for base and octo-org:master for compare, you can compare the master branch of the repositories respectively owned by octocat and octo-org.
• Here's an example of a comparison between two repositories.

Comparisons across time

• Comparisons can be created for arbitrary time periods, like one month or two weeks. To define a time period, type the branch name, followed by a @, and then the date wrapped between a { } notation. For example, typing master@{2weeks} into the base dropdown menu compares the current master branch against the master branch as it was two weeks prior.
• Here's an example of a comparison between two time periods.
• You can also specify a specific date to compare against. Date formatting must follow the ISO8601 standard, which is YYYY-MM-DD (year-month-day).
• Here's an example comparing a branch from 2016-07-22 against that same branch several days later.

Comparisons across commits

• As a shortcut, Git uses the ^ notation to mean "one commit prior."
• You can use this notation to compare a single commit or branch against its immediate predecessors. For example, 96d29b7^^^^^ indicates five commits prior to 96d29b7, because there are five ^ marks. Typing 96d29b7^^^^^ in the base branch and 96d29b7 in the compare branch compares the five commits made before 96d29b7 with the 96d29b7 commit.

Here's an example of a comparison using the ^ notation.

[dorawyy]

By default, can original repo's owner push to fork (both public)?

Answer:

• No, if the repo is a public repo, then by default, original repo's collaborators don't have push access to the fork repo.

Here are the details:

1. Original repo's colalborators can propose commits to the fork, all commits they proposed will go via pull requests

2. Then transferring to the compare view (comparing the patch branch on original repo and the branch you want to commit to of the fork repo

3. All commits will be made in the committer's own repo (original repo in this testcase), via checking out a new patch branch

[dorawyy]

By default, the pull request would grant upstream repo's owner push access to the fork repo branch

The developer has to manually uncheck this to disable push access from upstream repo's collaborator