|
| 1 | +# Contributing to robvis |
| 2 | + |
| 3 | +The goal of this guide is to help contribute to robvis as quickly as possible. |
| 4 | + |
| 5 | +Please note that robvis is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms. |
| 6 | + |
| 7 | + |
| 8 | +### Fixing typos |
| 9 | +Small typos or grammatical errors in documentation may be edited directly using the GitHub web interface of your forked repository, so long as the changes are made in the _source_ file. |
| 10 | + |
| 11 | +* DO: edit a roxygen comment in a `.R` file below `R/`. |
| 12 | +* DO NOT: edit an `.Rd` file below `man/`. |
| 13 | + |
| 14 | +Similarly, typos/errors in the supporting documents (e.g. these contributing guidelines, NEWS.md, CODE_OF_CONDUCT.md) may be edited directly using the GitHub web interface of your forked repository. |
| 15 | + |
| 16 | +The exception to the above is when typos/errors occur in the README.md document. To correct these: |
| 17 | + |
| 18 | + * Fork the respository to your personal GitHub account |
| 19 | + * Edit the README.Rmd document to fix the error |
| 20 | + * Knit the README.Rmd document to produce the corrected README.md |
| 21 | + * Commit changes and push both corrected documents to your forked respository |
| 22 | + * Issue a pull request (see the section on [Pull Requests](#pull-requests), below). |
| 23 | + |
| 24 | + |
| 25 | +### Filing an issue |
| 26 | + |
| 27 | +When filing an issue, the most important thing is to include a minimal |
| 28 | +reproducible example so that we can quickly verify the problem, and then figure |
| 29 | +out how to fix it. See "[Writing a good reproducible example](https://reprex.tidyverse.org/articles/reprex-dos-and-donts.html)". |
| 30 | + |
| 31 | + |
| 32 | +1. **Any additional required packages** should be loaded at the top of the script, so it's easy to |
| 33 | + see which ones the example needs. |
| 34 | + |
| 35 | +2. Spend a little bit of time ensuring that your **code** is easy for others to |
| 36 | + read: |
| 37 | + |
| 38 | + * make sure you've used spaces and your variable names are concise, but |
| 39 | + informative |
| 40 | + |
| 41 | + * use comments generously to indicate where your problem lies |
| 42 | + |
| 43 | + * do your best to remove everything that is not related to the problem. |
| 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 | + |
| 49 | +### Pull Requests |
| 50 | + |
| 51 | +#### Getting Started |
| 52 | +* Make sure you have a [GitHub account](https://github.com/signup/free). |
| 53 | +* Familiarise yourself with Git and Github, using the [resources](#additional-resources) at the end of this page. |
| 54 | + |
| 55 | +#### Prerequisites |
| 56 | +Before you make a substantial pull request, you should always file an issue and |
| 57 | +make sure someone from the team agrees that it’s a problem. If you’ve found a |
| 58 | +bug, create an associated issue and illustrate the bug with a minimal |
| 59 | +[reproducible example](https://reprex.tidyverse.org/articles/reprex-dos-and-donts.html). |
| 60 | + |
| 61 | +#### Pull request process |
| 62 | +* We recommend that you create a Git branch for each pull request (PR). |
| 63 | +* Look at the Travis and AppVeyor build status before and after making changes. |
| 64 | +* We use [roxygen2](https://cran.r-project.org/package=roxygen2), with |
| 65 | +[Markdown syntax](https://cran.r-project.org/web/packages/roxygen2/vignettes/markdown.html), |
| 66 | +for documentation. |
| 67 | +* For user-facing changes, add a bullet to the top of [NEWS.md](NEWS.md) below the current |
| 68 | +development version header describing the changes made followed by your GitHub |
| 69 | +username, and links to relevant issue(s)/PR(s). |
| 70 | + |
| 71 | + |
| 72 | +### Additional Resources |
| 73 | + |
| 74 | + * The [Git and Github](http://r-pkgs.had.co.nz/git.html) section of the __R Packages__ book by Hadley Wickham |
| 75 | + * [Happy Git and GitHub for the useR](https://happygitwithr.com/) |
| 76 | + * General GitHub [documentation](https://help.github.com/) |
| 77 | + * GitHub pull request [documentation]](https://help.github.com/articles/creating-a-pull-request/) |
| 78 | + |
| 79 | + |
| 80 | + |
| 81 | + |
| 82 | + |
| 83 | + |
| 84 | + |
0 commit comments