Skip to content
This repository has been archived by the owner on Dec 4, 2017. It is now read-only.

Technical Editing for Angular Docs

Jump to bottom
Kathy Walrath edited this page Jul 6, 2016 · 1 revision

One-time setup

You need to get local copies of the angular/angular and angular.io repos. Because you'll be making changes to angular.io, you first need to fork that repo.

After you have local copies of the repos, you'll need to change the configuration.

  1. Go to https://github.com/angular/angular.io, and click the Fork button at the upper right.
    This creates a repo at https://github.com/YOUR_ID/angular.io, where YOUR_ID is your GitHub ID.

  2. In a terminal window, create a directory to hold your clones of angular and angular.io. We'll call it ~/angular, but you could use a different location.

mkdir ~/angular
  1. Clone the repos.
cd ~/angular
git clone https://github.com/angular/angular.git
git clone https://github.com/YOUR_ID/angular.io.git # YOUR-ID -> your GitHub ID

These commands create directories named angular and angular.io that hold clones of the angular/angular and angular/angular.io repos, respectively. From here on out, unless otherwise stated, all instructions apply only to the angular.io directory.

  1. Tell your angular.io clone about its grandparent, which we call upstream:
$ git remote add upstream [email protected]:angular/angular.io.git
  1. Create ssh keys: ssh-keygen -t rsa -C "[email protected]"
ssh-add ~/.ssh/id_rsa
pbcopy < ~/.ssh/id_rsa.pub

  1. Paste your keys into GitHub, under SSH Keys for your account. [PENDING: test, flesh out these instructions]

    curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.2/install.sh | bash

  2. Under the new angular.io directory, do the usual setup required to build the docs:

cd ~/angular/angular.io
nvm use 5
npm install

[PENDING: Check. Specifying nvm might not be necessary any more.]

MAYBE ALSO:

  1. 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"

Now that you're set up, you can view the docs, create your own pull requests, and review other people's pull requests.

Run a doc server

From the top directory of the angular.io clone, run gulp check-deploy:

cd ~/angular/angular.io
gulp check-deploy

TODO: Flesh this out

Edit a pull request

NOTE: This section is preliminary; we'll probably edit or delete it.

  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.

  1. 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.

  1. If necessary, squash commits.
git rebase -i upstream/master
(...pick the first change, and fixup the rest...)
  1. 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
  1. Fetch and rebase master.
git voodoo
  1. 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
  1. Push the change.
git push upstream pr-123:master
  1. Clean up.
git checkout master
git voodoo
git branch -D pr-123
  1. 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.

Clone this wiki locally