For comparison until the next release (ropensci#160)

* update dev (ropensci#157) * draft book release guidance (ropensci#152) * include the book release guidance in the book * update news * clarify release guidance * Remove "click here" link (ropensci#166) * Update all links to HTTPS (ropensci#167) * URLs should be enclosed in angle brackets, e.g. <https://www.r-project.org> (ropensci#169) --https://cran.r-project.org/doc/manuals/r-release/R-exts.html * Expand on what 'more discoverable' means (ropensci#172) * fix @melvidoni's affiliation in dev too * new dev guide URL * add mention of usethis functions for adding testing or vignette infrastructure in the part about dependencies in the package building guide thx @cboettig fix ropensci#112 * remove recommendation about `roxygen2` dev version since the latest stable version has what is needed. fix ropensci#165 thanks @Bisaloo * add more details about gitflow * more direct link to Amanda's write-up * update ref to R pkg book * fix ropensci#163 now that the book is less new * Update pkg_building.Rmd (ropensci#178) * Update pkg_building.Rmd See ropensci#151 * Update appendix.Rmd As requested. * Update index.Rmd As requested. * Rodev mentions (ropensci#176) Fix ropensci#48 * CRAN checks explanations (ropensci#177) * Explain CRAN checks * add that rOpenSci maintains API Fix ropensci#175 * docs.ropensci.org guidance (ropensci#162) fix ropensci#164 and cf ropensci#155 * fix ropensci#155 by improving pkgdown guidance * suggest R Markdown hunks approach for README and vignette (ropensci#161) * fix ropensci#179 by fixing formatting of Appendices B-D in the pdf version of the book * make NEWs template look ok again cf ropensci#179 * fix ref to R packages book * add link to rOpenSci community call "Security for R" to security chapter cf ropensci#154 * Add note about pkgreviewr Rstudio dependency. Resolves ropensci#183 * Break up reproducibility category into component parts (ropensci#184) - Also increase clarity that software wrappers are for non-R programs - Re-arrange thematically - Add appropriate examples Closes ropensci/software-review-meta#81 * fix ropensci#192 update instructions in readme for rendering book locally, _book instead of _output and updated NEWS * fix spelling and missing "an" in Code Style subsection within Packaging Guide section (ropensci#182) * fix ropensci#193 change slack channel name to software-review from onboarding in editor checklist add entry to news * ropensci#128 taking over maint. chapter work, moved to new branch * move taking over to chapter 10 * spelling changs in taking over chapter * add news item for the taking over chapter ropensci#128 * Update JOSS instrucctions * Explicitly use RO repo url in JOSS submittal. * fix ropensci#180 add note for handling editors to nominate blog posts of interest * fix some links in the changelog * Fix ropensci#181 typo * fix ropensci#191 add to approval template mention of including docs.ropensci.org link in DESCRIPTION file * fix section link to docsropensci in pkg building chapter, was missing pound sign * fix some broken urls in pkg_building * fix spelling problems after using spelling
rcorces · Oct 4, 2019 · 0a8f24d · 0a8f24d
1 parent 303f807
commit 0a8f24d
Show file tree

Hide file tree

Showing 23 changed files with 314 additions and 89 deletions.
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@ rOpenSci Packages: Development, Maintenance, and Peer Review
 [![Build Status](https://travis-ci.org/ropensci/dev_guide.svg?branch=master)](https://travis-ci.org/ropensci/dev_guide)
 [![DOI](https://zenodo.org/badge/126815002.svg)](https://zenodo.org/badge/latestdoi/126815002)
 
-rOpenSci's guide for packages in our suite. [Read it here](https://ropensci.github.io/dev_guide/).
+rOpenSci's guide for packages in our suite. [Read it here](https://devguide.ropensci.org/).
 
 ## Contributing
 
@@ -27,7 +27,7 @@ We copied this [setup from Data Carpentry](https://github.com/datacarpentry/R-ec
 
 If you're an associate editor, you can also push directly to `master` for small fixes. We shall use PRs to `dev` for discussing larger updates, and PR from `dev` to `master` for each release.
 
-If you're an associate editor and you want to render the book locally you need to install `bookdown` and the other dependencies stated in [DESCRIPTION](DESCRIPTION) in particular use `devtools::install_github("bergant/airtabler")`, and [get and store an Airtable API key following their instructions](https://github.com/bergant/airtabler#get-and-store-the-api-key) (if you're not an editor, you don't have access to our Airtable base). Then use `bookdown::render_book('index.Rmd', 'bookdown::gitbook')` and the book will be generated in an `_output` folder.
+If you're an associate editor and you want to render the book locally you need to install `bookdown` and the other dependencies stated in [DESCRIPTION](DESCRIPTION) in particular use `devtools::install_github("bergant/airtabler")`, and [get and store an Airtable API key following their instructions](https://github.com/bergant/airtabler#get-and-store-the-api-key) (if you're not an editor, you don't have access to our Airtable base). Then use `bookdown::render_book('index.Rmd', 'bookdown::gitbook')` and the book will be generated in the `_book` folder; you can open the book on the command line by doing `open _book/index.html`.
 
 # Meta
 

diff --git a/_bookdown.yml b/_bookdown.yml
@@ -7,7 +7,8 @@ rmd_files: ["index.Rmd", "pkg_building.Rmd",
            "softwarereview_intro.Rmd", "softwarereview_policies.Rmd",
            "softwarereview_author.Rmd",
            "softwarereview_reviewer.Rmd", "softwarereview_editor.Rmd",
-           "maintenance_collaboration.Rmd","maintenance_releases.Rmd",
+           "maintenance_collaboration.Rmd",
+           "maintenance_changing_maintainers.Rmd","maintenance_releases.Rmd",
            "maintenance_marketing.Rmd", "maintenance_github_grooming.Rmd",
            "maintenance_evolution.Rmd",
            "maintenance_contributing.Rmd", "appendix.Rmd"]

diff --git a/appendix.Rmd b/appendix.Rmd
@@ -2,8 +2,54 @@
 
 # NEWS {#booknews}
 
+## dev
+
+* 2019-10-03, include in the approval template that maintainers should include link to the docs.ropensci.org/pkg site (ropensci/dev_guide#191)
+
+* 2019-09-26, add instructions for handling editors to nominate packages for blog posts (ropensci/dev_guide#180)
+
+* 2019-09-26, add chapter on changing package maintainers (ropensci/dev_guide#128) (ropensci/dev_guide#194)
+
+* 2019-09-26, update Slack room to use for editors (ropensci/dev_guide#193)
+
+* 2019-09-11, update instructions in README for rendering the book locally (ropensci/dev_guide#192)
+
+* 2019-08-05, update JOSS submission instructions (ropensci/dev_guide#187)
+
+* 2019-07-22, break "reproducibility" category in policies into component parts. (ropensci/software-review-meta#81)
+
+* 2019-06-18, add link to rOpenSci community call "Security for R" to security chapter.
+
+* 2019-06-17, fix formatting of Appendices B-D in the pdf version of the book (bug report by [`@IndrajeetPatil`](https://github.com/IndrajeetPatil), #179)
+
+* 2019-06-17, add suggestion to use R Markdown hunks approach when the README and the vignette share content. (ropensci/dev_guide#161)
+
+* 2019-06-17, add mention of central building of documentation websites.
+
+* 2019-06-13, add explanations of CRAN checks. (ropensci/dev_guide#177)
+
+* 2019-06-13, add mentions of the `rodev` helper functions where relevant.
+
+* 2019-06-13, add recommendation about using `cat` for `str.*()` methods.  RStudio assumes that `str` uses `cat`, if not when loading an R object the `str` prints to the console in RStudio and doesn't show the correct object structure in the properties. ([`@mattfidler`] (https://github.com/mattfidler/) #178)
+
+* 2019-06-12, add more details about git flow.
+
+* 2019-06-12, remove recommendation about `roxygen2` dev version since the latest stable version has what is needed. ([`@bisaloo`](https://github.com/bisaloo/), #165)
+
+* 2019-06-11, add mention of usethis functions for adding testing or vignette infrastructure in the part about dependencies in the package building guide.
+
+* 2019-06-10, use the new URL for the dev guide, https://devguide.ropensci.org/
+
+* 2019-05-27, add more info about the importance of the repo being recognized as a R package by linguist ([`@bisaloo`](https://github.com/bisaloo/), #172)
+
+* 2019-05-22, update all links eligible to HTTPS and update links to the latest versions of Hadley Wickham and Jenny Bryan's books ([`@bisaloo`](https://github.com/bisaloo/), #167)
+
+* 2019-05-15, add book release guidance for editors. (ropensci/dev_guide#152)
+
 ## 0.2.0
 
+* 2019-05-23, add CRAN gotcha: in the Description field of your DESCRIPTION file, enclose URLs in angle brackets.
+
 * 2019-05-13, add more content to the chapter about contributing.
 
 * 2019-05-13, add more precise instructions about blog posts to approval template for editors.
@@ -60,37 +106,71 @@
 # Review template {#reviewtemplate}
 
 ```
-```{r, child="templates/review.md"}
+```{r eval = !knitr::is_latex_output(), child="templates/review.md"}
+```
 ```
+
+```{r eval = knitr::is_latex_output(), child="templates/review.md"}
+
 ```
 
 
 
 # Editor's template {#editortemplate}
 
+
 ```
-```{r, child="templates/editor.md"}
+```{r eval = !knitr::is_latex_output(), child="templates/editor.md"}
 ```
 ```
 
+```{r eval = knitr::is_latex_output(), child="templates/editor.md"}
+
+```
+
 # Review request template {#reviewrequesttemplate}
 
 Editors may make use of the e-mail template below in recruiting reviewers.
 
 ```
-```{r, child="templates/request.md"}
+```{r eval = !knitr::is_latex_output(), child="templates/request.md"}
 ```
 ```
+
+```{r eval = knitr::is_latex_output(), child="templates/request.md"}
+
+```
+
 # Approval comment template {#approvaltemplate}
 
+
 ```
-```{r, child="templates/approved.md"}
+```{r eval = !knitr::is_latex_output(), child="templates/approved.md"}
 ```
 ```
 
+```{r eval = knitr::is_latex_output(), child="templates/approved.md"}
+
+```
+
+
 # NEWS template {#newstemplate}
 
+
+```
+```{r child="templates/news.md"}
+```
+```
+
+
+# Book release guidance {#bookreleaseissue}
+
+
 ```
-```{r, child="templates/news.md"}
+```{r eval = !knitr::is_latex_output(), child="templates/book-release.md"}
 ```
 ```
+
+```{r eval = knitr::is_latex_output(), child="templates/book-release.md"}
+
+```
diff --git a/book.bib b/book.bib
@@ -6,5 +6,5 @@ @Book{xie2015
   year = {2015},
   edition = {2nd},
   note = {ISBN 978-1498716963},
-  url = {http://yihui.name/knitr/},
+  url = {https://yihui.name/knitr/},
 }
diff --git a/index.Rmd b/index.Rmd
@@ -8,7 +8,7 @@ bibliography: [book.bib]
 biblio-style: apalike
 link-citations: yes
 github-repo: ropenscilabs/dev_guide
-url: 'https\://ropensci.github.io/dev_guide/'
+url: 'https\://devguide.ropensci.org/'
 description: "Extended version of the rOpenSci packaging guide. This book is a guide for authors, maintainers, reviewers and editors of rOpenSci. The first section of the book contains our guidelines for creating and testing R packages. The second section is dedicated to rOpenSci's software peer review process: what it is, our policies, and specific guides for authors, editors and reviewers throughout the process. The third and last section features our best practice for nurturing your package once it has been onboarded: how to collaborate with other developers, how to document releases, how to promote your package and how to leverage GitHub as a development platform. The third section also features a chapter for anyone wishing to start contributing to rOpenSci packages."
 cover-image: images/cover.png
 apple-touch-icon: "images/apple-touch-icon.png"
@@ -25,7 +25,7 @@ knitr::include_graphics("images/cover.png")
 
 <a href="https://doi.org/10.5281/zenodo.2553043"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.2553043.svg?branch=master" alt="DOI"></a>
 
-<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/3.0/us/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/3.0/us/88x31.png" /></a><br /> This work is licensed under [a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License](http://creativecommons.org/licenses/by-nc-sa/3.0/us/). Refer to [its Zenodo DOI](https://doi.org/10.5281/zenodo.2553043) to cite it.
+<a rel="license" href="https://creativecommons.org/licenses/by-nc-sa/3.0/us/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/3.0/us/88x31.png" /></a><br /> This work is licensed under [a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License](https://creativecommons.org/licenses/by-nc-sa/3.0/us/). Refer to [its Zenodo DOI](https://doi.org/10.5281/zenodo.2553043) to cite it.
 
 # Preface {-}
 
@@ -45,4 +45,5 @@ This book is a living document. You can view updates to our best practices and p
 
 _If you want to contribute to this book (suggestions, corrections) please refer to [the GitHub repository](https://github.com/ropensci/dev_guide) in particular [the contributing guidelines](https://github.com/ropensci/dev_guide#contributing). Thanks!_
 
-_We are thankful for all authors, reviewers and guest editors for helping us improve the system and this guide over the years. Thanks also to the following persons who made contributions to this guide and its previous incarnations: [Katrin Leinweber](https://github.com/katrinleinweber), [John Baumgartner](https://github.com/johnbaums), [François Michonneau](https://github.com/fmichonneau), [Christophe Dervieux](https://github.com/cderv), [Lorenzo Busetto](https://github.com/lbusett), [Ben Marwick](https://github.com/benmarwick), [Nicholas Horton](https://github.com/nicholasjhorton), [Chris Kennedy](https://github.com/ck37), [Mark Padgham](https://github.com/mpadge), [Jeroen Ooms](https://github.com/jeroen), [Sean Hughes](https://github.com/seaaan), [Jan Gorecki](https://github.com/jangorecki), [Joseph Stachelek](https://github.com/jsta), [Dean Attali](https://github.com/daattali), [Julia Gustavsen](https://github.com/jooolia), [Nicholas Tierney](https://github.com/njtierney), [Rich FitzJohn](https://github.com/richfitz), [Tiffany Timbers](https://github.com/ttimbers), [Hilmar Lapp](https://github.com/hlapp), [Miles McBain](https://github.com/milesmcbain), [Bryce Mecum](https://github.com/amoeba), [Jonathan Carroll](https://github.com/jonocarroll/), [Carl Boettiger](https://github.com/cboettig/), [Florian Privé](https://github.com/privefl), [Stefanie Butland](https://github.com/stefaniebutland), [Daniel Possenriede](https://github.com/dpprdan/), [Hadley Wickham](https://github.com/hadley/). Please tell us if we forgot to acknowledge your contribution!_
+_We are thankful for all authors, reviewers and guest editors for helping us improve the system and this guide over the years. Thanks also to the following persons who made contributions to this guide and its previous incarnations: [Katrin Leinweber](https://github.com/katrinleinweber), [John Baumgartner](https://github.com/johnbaums), [François Michonneau](https://github.com/fmichonneau), [Christophe Dervieux](https://github.com/cderv), [Lorenzo Busetto](https://github.com/lbusett), [Ben Marwick](https://github.com/benmarwick), [Nicholas Horton](https://github.com/nicholasjhorton), [Chris Kennedy](https://github.com/ck37), [Mark Padgham](https://github.com/mpadge), [Jeroen Ooms](https://github.com/jeroen), [Sean Hughes](https://github.com/seaaan), [Jan Gorecki](https://github.com/jangorecki), [Joseph Stachelek](https://github.com/jsta), [Dean Attali](https://github.com/daattali), [Julia Gustavsen](https://github.com/jooolia), [Nicholas Tierney](https://github.com/njtierney), [Rich FitzJohn](https://github.com/richfitz), [Tiffany Timbers](https://github.com/ttimbers), [Hilmar Lapp](https://github.com/hlapp), [Miles McBain](https://github.com/milesmcbain), [Bryce Mecum](https://github.com/amoeba), [Jonathan Carroll](https://github.com/jonocarroll/), [Carl Boettiger](https://github.com/cboettig/), [Florian Privé](https://github.com/privefl), [Stefanie Butland](https://github.com/stefaniebutland), [Daniel Possenriede](https://github.com/dpprdan/), [Hadley Wickham](https://github.com/hadley/), [Hugo Gruson](https://github.com/bisaloo/), [Mauro Lepore](https://github.com/maurolepore/). [Matthew Fidler](https://github.com/mattfidler) Please tell us if we forgot to acknowledge your contribution!_
+
diff --git a/inst/WORDLIST b/inst/WORDLIST
@@ -137,7 +137,7 @@ rOpenSci
 ropenscilabs
 rOpenSci's
 rotl
-roxygen
+roxygen2
 rrlite
 RSE
 rstats
@@ -216,3 +216,25 @@ whyreview
 whysubmit
 WIP
 zenodo
+usethis
+tidync
+textreuse
+StackOverflow
+RStudio
+Gruson
+navbar
+RefManageR
+roxygen
+knitr
+bibliometric
+bibliometrics
+bookrelease
+cranchecks
+CVs
+docsropensci
+pkgdown
+Fidler
+Lepore
+shippable
+RMIT
+rdata
diff --git a/maintenance_changing_maintainers.Rmd b/maintenance_changing_maintainers.Rmd
@@ -0,0 +1,59 @@
+# Changing package maintainers {#changing-maintainers}
+
+```{block, type='summaryblock'}
+This chapter presents our guidance for taking over maintenance of a package.
+```
+
+## Do you want to give up maintenance of your package?
+
+We have a call for contributors section in our newsletter that comes out every two weeks. The section is called _Call For Contributors_. In that section we highlight packages looking for new maintainers. If you are looking to leave the role of maintainer of your package, get in touch with us and we can highlight your package in our newsletter. We've been very successful thus far, finding new maintainers for six out of six packages.
+
+## Do you want to take over maintenance of a package?
+
+We have a call for contributors section in our newsletter that comes out every two weeks. The section is called _Call For Contributors_. In that section we highlight packages looking for new maintainers. If you are not subscribed to the newsletter already, it's a good idea to subscribe to get notified when there's a package looking for a new maintainer.
+
+## Taking over maintenance of a package
+
+* Add yourself as the new maintainer in the DESCRIPTION file, with `role = c("aut", "cre")`, and make the former maintainer `aut` only.
+* Make sure to change maintainer to your name anywhere else in the package, while retaining the former maintainer as an author (e.g, package level manual file, CONTRIBUTING.md, CITATION, etc.)
+* The [Collaboration Guide](#collaboration) has guidance about adding new maintainers and collaborators
+* Packages that have been archived or [orphaned][] on CRAN don’t need permission of the previous maintainer to be taken over on CRAN. In these cases do get in touch with us so we can offer any help as needed.
+* If the package has not been archived by CRAN and there is a maintainer change, have the old maintainer email CRAN and put in writing who the new maintainer is. Make sure to mention that email about the maintainer change when you submit the first new version to CRAN. If the old maintainer is unreachable or will not send this email get in touch with rOpenSci staff.
+* If the previous maintainer is reachable, scheduling a meeting will help you get the "lay of the land"
+
+### FAQ for new maintainers
+
+* There are a few unresolved issues from the package that I don’t know how to fix. Whom may I ask for help?
+
+  It depends; here's what to do in different scenarios:
+
+    - if the old maintainer can be contacted: reach out to them, and ask for help
+    - rOpenSci slack: good for getting help on specific or general problems, the #general room is where many ask questions
+    - rOpenSci discussion forum: this forum is a good option, feel free to ask any questions here
+    - rOpenSci staff: feel free to get in touch with one of us via slack/email/pinging us on GitHub issues, we'll be happy to help
+    - of course there's general R help too if that suits your needs: StackOverflow, Twitter #rstats, etc.
+
+* How much can/should you change in the package?
+
+  For general help on changing code in a package, see the [Package evolution](#evolution)
+  section. 
+
+  When thinking though this, there are many considerations.
+
+  How much time do you have to spend on the package? If you have very limited time, it'd be best to focus on the most critical tasks, whatever those are for the package in question. If you have ample amount of time, your goals can be larger in scope.
+
+  How mature is the package? If the package is mature, many people likely have code that depends on the package's API (i.e., the exported functions, and their parameters). In addition, if there are packages that depend on your package on CRAN, then you need to check that whatever changes you make don't break those packages. The more mature the package is, the more careful you need to be about making changes, especially with the names of exported functions, their parameters, and the exact structure of what exported functions return. Changes can be more easily made that only affect internals of the package.
+
+## Tasks for rOpenSci staff
+
+As an organization, rOpenSci is interested in making sure packages in our suite are available as long as they are useful to the community. As maintainers need to move on, we will in most cases try to get a new maintainer for each package. To these ends, the following tasks are the responsibility of rOpenSci staff.
+
+* If a repository hasn’t seen any activity (commits, issues, pull requests) in quite a long time it may simply be a mature package with little need for changes/etc., so take this into account.
+* Current maintainer has not responded to issues/pull requests in many months, via any of emails, GitHub issues, or Slack messages:
+  * Make contact and see what the situation is. They may say they’d like to step down as maintainer, in which case look for a new maintainer
+* Current maintainer is completely missing/not responding
+  * If this happens we will try to contact the maintainer for up to one month. However, if updating the package is urgent, we may use our admin access to make changes on their behalf.
+* Put a call out in the “Call for Contributors” section of the rOpenSci newsletter for a new maintainer - get in touch with Scott for this or open an issue in the [newsletter repo](https://github.com/ropensci/biweekly/)
+
+
+[orphaned]: https://cran.r-project.org/src/contrib/Orphaned/README