You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: vignettes/development.Rmd
+62-50Lines changed: 62 additions & 50 deletions
Original file line number
Diff line number
Diff line change
@@ -13,50 +13,17 @@ knitr::opts_chunk$set(
13
13
14
14
# Contributing to ggplot2 development
15
15
16
-
The goal of this guide is to help you get up and contributing to ggplot2 as quickly as possible. It's still a work in progress and very rough. Your feedback is much appreciated and so are pull requests :).
16
+
The goal of this guide is to help you get up and contributing to ggplot2 as quickly as possible. It's still a work in progress and very rough. Your feedback is much appreciated and so are pull requests :). Rather than emailing me directly about questions, please discuss ggplot2 development issues on the [ggplot2-dev](https://groups.google.com/forum/#!forum/ggplot2-dev) mailing list. That way multiple people can learn at the same time.
17
17
18
-
## What makes a good pull request?
19
-
20
-
Pull requests will be evaluated against the following checklist:
21
-
22
-
```
23
-
* [ ] Motivate the change in one paragraph, and include it in NEWS.
24
-
Reference this issue and thank yourself.
25
-
* [ ] Check pull request only includes relevant changes.
26
-
* [ ] Use the [official style](http://adv-r.had.co.nz/Style.html).
27
-
* [ ] Update documentation and re-run roxygen2
28
-
* [ ] Add test, if bug in non-graphical function
29
-
* [ ] Add minimal example, if new graphical feature
30
-
* [ ] Does not change existing behaviour
31
-
```
32
-
33
-
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.
34
-
35
-
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.
36
-
37
-
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.
38
-
39
-
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.
40
-
41
-
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.
18
+
To contribute a change to ggplot2, you follow these steps:
42
19
43
-
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.
44
-
45
-
## Super-basic setup
46
-
47
-
If you just want to track the development of ggplot2 and do work on your own local branch, just clone Hadley's repository:
48
-
49
-
```
50
-
git clone https://github.com/hadley/ggplot2.git
51
-
```
52
-
53
-
That's it. You don't even have to set up an account on GitHub. To get the latest updates, run:
54
-
55
-
```
56
-
git pull
57
-
```
58
-
59
-
Once you've cloned the repo, you can branch, change, and commit. You just won't be able to publish your changes to GitHub. (If you later want to publish these changes to GitHub, it is possible. Ask the mailing list if you need assistance.)
20
+
1. Set up a local ggplot2 development environment.
21
+
1. Create a branch in git.
22
+
1. Make your changes.
23
+
1. Push branch to github and issue pull request.
24
+
1. Discuss the pull request with Winston or Hadley.
25
+
1. Iterate until either we're happy, or we've determined that your change
26
+
is not a good fit for ggplot2.
60
27
61
28
## Basic setup
62
29
@@ -87,31 +54,76 @@ If you want to do development on ggplot2 and share the changes with other people
87
54
88
55
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.
89
56
57
+
### Tracking a remote branch
90
58
91
-
## Tracking a remote branch
92
-
93
-
You can set up your `master` branch to track `hadley/master`. This isn't strictly necessary, but it can make things simpler. Do the following:
59
+
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:
94
60
95
61
```
96
62
git checkout master
97
63
git branch --set-upstream master hadley/master
98
64
```
99
65
100
-
Then, each time you want to get it up to date, run:
66
+
Then, each time you want to get up to date, run:
101
67
102
68
```
103
69
git checkout master
104
70
git pull
105
71
```
106
72
107
-
Or, equivalently:
73
+
### Development environment
74
+
75
+
You'll also need a copy of the packages I use for package development. Get them by running the following R code:
108
76
77
+
```{r, eval = FALSE}
78
+
install.packages(c("devtools", "testthat"))
79
+
devtools::install_github("klutometis/roxygen")
109
80
```
110
-
git checkout master
111
-
git fetch hadley
112
-
git merge hadley/master
81
+
82
+
Next, install all the suggested packages that ggplot2 needs. To do this either open the ggplot2 rstudio project, or set your working directory to the ggplot2 directory, then run:
83
+
84
+
```{r, eval = FALSE}
85
+
install_deps(deps = T)
113
86
```
114
87
88
+
The key functions you'll use when working on ggplot2:
89
+
90
+
*`devtools::load_all()`: loads all code into your current environment
91
+
*`devtools::document()`: updates the roxygen comments
92
+
*`devtools::test()`: run all unit tests
93
+
*`devtools::check()`: runs R CMD check on the package to check for errors.
94
+
95
+
If you're using Rstudio, I highly recommend learning the keyboard shortcuts for these commands. You can find them in the `Build` menu.
96
+
97
+
98
+
## What makes a good pull request?
99
+
100
+
Pull requests will be evaluated against the following checklist:
101
+
102
+
```
103
+
* [ ] Motivate the change in one paragraph, and include it in NEWS.
104
+
Reference this issue and thank yourself.
105
+
* [ ] Check pull request only includes relevant changes.
106
+
* [ ] Use the [official style](http://adv-r.had.co.nz/Style.html).
107
+
* [ ] Update documentation and re-run roxygen2
108
+
* [ ] Add test, if bug in non-graphical function
109
+
* [ ] Add minimal example, if new graphical feature
110
+
* [ ] Does not change existing behaviour
111
+
```
112
+
113
+
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.
114
+
115
+
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.
116
+
117
+
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.
118
+
119
+
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.
120
+
121
+
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.
122
+
123
+
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.
124
+
125
+
126
+
115
127
## How to make changes on a new branch
116
128
117
129
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.
0 commit comments