forked from ropensci/dev_guide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathmaintenance_contributing.Rmd
90 lines (46 loc) · 7.13 KB
/
maintenance_contributing.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
# Contributing Guide {#contributingguide}
```{block, type='summaryblock'}
This chapter outlines how you can contribute to the rOpenSci project as a user or developer.
```
So you want to contribute to rOpenSci? Fantastic! First of all, maybe contributing code or documentation to a package is not the (only) way you’ll want to get involved. Check out our [community page](https://ropensci.org/community/) to find out all the ways to participate in the project, from reading about our packages to volunteering to review them.
We strive to make contributing to our suite a constructive and positive experience and we welcome participation that adheres to [our code of conduct](https://ropensci.org/code-of-conduct).
If you wish to contribute to this guide itself, please report any suggestions via [this GitHub repository](https://github.com/ropensci/dev_guide).
## Why contribute to rOpenSci packages?
In general, [as explained by Kara Woo in her talk at the CascadiaR conference](https://github.com/karawoo/2018-06-02-cascadiarconf/blob/master/cascadiarconf.pdf), contributing to R packages allows you to make things work the way you want (by adding some functionality to your favorite package), can lead to opportunities and allows you to learn about package development.
Specifically at rOpenSci, we strive to make contributing a good experience. This is embedded in [our mission](https://ropensci.org/about/): we are creating social infrastructure through a welcoming and diverse community and building capacity of software users and developers and fostering a sense of pride in their work.
## Non code contributions
### Reporting use cases for our packages or guidelines
It’s valuable to both users and developers of a package to see how it has been used “in the wild”. If you see a use case of one of our packages, please add it to our [public forum in the Use Cases category](https://discuss.ropensci.org/c/usecases). We’ve created a template to help. We’ll tweet about it, and might add it to the [rOpenSci biweekly newsletter](https://news.ropensci.org/). You might also let the package author know by opening an issue in the GitHub repository for that package, perhaps suggesting they create a “use cases in the wild” section in the README, and maybe even tag them in a tweet about the use case. This goes a long way to encouraging people to keep up development knowing there are others who appreciate and build on their work.
See examples of README's listing use cases in the wild [here](https://github.com/ropenscilabs/ghrecipes/blob/master/README.md#use-cases-in-the-wild) and [here](https://github.com/ropensci/riem/blob/master/README.md#use-cases-in-the-wild)
We would also love to hear about examples in which rOpenSci resources or guidelines have been used. Have you implemented better security practices, like signing your commits, based on recommendations in a [Community Call](https://ropensci.org/commcalls/), or used our standards/checklists etc. when reviewing software elsewhere? Do tell people (e.g. journal editors, students, internal code review group, users) that they came from rOpenSci, and tell us in [our public forum](https://discuss.ropensci.org/c/usecases), or [privately by email](https://ropensci.org/contact/).
### Reporting issues or Requesting features
If you already have a package in mind, head to its issue tracker to report a bug or a feature request you might have. E.g. if you have a feature request for `magick`, the place to fill it is https://github.com/ropensci/magick/issues
When reporting a bug try to include a reproducible example ("[reprex](https://www.tidyverse.org/help/#reprex)") to help the package author help you.
### Asking other questions
You can use our [discussion forum](https://discuss.ropensci.org/) to ask questions related to the usage of our packages, even when you don't know yet which of our packages could help you.
For more guidance about where to ask questions related to rOpenSci packages, refer to Scott Chamberlain's talk in this [community call](https://ropensci.org/commcalls/2017-03-07/) or the [corresponding slidedeck](https://scotttalks.info/qropensci/).
## Code contributions
### Prerequisites for package development
Before contributing to one of our packages, you might want to read a bit more about package development in general and our guidelines.
#### Learning about package development
##### Tutorials
* [Hilary Parker's famous blog post *Writing an R package from scratch*](https://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/) or [its updated version by Tomas Westlake](https://r-mageddon.netlify.com/post/writing-an-r-package-from-scratch/) that shows how to do the same more efficiently using `usethis`.
* [this workflow description by Emil Hvitfeldt](https://www.hvitfeldt.me/2018/09/usethis-workflow-for-package-development/)
* [This pictorial by Matthew J Denny](https://www.mjdenny.com/R_Package_Pictorial.html)
##### Books
* [Hadley Wickham and Jenny Bryan's *R packages* book](https://r-pkgs.org/)
* [*Writing R extensions*, the official CRAN guide](https://cran.r-project.org/doc/manuals/r-release/R-exts.html)
* [*Mastering Software Development in R* by Roger D. Peng, Sean Kross, and Brooke Anderson](https://bookdown.org/rdpeng/RProgDA/)
* [*Advanced R* by Hadley Wickham](https://adv-r.hadley.nz/)
* [*Testing R code* by Richard Cotton](https://www.crcpress.com/Testing-R-Code/Cotton/p/book/9781498763653)
##### MOOCs
There is a [Coursera specialization corresponding to the book by Roger Peng, Sean Kross and Brooke Anderson](https://fr.coursera.org/specializations/r), with a course specifically about R packages.
#### Reading about our guidelines
See the whole first section of this book: [Building Your Package](#building)
### Finding where to contribute code or documentation
Our packages are developed on GitHub. We have two organizations:
* https://github.com/ropensci for more mature packages, including some developed by rOpenSci staff and some developed by community members whose packages have gone through [software peer review](#softwarereviewintro)
* https://github.com/ropenscilabs for experiments and packages that are not ready for release yet.
If you already know what package you’d like to contribute to, have a look at its issue tracker and comment in one of the issues to ask the maintainer whether they'd be interested in your help. E.g. if you like `taxize`, the place to look is https://github.com/ropensci/taxize/issues
If you’re not sure which package you’d like to contribute to, you can start by browsing [our packages page](https://ropensci.org/packages/). To browse issues targeted at beginners you could try [the `contributr` Shiny app by Lucy D'Agostino McGowan](https://ropensci.shinyapps.io/contributr/) or use an advanced GitHub search such as [this one](https://github.com/search?q=user%3Aropensci+user%3Aropenscilabs+label%3ABeginner+state%3Aopen&type=Issues) that gets all issues from "ropensci" or "ropenscilabs" organizations that are open and labelled "beginner".
Still not sure how you can contribute? [Tell us about your expertise and interests](https://discuss.ropensci.org/c/contributing) and we’ll try to match you with a package that could use your help.