|
| 1 | +# Contributing to `tmle3` development |
| 2 | + |
| 3 | +We, the authors of the `tmle3` R package, use the same guide as is used for |
| 4 | +contributing to the development of the popular `ggplot2` R package. This |
| 5 | +document is simply a formal re-statement of that fact. |
| 6 | + |
| 7 | +The goal of this guide is to help you get up and contributing to `tmle3` as |
| 8 | +quickly as possible. The guide is divided into two main pieces: |
| 9 | + |
| 10 | +* Filing a bug report or feature request in an issue. |
| 11 | +* Suggesting a change via a pull request. |
| 12 | + |
| 13 | +## Issues |
| 14 | + |
| 15 | +When filing an issue, the most important thing is to include a minimal |
| 16 | +reproducible example so that we can quickly verify the problem, and then figure |
| 17 | +out how to fix it. There are three things you need to include to make your |
| 18 | +example reproducible: required packages, data, code. |
| 19 | + |
| 20 | +1. **Packages** should be loaded at the top of the script, so it's easy to |
| 21 | + see which ones the example needs. |
| 22 | + |
| 23 | +2. The easiest way to include **data** is to use `dput()` to generate the R |
| 24 | + code to recreate it. For example, to recreate the `mtcars` dataset in R, |
| 25 | + I'd perform the following steps: |
| 26 | + |
| 27 | + 1. Run `dput(mtcars)` in R |
| 28 | + 2. Copy the output |
| 29 | + 3. In my reproducible script, type `mtcars <- ` then paste. |
| 30 | + |
| 31 | + But even better is if you can create a `data.frame()` with just a handful |
| 32 | + of rows and columns that still illustrates the problem. |
| 33 | + |
| 34 | +3. Spend a little bit of time ensuring that your **code** is easy for others to |
| 35 | + read: |
| 36 | + |
| 37 | + * make sure you've used spaces and your variable names are concise, but |
| 38 | + informative |
| 39 | + |
| 40 | + * use comments to indicate where your problem lies |
| 41 | + |
| 42 | + * do your best to remove everything that is not related to the problem. |
| 43 | + The shorter your code is, the easier it is to understand. |
| 44 | + |
| 45 | +You can check you have actually made a reproducible example by starting up a |
| 46 | +fresh R session and pasting your script in. |
| 47 | + |
| 48 | +(Unless you've been specifically asked for it, please don't include the output |
| 49 | +of `sessionInfo()`.) |
| 50 | + |
| 51 | +## Pull requests |
| 52 | + |
| 53 | +To contribute a change to `tmle3`, you follow these steps: |
| 54 | + |
| 55 | +1. Create a branch in git and make your changes. |
| 56 | +2. Push branch to github and issue pull request (PR). |
| 57 | +3. Discuss the pull request. |
| 58 | +4. Iterate until either we accept the PR or decide that it's not a good fit for |
| 59 | + `tmle3`. |
| 60 | + |
| 61 | +Each of these steps are described in more detail below. This might feel |
| 62 | +overwhelming the first time you get set up, but it gets easier with practice. |
| 63 | + |
| 64 | +If you're not familiar with git or GitHub, please start by reading |
| 65 | +<http://r-pkgs.had.co.nz/git.html> |
| 66 | + |
| 67 | +Pull requests will be evaluated against the a checklist: |
| 68 | + |
| 69 | +1. __Motivation__. Your pull request should clearly and concisely motivates the |
| 70 | + need for change. Plesae describe the problem your PR addresses and show |
| 71 | + how your pull request solves it as concisely as possible. |
| 72 | + |
| 73 | + Also include this motivation in `NEWS` so that when a new release of |
| 74 | + ggplot2 comes out it's easy for users to see what's changed. Add your |
| 75 | + item at the top of the file and use markdown for formatting. The |
| 76 | + news item should end with `(@yourGithubUsername, #the_issue_number)`. |
| 77 | + |
| 78 | +2. __Only related changes__. Before you submit your pull request, please |
| 79 | + check to make sure that you haven't accidentally included any unrelated |
| 80 | + changes. These make it harder to see exactly what's changed, and to |
| 81 | + evaluate any unexpected side effects. |
| 82 | + |
| 83 | + Each PR corresponds to a git branch, so if you expect to submit |
| 84 | + multiple changes make sure to create multiple branches. If you have |
| 85 | + multiple changes that depend on each other, start with the first one |
| 86 | + and don't submit any others until the first one has been processed. |
| 87 | + |
| 88 | +3. __Use `tmle3` coding style__. Please follow the |
| 89 | + [official ggplot2 style](http://adv-r.had.co.nz/Style.html). Maintaing |
| 90 | + a consistent style across the whole code base makes it much easier to |
| 91 | + jump into the code. If you're modifying existing ggplot2 code that |
| 92 | + doesn't follow the style guide, a separate pull request to fix the |
| 93 | + style would be greatly appreciated. |
| 94 | + |
| 95 | +4. If you're adding new parameters or a new function, you'll also need |
| 96 | + to document them with [roxygen](https://github.com/klutometis/roxygen). |
| 97 | + Make sure to re-run `devtools::document()` on the code before submitting. |
| 98 | + |
| 99 | +This seems like a lot of work but don't worry if your pull request isn't |
| 100 | +perfect. It's a learning process. A pull request is a process, and unless |
| 101 | +you've submitted a few in the past it's unlikely that your pull request will be |
| 102 | +accepted as is. Please don't submit pull requests that change existing |
| 103 | +behaviour. Instead, think about how you can add a new feature in a minimally |
| 104 | +invasive way. |
0 commit comments