Working on development doc

Author: hadley

vignettes/development.Rmd

@@ -18,60 +18,46 @@ The goal of this guide is to help you get up and contributing to ggplot2 as quic
 To contribute a change to ggplot2, you follow these steps:
 
 1. Set up a local ggplot2 development environment.
-1. Create a branch in git.
-1. Make your changes.
-1. Push branch to github and issue pull request.
-1. Discuss the pull request with Winston or Hadley.
-1. Iterate until either we're happy, or we've determined that your change
-   is not a good fit for ggplot2.
+1. Create a branch in git and make your changes.
+1. Push branch to github and issue pull request (PR).
+1. Discuss the pull request.
+1. Iterate until either we accept the PR or decide that it's not
+   a good fit for ggplot2.
 
 Each of these steps are described in more detail below. This might feel overwhelming the first time you get set up, but it gets easier with practice. If you get stuck at any point, please reach out for help on the [ggplot2-dev](https://groups.google.com/forum/#!forum/ggplot2-dev) mailing list
 
 ## Basic setup
 
 If you want to do development on ggplot2 and share the changes with other people, you'll have to set up an account on GitHub. You'll make a fork of Hadley's repository and store it on GitHub. You'll also make a copy of your repository on your local machine.
 
-1.  [Set up an account](https://github.com/) on GitHub and set up ssh keys
-    as described in their instructions.
+1.  [Join github](https://github.com/join).
 
-2.  Make a fork of [Hadley's repository](https://github.com/hadley/ggplot2) by
-    clicking the Fork button in the upper right. For more info, see the
-    [GitHub page](http://help.github.com/fork-a-repo/) on forking.)
+1.  [Set up git and github](https://help.github.com/articles/set-up-git).
 
-3.  Clone your GitHub repository to your local computer (change `myname` to
-    your account name):
+1.  Fork of the main repo by going to https://github.com/hadley/ggplot2/fork.
+    A fork is a copy of ggplot2 that you can work on independently.
+    See [fork a repo](https://help.github.com/articles/fork-a-repo) for
+    more details.
+
+1.  Clone your fork to your local computer (change `myname` to your account
+    name):
 
     ```
     git clone [email protected]:myname/ggplot2.git
     cd ggplot2
     ```
 
-4.  Once you've done that, you'll probably want to add the main repository
-    as a remote:
+1.  Once you've done that, add the main repository as a remote and set up
+    the master branch to track the main ggplot2 repo. This will make it
+    easier to keep up to date.
 
     ```
     git remote add hadley git://github.com/hadley/ggplot2.git
-    git fetch hadley
+    git branch --set-upstream master hadley/master
     ```
 
 Now on your local machine you have the local repository and two remote repositories: `origin` (the default), which is your personal ggplot2 repo at GitHub, and `hadley` which is Hadley's. You'll be able to push changes to your own repository only.
 
-### Tracking a remote branch
-
-It's a good idea to set up your `master` branch to track `hadley/master`. This make it easier to update your fork of ggplot2 when the main repo changes. Do the following:
-
-```
-git checkout master
-git branch --set-upstream master hadley/master
-```
-
-Then, each time you want to get up to date, run:
-
-```
-git checkout master
-git pull
-```
-
 ### Development environment
 
 You'll also need a copy of the packages I use for package development. Get them by running the following R code:
@@ -96,46 +82,13 @@ The key functions you'll use when working on ggplot2:
 
 If you're using Rstudio, I highly recommend learning the keyboard shortcuts for these commands. You can find them in the `Build` menu.
 
+## Making changes
 
-## What makes a good pull request?
-
-Pull requests will be evaluated against the following checklist:
-
-```
-* [ ] Motivate the change in one paragraph, and include it in NEWS.
-      In parenthesis, reference your github user name and this issue:
-      `(@hadley, #1234)`
-* [ ] Check pull request only includes relevant changes.
-* [ ] Use the [official style](http://adv-r.had.co.nz/Style.html).
-* [ ] Update documentation and re-run roxygen2
-* [ ] Add test, if bug in non-graphical function
-* [ ] Add visual test, if bug in graphical function
-* [ ] Add minimal example, if new graphical feature
-```
-
-These are explained in more detail below. This seems like a lot of work but don't worry if your pull request isn't perfect. It's a learning process and Winston and I will be on hand to help you out. A pull request is a process, and unless you've submitted a few in the past it's unlikely that your pull request will be accepted as is.
-
-The most important thing is that your pull request clearly and concisely motivates the need for the change. Unfortunately neither Winston nor I have much time to work on ggplot2 these days, so you need to describe the problem and show how your pull request solves it as concisely as possible. You should also include this motivation in the `NEWS` file so that when a new release of ggplot2 comes out it's easy for users to see what's changed.
-
-When you submit your pull request, check to make sure that you haven't accidentally included any unrelated changes. These make it harder to see exactly what's changed, and to evaluate any unexpected side effects.
-
-Please follow the [official ggplot2 style](http://adv-r.had.co.nz/Style.html). Maintaing a consistent style across the whole code base makes it much easier to jump into the code. Similarly, please make sure you update the roxygen comments, and re-run `devtools::document()` on the code. Currently, ggplot2 uses the development version of roxygen2, which you can get with `install_github("klutometis/roxygen"). This will be available on CRAN in the near future.
-
-If you're fixing a bug in a non-graphical function, please include a test. If you're adding a new graphical feature, please add a minimal example illustrating the feature.
-
-Finally, ggplot2 is a mature package used by thousands of people. This means that it's basically impossible to change any existing functionality without breaking someone's code (or another package on CRAN). Because of this please don't submit pull requests that change existing behaviour. Instead, think about how you can add a new feature in a minimally invasive way.
-
-
-
-## How to make changes on a new branch
-
-When you want to make changes, you should work on a new branch. Otherwise things can get a bit confusing when it comes time to merge it into the main branch. You probably want to start with the `master` branch.
+When you want to make changes, you should work on a new branch. Otherwise things can get a bit confusing when it comes time to merge it into the main repo with a pull request. You probably want to start with the `master` branch.
 
 ```
 # Fetch the latest version of hadley/ggplot2
 git fetch hadley
-
-# Check out the latest
 git checkout hadley/master
 ```
 
@@ -152,23 +105,12 @@ Now you can make your changes and commit them to this branch on your local repos
 When you feel like sharing your changes, push them to your GitHub repo:
 
 ```
-git push origin myfix
+git push
 ```
 
 Then you can submit a pull request if you want it to be integrated in the main branch.
 
-## Resetting a branch
-
-If you have made some changes to your master branch and want to get it back in line with hadley/master, do the following. Before you do this, be sure that you are willing to discard all your commits that diverge from hadley/master! It is possible to recover the commits using `git reflog`, but it's easier to not discard them in the first place.
-
-```
-git checkout master
-git reset --hard hadley/master
-```
-
-## Testing merges
-
-If your branch has been running parallel to the main branch for a long time, it's possible that it won't merge properly. You can test it out by checking out the main branch and merging yourself.
+If you've been working on your for a while, it's possible that it won't merge properly because something has changed in both the main repo and in your branch. You can test it out by checking out the main branch and merging yourself.
 
 First, make a new branch called `testmerge`, based off the main branch:
 
@@ -194,7 +136,73 @@ git branch -D testmerge
 
 If there are any merge conflicts, you may want to rebase your changes on top of the current master version, or just resolve the conflicts and commit it to your branch. Rebasing may make for a somewhat cleaner commit history, but there is a possibility of messing things up. If you want to be safe, you can just make a new branch and rebase that on top of the current master.
 
-## Fetching a branch from someone else's repository
+## What makes a good pull request?
+
+<!--
+* [ ] Motivate the change in one paragraph, and include it in NEWS.
+      In parentheses, reference your github user name and this issue:
+      `(@hadley, #1234)`
+* [ ] Check pull request only includes relevant changes.
+* [ ] Use the [official style](http://adv-r.had.co.nz/Style.html).
+* [ ] Update documentation and re-run roxygen2
+* [ ] Add test, if bug in non-graphical function
+* [ ] Add visual test, if bug in graphical function
+* [ ] Add minimal example, if new graphical feature
+
+See http://docs.ggplot2.org/dev/vignettes/development.html for more details.
+--->
+
+Pull requests will be evaluated against the a seven point checklist:
+
+1.  __Motivation__. Your pull request must clearly and concisely motivates the
+   need for change. Unfortunately neither Winston nor I have much time to
+   work on ggplot2 these days, so you need to describe the problem and show
+   how your pull request solves it as concisely as possible.
+
+   Also include this motivation in `NEWS` so that when a new release of
+   ggplot2 comes out it's easy for users to see what's changed. Add your
+   item at the top of the file and use markdown for formatting. The
+   news item should end with `(@yourGithubUsername, #the_issue_number)`.
+
+1.  __Only related changes__. Before you submit your pull request, please
+    check to make sure that you haven't accidentally included any unrelated
+    changes. These make it harder to see exactly what's changed, and to
+    evaluate any unexpected side effects.
+
+    Each PR corresponds to a git branch, so if you expect to submit
+    multiple changes make sure to create multiple branches. If you have
+    multiple changes that depend on each other, start with the first one
+    and don't submit any others until the first one has been processed.
+
+1.  __Use ggplot2 coding style__. Please follow the
+    [official ggplot2 style](http://adv-r.had.co.nz/Style.html). Maintaing
+    a consistent style across the whole code base makes it much easier to
+    jump into the code.
+
+1.  If you're adding new parameters or a new function, you'll also need
+    to document them with [roxygen](https://github.com/klutometis/roxygen).
+    Make sure to re-run `devtools::document()` on the code before submitting.
+
+    Currently, ggplot2 uses the development version of roxygen2, which you
+    can get with `install_github("klutometis/roxygen")`. This will be
+    available on CRAN in the near future.
+
+1.  If fixing a bug or adding a new feature to a non-graphical function,
+    please add a [testthat](https://github.com/hadley/testthat) unit test.
+
+1.  If fixing a bug in the visual output, please add a visual test.
+    (Instructions to follow soon)
+
+1.  If you're adding a new graphical feature, please add a short example
+    to the appropriate function.
+
+This seems like a lot of work but don't worry if your pull request isn't perfect. It's a learning process and Winston and I will be on hand to help you out. A pull request is a process, and unless you've submitted a few in the past it's unlikely that your pull request will be accepted as is.
+
+Finally, remember that ggplot2 is a mature package used by thousands of people. This means that it's extremely difficult (i.e. impossible) to change any existing functionality without breaking someone's code (or another package on CRAN). Please don't submit pull requests that change existing behaviour. Instead, think about how you can add a new feature in a minimally invasive way.
+
+## Advanced techniques
+
+### Fetching a branch from someone else's repository
 
 Sometimes you will want to fetch a branch from someone's repository, but without going to the trouble of seting it up as a remote. This is handy if you just want to quickly try out a someone's work.
 
@@ -207,15 +215,15 @@ git checkout FETCH_HEAD
 
 Just doing the above won't create a local branch -- you'll be in "detached HEAD" state. If you'd like to create a local branch to work on, run (you can replace `somebranch` with whatever name you like):
 
-  ```
+```
 git checkout -b somebranch
 ```
 
-## Adding other repositories as remotes
+### Adding other repositories as remotes
 
 If you often work off of someone else's repository, it can be useful to add their repo as a *remote*. This makes it easier to fetch changes in their repository. If the person's GitHub account is `otherdevel`, you would do the following:
 
-  ```
+```
 git remote add otherdevel git://github.com/otherdevel/ggplot2.git
 git fetch otherdevel
 
@@ -228,15 +236,15 @@ If you don't want to follow them any more, run:
 git remote rm otherdevel
 ```
 
-## Delete a branch from GitHub
+### Delete a branch from GitHub
 
 If you pushed a branch to your GitHub repo but it's no longer needed there, you can remove it with:
 
 ```
 git push origin :mybranch
 ```
 
-## Visualizing the development tree
+### Visualizing the development tree
 
 GitHub has a very nice [development tree view](https://github.com/hadley/ggplot2/), but it of course only shows commits that have been pushed to GitHub. You may also want to view the tree on your local machine, to see how your local changes relate to the main tree. There are a number of programs out there that will do this.