Merging Changes

This project (like angular/angular) doesn't do simple merges. It uses rebases and squashes to keep a simple, linear history.

Now that GitHub lets you squash as you merge, this page is less necessary. If you're accepting a change as-is, with only commit message changes (if any), then you can push the green button.

For those other times... These notes are based on Ward's setup, and Kathy has followed them many times. Many other possibilities exist (e.g. see Using Git with Angular repositories), but this procedure is nice and simple.

If you've already set up your merge repo, go straight to Merge!

One-time setup: Create a repo just for merging

You probably already have a repo for editing, but create another for merging. You'll edit its local git configuration to make merging easier.

1. Clone the angular/angular.io repo, putting it into the same directory that contains your angular clone and any other angular.io clones you have.

cd ANGULAR-REPOS # In the directory that contains your angular repos
git clone https://github.com/angular/angular.io.git angular.io-MERGE

2. Do the usual setup required to build the docs:

cd angular.io-MERGE
nvm use 5
npm install

3. Edit the local git configuration file (not the global one):

vim .git/config  # Use your favorite editor

4. Change origin to upstream throughout the file.

5. Add aliases for pr and voodoo:

[alias]
# Add a GitHub pull request to your local repo and checkout
# Usage: git pr 123 (where 123 is the pull request number)
#   Creates a new branch: pr-123 containing the contents of the pull request
#   Replaces "git checkout upstream/pr/123 && git checkout -b pr-123"
pr = "!f() { git fetch upstream refs/pull/$1/head:pr-$1; git checkout pr-$1; } ; f"

# Do the "fetch upstream && rebase upstream master" dance
# Usage: git voodoo
voodoo = "!f() { git fetch upstream; git rebase upstream/master; } ; f"

At the end, your .git/config file should look something like this:

[core]
  repositoryformatversion = 0
  bare = false
  logallrefupdates = true
  ignorecase = true
[remote "upstream"]
  url = https://github.com/angular/angular.io.git
  fetch = +refs/heads/*:refs/remotes/upstream/*
[branch "master"]
  remote = upstream
  merge = refs/heads/master
[alias]
  # Add a GitHub pull request to your local repo and checkout
  # Usage: git pr 123 (where 123 is the pull request number)
  #   Creates a new branch: pr-123 containing the contents of the pull request
  #   Replaces "git checkout upstream/pr/123 && git checkout -b pr-123"
  pr = "!f() { git fetch upstream refs/pull/$1/head:pr-$1; git checkout pr-$1; } ; f"

  # Do the "fetch upstream && rebase upstream master" dance
  # Usage: git voodoo
  voodoo = "!f() { git fetch upstream; git rebase upstream/master; } ; f"

NOTE: You might have additional configuration, such as for filemode, symlinks, and precomposeunicode.

Merge!

1. Sync your local repo with the remote one.

git checkout master
git voodoo

git voodoo is equivalent to git fetch upstream followed by git rebase upstream/master.

We probably overuse it in these instructions, but it's better to do it unnecessarily than to forget to do it. Note that git status, and perhaps other commands, will be confused until you do that voodoo for the first time.

2. Get the pull request files. For example, if the pull request # is 123:

git pr 123

git pr is equivalent to git checkout upstream/pr/123 followed by git checkout -b pr-123.

3. If necessary, squash commits.

git rebase -i upstream/master
(...pick the first change, and fixup the rest...)

4. Make sure the commit message follows the commit message guidelines and perhaps reflects messages for similar pull requests. Almost always the commit message's last line should be "closes #123"; that will close the PR and add links between the PR and this commit.

You can change the commit message with this command:

git commit -c pr-123 --amend

Here's an example of a commit message:

docs(samples): add Dart version of pipes example

closes #123

5. Fetch and rebase master.

git voodoo

6. Make sure your branch has the commits you expect for that PR!

git log -v -n 3 

n is optional; limits the number of commits displayed

Should see the pr commit(s) followed by the top prior commits on master. Stop and reconsider if you see anything else ... or if you forgot to add the closes #123.

1. Make sure your changes didn't break the site:

gulp check-deploy

Viewing the build: By default, the pages are served at localhost:3000 and localhost:9000.

Speeding up the build: If you aren't deploying or are deploying but have already harp-built the Dart API docs, you can greatly speed up the build by making harp ignore the API docs:

gulp build-dart-cheatsheet              # If you're deploying or you made changes to the Dart cheatsheet
gulp check-deploy --lang=''             # Deploy to the website without rebuilding Dart API/cheatsheet

Deployment note: If you're pushing angular.io, make sure you have the latest changes in angular/angular and dart-lang/angular2 (next to your angular.io directory). Run this command before generating the API docs: git clean -xdf ./public/docs/dart/latest/api/. And make sure you're using the right branch/tag. On angular/angular, that's the 2.2.x branch: git voodoo; git checkout -b 2.2.x. On dart-lang/angular2, that's the latest tag, e.g.: cd ../angular-dart; git checkout tags/2.1.1 -b 2.1.1. Before deploying, spot check a few pages: homepage, cheat sheet (TS, Dart), API reference (TS, Dart).

7. Push the change.

git push upstream pr-123:master

8. Clean up.

git checkout master
git voodoo
git branch -D pr-123

9. Go to https://github.com/angular/angular.io/pulls and confirm that the PR is closed (it is no longer listed).

If it is still open—most likely because you omitted "closes #123"—close the PR now with a comment linking back to this commit.