+## Reviewer Response
+
+
+#### Final approval (post-review)
+
+- [ ] **The author has responded to my review and made changes to my satisfaction. I recommend approving this package.**
+
+<!--Please update the estimate below.-->
+
+Estimated hours spent reviewing:2024-01-09, update roxygen2 wording (@vincentvanhees, #792).
2023-12-15, update roxygen2 advice, mainly linking to roxygen2 website (#750).
2023-09-15, add suggestions for API packages (#496).
Translation to Spanish!
2023-07-17, Update Aims and Scope to include translation packages, remove experimental text-processing categories, and provide clarifications around API wrappers
2023-05-04, Added link to Bioconductor book (#663, @llrs).
2023-04-26, Changed suggested lifecycle stage in authors guide (#661, @bart1).
2023-04-25, changed the COI section to use parallel construction (#659, @eliocamp).
2022-07-04, Add resources around GitHub workflows (#479, @maurolepore).
2023-02-14, update instructions for CITATION to reflect new CRAN policies (#604, #609).
2023-02-14, add package maintainer cheatsheet (#608).
2023-01-25, add Mastodon as social media (#592, by @yabellini).
2023-01-25, add Mastodon as social media (#592, by @yabellini).
2023-01-20, fix small formating error (#590 by @eliocamp).
2022-11-22, mention shinytest2 near shinytest.
2022-09-20, add editor instruction to add “stats” label to stats submissions
2022-09-20, fixed link to reviewer approval template (#548), and rendering of editor’s template (#547)
2022-08-23, add recommendation to document argument default (@Bisaloo, #501)
2022-08-06, fix link to R Packages book (#498)
2022-07-21, mention GitHub Discussions and GitHub issue templates. (#482)
2022-07-21, highlight values for reviewing in more places (#481)
2022-07-20, Explanation of package submission via non-default branches (#485), added @s3alfisc to contributor list.
2022-07-20, add how to volunteer as a reviewer (#457).
2022-06-23, Expanded explanation of Codecov, added @ewallace to contributor list (#484)
2022-06-03, Remove former references to now-archived “rodev” package
2022-05-30, Advise that reviewers can also directly call @ropensci-review-bot check package
2022-05-27, Add Mark Padgham to list of authors
2022-05-27, Add devguider::prerelease_checklist item to pre-release template (#463)
2022-05-13, Align version number in DESCRIPTION file with actual version (#443)
2022-05-13, Update guidelines for CONTRIBUTING.md (#366, #462)
2022-05-09, Add section on authorship of included code, thanks to @KlausVigo (#388).
2022-05-09, Remove mention of ‘rev’ role requiring R v3.5
2022-05-05, Move all scripts from local inst directory to ropensci-org/devguider pkg.
2022-05-03, Update package archiving guidance to reduce README to minimal form.
2022-04-29, Advise that authors can directly call @ropensci-review-bot check package.
2022-04-29, Describe pkgcheck-action in CI section.
2022-04-29, Update scope in policies section to include statistical software.
2022-04-29, Add prelease.R script to open pre-release GitHub issue & ref in appendix.
2022-04-26, Add GitHub 2FA recommendation to package security.
2022-03-29, Remove references to Stef Butland, former community manager.
2022-03-28, Add comments on submission planning about time commitment.
2022-03-24, Remove approval comment template (coz it’s automatically generated by the bot now).
2022-03-21, rephrase CITATION guidance to make it less strict. Also mentions CITATION.cff and the cffr package.
2022-03-08, add links to blogs related to package development (#389).
2022-02-17, update redirect instructions (@peterdesmet, #387).
2022-02-14, link to Michael Lynch’s post Why Good Developers Write Bad Unit Tests.
2022-02-14, mention more packages for testing like dittodb, vcr, httptest, httptest2, webfakes.
2022-01-10, make review templates R Markdown files (@Bisaloo, #340).
2022-01-14, update guidance on CI services (#377)
2022-01-11, update guidance around branches, with resources suggested by @ha0ye and @statnmap.
2022-01-10, divide author’s guide into sub-sections, and add extra info including pkgcheck.
2021-11-30, adds links to examples of reviews, especially tough but constructive ones (with help from @noamross, @mpadge, #363).
2021-11-19, add recommended spatial packages to scaffolding section (software-review-meta#47)
2021-11-18, update advice on grouping functions for pkgdown output (#361)
2021-11-04, add mentions of stat software review to software review intro and to the first book page (#342).
2021-11-04, mention pkgcheck in the author guide (@mpadge, #343).
2021-11-04, add editors’ responsibilities including Editor etiquette for commenting on packages on which you aren’t handling/reviewing (@jhollist, #354).
2021-11-04, give precise examples of tools for installation instructions (remotes, pak, R-universe).
2021-11-04, add more bot guidance (less work for editors).
2021-10-07, add guidance for editorial management (recruiting, inviting, onboarding, offboarding editors).
2021-09-14, add a requirement that there is at least one HTML vignette.
2021-09-03, add some recommendations around git. (@annakrystalli, #341)
2021-07-14, clarify the categories data extraction and munging by adding examples. (@noamross, #337)
2021-05-20, add guidance around setting up your package to foster a community, inspired by the recent rOpenSci community call. (with help from @Bisaloo, #289, #308)
2021-04-27, no longer ask reviewers to ask covr as it’ll be done by automatic tools, but ask them to pay attention to tests skipped.
2021-04-02, add citation guidance.
2021-04-02, stop asking reviewers to run goodpractice as this is part of editorial checks.
2021-03-23, launched a new form for reviewer volunteering.
2021-02-24, add guidance around the use of @ropensci-review-bot.
2021-02-04, add guidance to enforce package versioning and tracking of changes through review (@annakrystalli, #305)
2021-01-25, add a translation of the review template in Spanish (@Fvd, @maurolepore, #303)
2021-01-25, the book has now better citation guidance in case you want to cite this very guide (@Bisaloo, #304).
2021-01-12, add some more guidance on escaping examples (#290).
2021-01-12, mention the lifecycle package in the chapter about package evolution (#287).
2021-01-12, require overlap information is put in documentation (#292).
2021-01-12, start using the bookdown::bs4_book() template.
2021-01-12, add a sentence about whether it is acceptable to push a new version of a package to CRAN within two weeks of the most recent version if you have just been made aware of, and fixed, a major bug (@sckott, #283)
2021-01-12, mention the HTTP testing in R book.
2021-01-12, mention testthat snapshot tests.
2021-01-12, remove mentions of Travis CI and link to Jeroen Ooms’ blog post about moving away from Travis.
2021-01-12, update the package curation policy: mention a possible exception for legacy packages that are vital parts of the R and/or rOpenSci package ecosystem which are actively monitored by staff. (@noamross, #293)
2020-10-08, add help about link checking (@sckott, #281)
2020-10-08, update JOSS instructions (@karthik, #276)
2020-10-05, add links to licence resources (@annakrystalli, #279)
2020-10-05, update information about the contributing guide (@stefaniebutland, #280)
2020-09-11, make reviewer approval a separate template (@bisaloo, #264)
2020-09-22, add package curation policy (@noamross, #263)
2020-09-11, add more guidance and requirements for docs at submission (@annakrystalli, #261)
2020-09-14, add more guidance on describing data source in DESCRIPTION (@mpadge, #260)
2020-09-14, add more guidance about tests of deprecated functions (@sckott, #213)
2020-09-11, update the CI guidance (@bisaloo, @mcguinlu, #269)
2020-09-11, improve the redirect guidance (@jeroen, @mcguinlu, #269)
2020-04-02, give less confusing code of conduct guidance: the reviewed packages’ COC is rOpenSci COC (@Bisaloo, @cboettig, #240)
2020-03-27, add section on Ethics, Data Privacy and Human Subjects Research to Policies chapter
2020-03-12, mention GitHub Actions as a CI provider.
2020-02-24, add guide for inviting a guest editor.
2020-02-14, add mentions of the ropensci-books GitHub organisation and associated subdomain.
2020-02-10, add field and laboratory reproducibility tools as a category in scope.
2020-02-10, add more guidance about secrets and package development in the security chapter.
2020-02-06, add guidance about Bioconductor dependencies (#246).
2020-02-06, add package logo guidance (#217).
2020-02-06, add one CRAN gotcha: single quoting software names(#245, @aaronwolen)
2020-02-06, improve guidance regarding the replacement of “older” pkgdown website links and source (#241, @cboettig)
2020-02-06, rephrase the EiC role (#244).
2020-02-06, remove the recommendation to add rOpenSci footer (https://github.com/ropensci/software-review-meta/issues/79).
2020-02-06, remove the recommendation to add a review mention to DESCRIPTION but recommends mentioning the package version when reviewers are added as “rev” authors.
2020-01-30, slightly changes the advice on documentation re-use: add a con; mention @includeRmd and @example; correct the location of Rmd fragments (#230).
2020-01-30, add more guidance for the editor in charge of a dev guide release (#196, #205).
2020-01-22, add guidance in the editor guide about not transferred repositories.
2020-01-22, clarify forum guidance (for use cases and in general).
2020-01-22, mention an approach for pre-computing vignettes so that the pkgdown website might get build on rOpenSci docs server.
2020-01-22, document the use of mathjax with rotemplate (@Bisaloo, #199).
2020-01-20, add guidance for off-thread interaction and COIs (@noamross, #197).
2020-01-20, add advice on specifying dependency minimum versions (@karthik, @annakrystalli, #185).
2020-01-09, start using GitHub actions instead of Travis for deployment.
-2019-12-11, add note in Documentation sub-section of Packaging Guide section about referencing the new R6 support in roxygen2 (ropensci/dev_guide#189)
2019-12-11, add new CRAN gotcha about having ‘in R’ or ‘with R’ in your package title (@bisaloo, ropensci/dev_guide#221)
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, #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, #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, #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, #167)
2019-05-15, add book release guidance for editors. (ropensci/dev_guide#152)
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.
2019-05-13, add policies allowing using either <- or = within a package as long as the whole package is consistent.
2019-05-13, add request for people to tell us if they use our standards/checklists when reviewing software elsewhere.
2019-04-29, add requirement and advice on testing packages using devel and oldrel R versions on Travis.
2019-04-23, add a sentence about why being generous with attributions and more info about ctb vs aut.
2019-04-23, add link to Daniel Nüst’s notes about migration from XML to xml2.
2019-04-22, add use of rOpenSci forum to maintenance section.
2019-04-22, ask reviewer for consent to be added to DESCRIPTION in review template.
2019-04-22, use a darker blue for links (feedback by @kwstat, #138).
2019-04-22, add book cover.
2019-04-08, improve formatting and link text in README (@katrinleinweber, #137)
2019-03-25, add favicon (@wlandau, #136).
2019-03-21, improve Travis CI guidance, including link to examples. (@mpadge, #135)
2019-02-07, simplify code examples in Package Evolution section (maintenance_evolution.Rmd file) (@hadley, #129).
2019-02-07, added a PDF file to export (request by @IndrajeetPatil, #131).
2019-01-23, add details about requirements for packages running on all major platforms and added new section to package categories.
2019-01-22, add details to the guide for authors about the development stage at which to submit a package.
2018-12-21, inclusion of an explicit policy for conflict of interest (for reviewers and editors).
2018-12-18, added more guidance for editor on how to look for reviewers.
2018-12-04, onboarding was renamed Software Peer Review.
NEWS.md file to track changes to the book.Editors preparing for a release can run the prelease.R script in the inst directory of this repository to automatically open a GitHub issue with checkpoints for all current issues assigned to the upcoming release milestone, along with the following checklist. Before running the script, please manually check the assignment of issues to the milestone. This should be run one month prior to planned release.
+## Release book version <insert version>
+
+### Repo maintenance between releases
+
+- [ ] Look at the issue tracker for [the dev guide](https://github.com/ropensci/dev_guide/issues) and for [software review meta](https://github.com/ropensci/software-review-meta/issues) for changes still to be made in the dev guide. Assign dev guide issues to milestones corresponding to versions, either the next one or the one after that, e.g. [version 0.3.0](https://github.com/ropensci/dev_guide/milestone/2). Encourage PRs, have them reviewed.
+
+### 1 month prior to release
+
+- [ ] Remind editors to open issues/PRs for items they want to see in the next version.
+
+- [ ] Run [the `devguide_prerelease()` function](https://github.com/ropensci-org/devguider) from the `devguider` package.
+
+- [ ] Ask editors for any feedback you need from them before release.
+
+- [ ] For each contribution/change make sure the NEWS in Appendix.Rmd were updated.
+
+- [ ] Plan a date for release in communication with rOpenSci's Community Manager who will give you a date for publishing a blog post / tech note.
+
+### 2 weeks prior to release
+
+- [ ] Draft a blog post / tech note about the release with enough advance for editors and then Community Manager to review it (2 weeks). [Example](https://github.com/ropensci/roweb3/pull/291), [General blog post instructions](https://blogguide.ropensci.org/), [specific instructions for release posts](#releaseblogpost).
+
+- [ ] Make a PR from the dev branch to the master branch, ping editors on GitHub and Slack. Mention the blog post draft in a comment on this PR.
+
+### Release
+
+- [ ] Check URLs using [the `devguide_urls()` function from the {devguider} package](https://github.com/ropensci-org/devguider)
+
+- [ ] Check spelling using [the `devguide_spelling()` function from the {devguider} package](https://github.com/ropensci-org/devguider). Update the [WORDLIST](https://github.com/ropensci/dev_guide/blob/master/inst/WORDLIST) as necessary.
+
+- [ ] Squash and merge the PR from dev to master.
+
+- [ ] GitHub release, check Zenodo release.
+
+- [ ] Re-build (for Zenodo metadata update in the book) or wait for daily build
+
+- [ ] Re-create the dev branch
+
+- [ ] Finish your blog post / tech note PR. Underline the most important aspects to be highlighted in tweets as part of the PR discussion.Note that we clean issue threads by removing extraneous content, so the record of you having asked for bot-help will most often quickly be erased or hidden.
+If you need a quick reminder!
+@ropensci-review-bot help@ropensci-review-bot code of conduct@ropensci-review-bot assign @username as editorSee editorial policy.
+@ropensci-review-bot put on holdDo not forget to first post a comment explaining the decision and thanking the author(s) for their submission.
+@ropensci-review-bot out-of-scopeSee editorial policy.
+@ropensci-review-bot put on holdGenerally only on pre-submission inquiries, or when authors otherwise indicate that package has substantially changed.
+@ropensci-review-bot check packageGenerally only on pre-submission inquiries, or when authors otherwise indicate that package has substantially changed.
+@ropensci-review-bot check srrTowards the end of the submission process.
+@ropensci-review-bot check readme@ropensci-review-bot seeking reviewers@ropensci-review-bot assign @username as revieweror
+@ropensci-review-bot add @username as reviewer@ropensci-review-bot remove @username from reviewers@ropensci-review-bot set due date for @username to YYYY-MM-DD@ropensci-review-bot submit review <review-url> time <time in hours>@ropensci-review-bot approve <package-name>
+### Editor checks:
+
+- [ ] **Documentation**: The package has sufficient documentation available online (README, pkgdown docs) to allow for an assessment of functionality and scope without installing the package. In particular,
+ - [ ] Is the case for the package well made?
+ - [ ] Is the reference index page clear (grouped by topic if necessary)?
+ - [ ] Are vignettes readable, sufficiently detailed and not just perfunctory?
+- [ ] **Fit**: The package meets criteria for [fit](https://devguide.ropensci.org/policies.html#package-categories) and [overlap](https://devguide.ropensci.org/policies.html#overlap).
+- [ ] **Installation instructions:** Are installation instructions clear enough for human users?
+- [ ] **Tests**: If the package has some interactivity / HTTP / plot production etc. are the tests using [state-of-the-art tooling](https://devguide.ropensci.org/building.html#testing)?
+- [ ] **Contributing information**: Is the documentation for contribution clear enough e.g. tokens for tests, playgrounds?
+- [ ] **License:** The package has a CRAN or OSI accepted license.
+- [ ] **Project management**: Are the issue and PR trackers in a good shape, e.g. are there outstanding bugs, is it clear when feature requests are meant to be tackled?
+---
+
+#### Editor comments
+
+---
+## Respuesta de quien hizo la revisión
+
+#### Aprobación final (posterior a la revisión)
+
+- [ ] **Quien mantiene el paquete ha respondido a mi revisión y ha realizado cambios satisfactorios. Recomiendo aprobar este paquete.**
+
+<!-- Por favor, actualiza la estimación de horas a continuación.-->
+
+Estimación de horas dedicadas a la revisión:
+2024-01-09, update roxygen2 wording (@vincentvanhees, #792).
2023-12-15, update roxygen2 advice, mainly linking to roxygen2 website (#750).
2023-09-15, add suggestions for API packages (#496).
Translation to Spanish!
2023-07-17, Update Aims and Scope to include translation packages, remove experimental text-processing categories, and provide clarifications around API wrappers
2023-05-04, Added link to Bioconductor book (#663, @llrs).
2023-04-26, Changed suggested lifecycle stage in authors guide (#661, @bart1).
2023-04-25, changed the COI section to use parallel construction (#659, @eliocamp).
2022-07-04, Add resources around GitHub workflows (#479, @maurolepore).
2023-02-14, update instructions for CITATION to reflect new CRAN policies (#604, #609).
2023-02-14, add package maintainer cheatsheet (#608).
2023-01-25, add Mastodon as social media (#592, by @yabellini).
2023-01-25, add Mastodon as social media (#592, by @yabellini).
2023-01-20, fix small formating error (#590 by @eliocamp).
2022-11-22, mention shinytest2 near shinytest.
2022-09-20, add editor instruction to add “stats” label to stats submissions
2022-09-20, fixed link to reviewer approval template (#548), and rendering of editor’s template (#547)
2022-08-23, add recommendation to document argument default (@Bisaloo, #501)
2022-08-06, fix link to R Packages book (#498)
2022-07-21, mention GitHub Discussions and GitHub issue templates. (#482)
2022-07-21, highlight values for reviewing in more places (#481)
2022-07-20, Explanation of package submission via non-default branches (#485), added @s3alfisc to contributor list.
2022-07-20, add how to volunteer as a reviewer (#457).
2022-06-23, Expanded explanation of Codecov, added @ewallace to contributor list (#484)
2022-06-03, Remove former references to now-archived “rodev” package
2022-05-30, Advise that reviewers can also directly call @ropensci-review-bot check package
2022-05-27, Add Mark Padgham to list of authors
2022-05-27, Add devguider::prerelease_checklist item to pre-release template (#463)
2022-05-13, Align version number in DESCRIPTION file with actual version (#443)
2022-05-13, Update guidelines for CONTRIBUTING.md (#366, #462)
2022-05-09, Add section on authorship of included code, thanks to @KlausVigo (#388).
2022-05-09, Remove mention of ‘rev’ role requiring R v3.5
2022-05-05, Move all scripts from local inst directory to ropensci-org/devguider pkg.
2022-05-03, Update package archiving guidance to reduce README to minimal form.
2022-04-29, Advise that authors can directly call @ropensci-review-bot check package.
2022-04-29, Describe pkgcheck-action in CI section.
2022-04-29, Update scope in policies section to include statistical software.
2022-04-29, Add prelease.R script to open pre-release GitHub issue & ref in appendix.
2022-04-26, Add GitHub 2FA recommendation to package security.
2022-03-29, Remove references to Stef Butland, former community manager.
2022-03-28, Add comments on submission planning about time commitment.
2022-03-24, Remove approval comment template (coz it’s automatically generated by the bot now).
2022-03-21, rephrase CITATION guidance to make it less strict. Also mentions CITATION.cff and the cffr package.
2022-03-08, add links to blogs related to package development (#389).
2022-02-17, update redirect instructions (@peterdesmet, #387).
2022-02-14, link to Michael Lynch’s post Why Good Developers Write Bad Unit Tests.
2022-02-14, mention more packages for testing like dittodb, vcr, httptest, httptest2, webfakes.
2022-01-10, make review templates R Markdown files (@Bisaloo, #340).
2022-01-14, update guidance on CI services (#377)
2022-01-11, update guidance around branches, with resources suggested by @ha0ye and @statnmap.
2022-01-10, divide author’s guide into sub-sections, and add extra info including pkgcheck.
2021-11-30, adds links to examples of reviews, especially tough but constructive ones (with help from @noamross, @mpadge, #363).
2021-11-19, add recommended spatial packages to scaffolding section (software-review-meta#47)
2021-11-18, update advice on grouping functions for pkgdown output (#361)
2021-11-04, add mentions of stat software review to software review intro and to the first book page (#342).
2021-11-04, mention pkgcheck in the author guide (@mpadge, #343).
2021-11-04, add editors’ responsibilities including Editor etiquette for commenting on packages on which you aren’t handling/reviewing (@jhollist, #354).
2021-11-04, give precise examples of tools for installation instructions (remotes, pak, R-universe).
2021-11-04, add more bot guidance (less work for editors).
2021-10-07, add guidance for editorial management (recruiting, inviting, onboarding, offboarding editors).
2021-09-14, add a requirement that there is at least one HTML vignette.
2021-09-03, add some recommendations around git. (@annakrystalli, #341)
2021-07-14, clarify the categories data extraction and munging by adding examples. (@noamross, #337)
2021-05-20, add guidance around setting up your package to foster a community, inspired by the recent rOpenSci community call. (with help from @Bisaloo, #289, #308)
2021-04-27, no longer ask reviewers to ask covr as it’ll be done by automatic tools, but ask them to pay attention to tests skipped.
2021-04-02, add citation guidance.
2021-04-02, stop asking reviewers to run goodpractice as this is part of editorial checks.
2021-03-23, launched a new form for reviewer volunteering.
2021-02-24, add guidance around the use of @ropensci-review-bot.
2021-02-04, add guidance to enforce package versioning and tracking of changes through review (@annakrystalli, #305)
2021-01-25, add a translation of the review template in Spanish (@Fvd, @maurolepore, #303)
2021-01-25, the book has now better citation guidance in case you want to cite this very guide (@Bisaloo, #304).
2021-01-12, add some more guidance on escaping examples (#290).
2021-01-12, mention the lifecycle package in the chapter about package evolution (#287).
2021-01-12, require overlap information is put in documentation (#292).
2021-01-12, start using the bookdown::bs4_book() template.
2021-01-12, add a sentence about whether it is acceptable to push a new version of a package to CRAN within two weeks of the most recent version if you have just been made aware of, and fixed, a major bug (@sckott, #283)
2021-01-12, mention the HTTP testing in R book.
2021-01-12, mention testthat snapshot tests.
2021-01-12, remove mentions of Travis CI and link to Jeroen Ooms’ blog post about moving away from Travis.
2021-01-12, update the package curation policy: mention a possible exception for legacy packages that are vital parts of the R and/or rOpenSci package ecosystem which are actively monitored by staff. (@noamross, #293)
2020-10-08, add help about link checking (@sckott, #281)
2020-10-08, update JOSS instructions (@karthik, #276)
2020-10-05, add links to licence resources (@annakrystalli, #279)
2020-10-05, update information about the contributing guide (@stefaniebutland, #280)
2020-09-11, make reviewer approval a separate template (@bisaloo, #264)
2020-09-22, add package curation policy (@noamross, #263)
2020-09-11, add more guidance and requirements for docs at submission (@annakrystalli, #261)
2020-09-14, add more guidance on describing data source in DESCRIPTION (@mpadge, #260)
2020-09-14, add more guidance about tests of deprecated functions (@sckott, #213)
2020-09-11, update the CI guidance (@bisaloo, @mcguinlu, #269)
2020-09-11, improve the redirect guidance (@jeroen, @mcguinlu, #269)
2020-04-02, give less confusing code of conduct guidance: the reviewed packages’ COC is rOpenSci COC (@Bisaloo, @cboettig, #240)
2020-03-27, add section on Ethics, Data Privacy and Human Subjects Research to Policies chapter
2020-03-12, mention GitHub Actions as a CI provider.
2020-02-24, add guide for inviting a guest editor.
2020-02-14, add mentions of the ropensci-books GitHub organisation and associated subdomain.
2020-02-10, add field and laboratory reproducibility tools as a category in scope.
2020-02-10, add more guidance about secrets and package development in the security chapter.
2020-02-06, add guidance about Bioconductor dependencies (#246).
2020-02-06, add package logo guidance (#217).
2020-02-06, add one CRAN gotcha: single quoting software names(#245, @aaronwolen)
2020-02-06, improve guidance regarding the replacement of “older” pkgdown website links and source (#241, @cboettig)
2020-02-06, rephrase the EiC role (#244).
2020-02-06, remove the recommendation to add rOpenSci footer (https://github.com/ropensci/software-review-meta/issues/79).
2020-02-06, remove the recommendation to add a review mention to DESCRIPTION but recommends mentioning the package version when reviewers are added as “rev” authors.
2020-01-30, slightly changes the advice on documentation re-use: add a con; mention @includeRmd and @example; correct the location of Rmd fragments (#230).
2020-01-30, add more guidance for the editor in charge of a dev guide release (#196, #205).
2020-01-22, add guidance in the editor guide about not transferred repositories.
2020-01-22, clarify forum guidance (for use cases and in general).
2020-01-22, mention an approach for pre-computing vignettes so that the pkgdown website might get build on rOpenSci docs server.
2020-01-22, document the use of mathjax with rotemplate (@Bisaloo, #199).
2020-01-20, add guidance for off-thread interaction and COIs (@noamross, #197).
2020-01-20, add advice on specifying dependency minimum versions (@karthik, @annakrystalli, #185).
2020-01-09, start using GitHub actions instead of Travis for deployment.
-2019-12-11, add note in Documentation sub-section of Packaging Guide section about referencing the new R6 support in roxygen2 (ropensci/dev_guide#189)
2019-12-11, add new CRAN gotcha about having ‘in R’ or ‘with R’ in your package title (@bisaloo, ropensci/dev_guide#221)
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, #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, #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, #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, #167)
2019-05-15, add book release guidance for editors. (ropensci/dev_guide#152)
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.
2019-05-13, add policies allowing using either <- or = within a package as long as the whole package is consistent.
2019-05-13, add request for people to tell us if they use our standards/checklists when reviewing software elsewhere.
2019-04-29, add requirement and advice on testing packages using devel and oldrel R versions on Travis.
2019-04-23, add a sentence about why being generous with attributions and more info about ctb vs aut.
2019-04-23, add link to Daniel Nüst’s notes about migration from XML to xml2.
2019-04-22, add use of rOpenSci forum to maintenance section.
2019-04-22, ask reviewer for consent to be added to DESCRIPTION in review template.
2019-04-22, use a darker blue for links (feedback by @kwstat, #138).
2019-04-22, add book cover.
2019-04-08, improve formatting and link text in README (@katrinleinweber, #137)
2019-03-25, add favicon (@wlandau, #136).
2019-03-21, improve Travis CI guidance, including link to examples. (@mpadge, #135)
2019-02-07, simplify code examples in Package Evolution section (maintenance_evolution.Rmd file) (@hadley, #129).
2019-02-07, added a PDF file to export (request by @IndrajeetPatil, #131).
2019-01-23, add details about requirements for packages running on all major platforms and added new section to package categories.
2019-01-22, add details to the guide for authors about the development stage at which to submit a package.
2018-12-21, inclusion of an explicit policy for conflict of interest (for reviewers and editors).
2018-12-18, added more guidance for editor on how to look for reviewers.
2018-12-04, onboarding was renamed Software Peer Review.
NEWS.md file to track changes to the book.Antes de realizar una nueva publicación de este libro, se puede ejecutar el script prelease.R que se encuentra en la carpeta inst de este repositorio. Esto va a crear una issue en GitHub con una lista de todas las issues asignadas al milestone de la próxima versión junto con la siguiente lista de tareas. Antes de correr el script, por favor revistar la asignación de issues al milestone. Todo esto debería hacerse un mes antes de la fecha de publicación programada.
+## Publicación del libro, versión <insertar versión>
+
+### Mantenimiento de repositorios entre versiones
+
+- [ ] Mira los *issues* de [la guía de desarrollo](https://github.com/ropensci/dev_guide/issues) y del [meta de revisión del software](https://github.com/ropensci/software-review-meta/issues) para revisar los cambios pendientes en la guía de desarrollo. Asigna los *issues* de la guía de desarrollo a los *milestones* correspondientes a cada versión, ya sea la siguiente o la versión que viene luego de esa, por ejemplo [versión 0.3.0](https://github.com/ropensci/dev_guide/milestone/2). Fomenta la creación de PR y haz que sean revisados.
+
+### 1 mes antes de la publicación
+
+- [ ] Recuerda al equipo de edición que abran *issues* o PRs sobre los temas que quieran incluir en la próxima versión.
+
+- [ ] Ejecuta [la función `devguide_prerelease()`](https://github.com/ropensci-org/devguider) del paquete `devguider`.
+
+- [ ] Pide al equipo de edición cualquier devolución que necesites antes de la publicación.
+
+- [ ] Por cada contribución o cambio, asegúrate de que se hayan actualizado las *NEWS* en Appendix.Rmd.
+
+- [ ] Coordina una fecha para la publicación con quien sea Community Manager de rOpenSci, quien te dará una fecha para publicar un artículo en el blog o nota técnica.
+
+### 2 semanas antes de publicar
+
+- [ ] Redacta un artículo para el blog o nota técnica sobre el lanzamiento con suficiente antelación para que el equipo de edición, y luego quien sea Community Manager puedan revisarlo (2 semanas).
+ [Ejemplo](https://github.com/ropensci/roweb3/pull/291), [Instrucciones generales para artículos de blog](https://blogguide.ropensci.org/), [instrucciones específicas para articulos de lanzamiento](#releaseblogpost).
+
+- [ ] Haz un PR de la *branch* dev a la *branch* master, notifica al equipo de edición en GitHub y Slack.
+ Menciona el borrador del artículo del blog en un comentario en ese PR.
+
+### Publicación
+
+- [ ] Comprueba las URL utilizando [la función `devguide_urls()` del paquete {devguider}](https://github.com/ropensci-org/devguider).
+
+- [ ] Comprueba la ortografía con [la función `devguide_spelling()` del paquete {devguider}](https://github.com/ropensci-org/devguider).
+ Actualiza la [LISTA DE PALABRAS](https://github.com/ropensci/dev_guide/blob/master/inst/WORDLIST) según sea necesario.
+
+- [ ] Unifica los *commits* (*squash*) y haz *merge* del PR de *dev* a *master*.
+
+- [ ] Crea un *release* en GitHub, asegúrate de que se cree un *release* en Zenodo.
+
+- [ ] Re-genera el libro (para actualizar los metadatos de Zenodo en el libro) o espera a la compilación diaria.
+
+- [ ] Vuelve a crear la *branch* dev.
+
+- [ ] Termina el PR de tu artículo para el blog o nota técnica.
+ Indica los aspectos más importantes que deben destacarse en los tweets como parte de la discusión del PR.Ten en cuenta que limpiamos los issues eliminando el contenido superfluo, por lo que la mayoría de las veces el registro de que has pedido ayuda a un bot se borrará u ocultará rápidamente.
+Si necesitas un recordatorio rápido
+@ropensci-review-bot help@ropensci-review-bot code of conduct@ropensci-review-bot assign @username as editorVer política editorial.
+@ropensci-review-bot put on holdNo olvides publicar primero un comentario explicando la decisión y agradeciendo a las personas responsables del paquete su envío.
+@ropensci-review-bot out-of-scopeVer política editorial.
+@ropensci-review-bot put on holdGeneralmente se hace sólo en consultas previas al envío para revisión, o cuando las personas responsables del paquete indican que el paquete ha cambiado sustancialmente.
+@ropensci-review-bot check packageGeneralmente se hace sólo en consultas previas al envío para revisión, o cuando las personas responsables del paquete indican que el paquete ha cambiado sustancialmente.
+@ropensci-review-bot check srrHacia el final del proceso de envío.
+@ropensci-review-bot check readme@ropensci-review-bot seeking reviewers@ropensci-review-bot assign @username as reviewero
+@ropensci-review-bot add @username as reviewer@ropensci-review-bot remove @username from reviewers@ropensci-review-bot set due date for @username to YYYY-MM-DD@ropensci-review-bot submit review <review-url> time <time in hours>@ropensci-review-bot approve <package-name>
+### Quien hace la edición debe comprobar:
+
+- [ ] **Documentación:** El paquete tiene suficiente documentación disponible en línea (*README*, documentación de *pkgdown*) que permita una evaluación de la funcionalidad y el alcance sin instalar el paquete. En concreto,
+ - [ ] ¿Está bien explicada la necesidad del paquete?
+
+ - [ ] ¿La página con el índice de funciones es clara (agrupada por temas si es necesario)?
+
+ - [ ] ¿Las viñetas son legibles, suficientemente detalladas y no superficiales?
+- [ ] **Encaja:** El paquete cumple los criterios para ser incluido en una [categoría](https://devguide.ropensci.org/policies.html#package-categories) y no hay [solapamiento](https://devguide.ropensci.org/policies.html#overlap).
+- [ ] **Instrucciones de instalación:** ¿Las instrucciones de instalación son lo suficientemente claras?
+- [ ] **Tests:** Si el paquete provee herramientas interactivas, usa recursos HTTP, produce gráficos, etc., ¿los *tests* son consistentes con [el estado del arte?](https://devguide.ropensci.org/building.html#testing)?
+- [ ] **Información para contribuir:** ¿La documentación acerca de cómo contribuir es lo suficientemente clara, por ejemplo, los *tokens* para *tests*, espacios para pruebas?
+- [ ] **Licencia:** El paquete tiene una licencia aceptada por CRAN u OSI.
+- [ ] **Gestión del proyecto:** ¿Los *issues* y *pull requests* se encuentran en buen estado? Por ejemplo, ¿hay errores pendientes, está claro cuándo se abordarán los pedidos de nueva funcionalidad?
+---
+
+#### Comentarios de edición
+
+---Guía para autoras/es de paquetes, encargadas/os, revisoras/es y editoras/es en el sistema de revisión por pares de rOpenSci. La primera sección del libro contiene nuestras recomendaciones para crear y probar los paquetes de R. La segunda sección está dedicada al proceso de revisión por pares de software de rOpenSci: qué es, nuestras políticas y guías específicas para orientar a quienes crean, mantienen, revisan y editan a lo largo del proceso. La tercera y última sección presenta nuestras buenas prácticas para hacer crecer su paquete una vez que ha sido incorporado a rOpenSci: cómo colaborar con otras/os desarrolladoras/es, cómo documentar cada versión de tu paquete y cómo aprovechar GitHub como plataforma de desarrollo. La tercera sección también incluye un capítulo para cualquiera que desee comenzar a contribuir a los paquetes de rOpenSci.
+
Esta obra está bajo una Licencia Creative Commons Atribución-NoComercial-CompartirIgual 3.0 Estados Unidos de América. Consulta el DOI de Zenodo de la version original y el DOI de la traducción para saber como citarlas.
Ejemplo:
+rOpenSci editorial team (2024). Paquetes rOpenSci: Desarrollo, mantenimiento y revisión por pares [rOpenSci Packages: Development, Maintenance, and Peer Review] (Traducción al español: Yanina Bellini Saibene, Elio Campitelli, Paola Corrales) Zenodo. https://zenodo.org/doi/10.5281/zenodo.10797248 (Trabajo original publicado en 2024)
+También puedes leer la versión PDF de este libro.
+ + ++Este capítulo presenta nuestra guía para asumir el mantenimiento de un paquete. +
+Nuestro newsletter quincenal tiene una sección de pedidos de colaboración denominada “Call for Contributors” (Pedidos de contribuciones, en inglés). En la misma se destacan paquetes que buscan nuevas personas para encargarse del mantenimiento. Si quieres dejar de mantener tu paquete, contáctanos para que lo incluyamos en esta sección.
+Nuestro newsletter quincenal tiene una sección de pedidos de colaboración denominada Pedidos de contribuciones. En la misma se destacan paquetes que buscan nuevas personas para encargarse del mantenimiento. Si aún lo hiciste, es una buena idea subscribirte al newsletter para recibir notificaciones cuando hay un paquete buscando ayuda.
+role = c("aut", "cre") y cambia el rol de la persona anterior a role = c("aut").Hay algunos issues no resueltos del paquete que no sé cómo arreglar. ¿A quién puedo pedir ayuda?
+Depende; esto es lo que hay que hacer en diferentes situaciones:
+¿Cuánto puedes o debes cambiar en el paquete?
+Para obtener ayuda general sobre cómo cambiar el código de un paquete, consulta la sección Evolución de paquetes.
+Al pensar en esto, hay varias cosas a considerar.
+¿Cuánto tiempo tienes para dedicarle al paquete? Si tu tiempo es muy limitado, lo mejor será que te centres en las tareas más críticas, sean las que sean para el paquete en cuestión. Si tienes mucho tiempo, tus objetivos pueden ser más ambiciosos.
+¿Qué grado de madurez tiene el paquete? Si el paquete es maduro, es probable que mucha gente tenga código que dependa de su API (es decir, las funciones exportadas y sus parámetros). Además, si hay paquetes en CRAN que dependen de tu paquete, entonces tienes que comprobar que cualquier cambio que hagas no rompa esos paquetes. Cuanto más maduro sea el paquete, más cuidado deberás tener a la hora de hacer cambios, especialmente con los nombres de las funciones exportadas, sus parámetros y la estructura exacta de lo que devuelven las funciones exportadas. Es más fácil hacer cambios que sólo afecten a los aspectos internos del paquete.
+Como organización, a rOpenSci le interesa asegurarse de que los paquetes de nuestra suite estén disponibles mientras sean útiles para la comunidad. Si un paquete se queda sin personas que lo mantengan, en la mayoría de los casos intentaremos conseguir nuevas personas que se encarguen del mismo. Para ello, las siguientes tareas son responsabilidad del personal de rOpenSci.
++Un recordatorio de la infraestructura y los canales de contacto para quienes mantienen paquetes de rOpenSci. +
+Si necesitas ayuda (por ejemplo una revisión de un PR o resolver problemas de CI), o asistencia para encontrar personas que ayuden o tomen la responsabilidad de mantener el paquete, o si necesitas que retiremos tu paquete, menciónanos en GitHub con @ropensci/admin o envía un correo electrónico a info@ropensci.org.
También puedes utilizar el canal de slack #package-maintenance.
+¡Nunca dudes en pedir ayuda!
+Deberías tener acceso “admin” al repositorio GitHub de tu paquete. Si no es el caso (por ejemplo, porqué falló el proceso automatizado o porque perdiste acceso después de haber tenido que desactivar temporalmente la autenticación de dos factores), por favor contáctanos enviando un correo electrónico a info@ropensci.org.
Si tienes una pregunta o un pedido sobre GitHub, como por ejemplo, añadir una nueva persona que colabora a la organización GitHub, puedes utilizar un canal público en el Slack de rOpenSci o mencionar a @ropensci/admin en GitHub.
Consulta rOpenSci docs.
+Quienes mantienen o desarrollan paquetes de rOpenSci deberían tener acceso al Slack de rOpenSci. Si no recibiste la invitación o no la aceptaste a tiempo, o si quieres que alguien que ahora contribuye regularmente a tu paquete reciba una invitación, por favor envía un correo electrónico a info@ropensci.org indicando el correo electrónico de la persona que quiere unirse al espacio de trabajo.
El canal #package-maintenance es relevante para hacer y responder consultas, así como para dar y recibir apoyo emocional cuando sea necesario.
+Consulta nuestra guía de blog.
+Si etiquetas issues con “help wanted” (“se busca ayuda”, en inglés), las difundiremos en la comunidad.
+Puedes notificar ejemplos y casos de uso de tu paquete o animar a las personas que usan tu paquete a compartirlos en nuestro foro, para que sean publicados en nuestro sitio web y en nuestro boletín de noticias.
+ + ++Colaborar con otras personas mejorará tu paquete, y si les das a algunas de ellas rol de autoría y permisos de escritura en el repositorio, tu paquete se desarrollará de forma más sostenible. Además, ¡trabajar en equipo puede ser muy agradable! +
++Los consejos para colaborar en este capítulo están divididos en una sección sobre cómo hacer que la infraestructura de tu repo sea accessible para la contribución y la colaboración (código de conducta, directrices de contribución, etiquetas de issues) y una sección sobre cómo colaborar con nuevas personas que quieran contribuir, en particular en el contexto de la organización “ropensci” de rOpenSci en GitHub. +
++Además de estos consejos, en su mayoría técnicos, es importante recordar que hay que ser amable y tener en cuenta la perspectiva de las otras personas, especialmente cuando sus prioridades difieren de las tuyas. +
+Tras el traslado a nuestra organización de GitHub, el Código de Conducta de rOpenSci se aplicará a tu proyecto. Por favor, añade este texto al README
+Ten en cuenta que este paquete se publica con un [Código de Conducta para contribuciones](https://ropensci.org/code-of-conduct/).
+Al contribuir a este proyecto, te comprometes a cumplir sus condiciones.Y eliminar el código de conducta actual del paquete, si lo hubiera.
+Puedes utilizar guías de issues, pull request y de contribución. Tener un archivo de contribución como .github/CONTRIBUTING.md o docs/CONTRIBUTING.md es obligatorio. Una forma fácil de insertar una plantilla para una guía de contribución es la función use_tidy_contributing() del paquete usethis que inserta esta plantilla como .github/CONTRIBUTING.md. Un ejemplo más extenso es esta plantilla de Peter Desmet o las completas páginas wiki de GitHub para el paquete mlr3. Estas y otras plantillas generalmente tendrán que ser modificadas para su uso con un paquete de rOpenSci, en particular haciendo referencia y enlazando con nuestro Código de Conducta como se describe en otra sección de este libro. Modificar una guía de contribución genérica para añadir un toque propio también tiende a hacer que parezca menos impersonal y más sincera. Las preferencias personales en una guía de contribución incluyen
Preferencias de estilo. Sin embargo, puedes preferir que el estilo sea uno automático (a través de lintr o styler) o bien arreglar el estilo de código por tu cuenta especialmente si no utilizas un estilo de código popular como el estilo de código tidyverse.
Infraestructura, como roxygen2.
Preferencias de flujo de trabajo. Por ejemplo, abrir un issue antes de hacer un pull request.
Una declaración de alcance, como en el paquete skimr.
Creación de una cuenta de prueba, tests simulados, enlace a documentación externa.
rOpenSci recomienda que las guías de contribución incluyan una declaración del ciclo de vida, que aclare la visión y las expectativas para el desarrollo futuro del paquete, como en este ejemplo. Los paquetes estadísticos deben tener una declaración de ciclo de vida, como se especifica en Normas Generales de Estadística G1.2. Ese enlace proporciona una plantilla para una declaración de ciclo de vida sencilla. Los archivos CONTRIBUTING.md también pueden describir cómo se reconocen las contribuciones (ver esta sección).
+Te animamos a que dirijas las consultas y comentarios que no sean informes de errores o pedidos de nueva funcionalidad al foro de rOpenSci después de asegurarte de que verás esas preguntas en el foro. El foro puede usarse para hacer preguntas sobre cómo usar el paquete e informar de sus casos de uso, y puedes suscribirte a categorías y etiquetas individuales para recibir notificaciones sobre tu paquete. No dudes en mencionar esto en los documentos de tu paquete, ya sea en la guía de contribución o en la plantilla de issue. Pide etiquetar las publicaciones con el nombre del paquete.
+Una vez que un pull request está más cerca de ser aceptado, puedes utilizar un flujo de trabajo de GitHub Actions PR para aplicar el estilo al código con styler.
+Utilizando las funciones de GitHub en torno a los issues puedes hacer que sean más encontrables y que tu hoja de ruta sea pública.
+Puedes utilizar una o varias plantilla(s) de issue para que los informes de errores o pedido de funcionalidad sean más fáciles de completar. Cuando hay varias plantillas de issue, éstas se muestran en un menú al hacer click en el botón de “nuevo issue”
+Incluso puedes configurar una de las opciones para que apunte a algún lugar fuera de tu repositorio (por ejemplo, un foro de discusión).
+Consulta la documentación de GitHub (en inglés).
+Puedes utilizar etiquetas como “se necesita ayuda” y “buen primer issue” para que seas más fáciles de encontrar, incluso por gente que llega por primera vez a tu repo. Consulta este artículo de GitHub (en inglés). También puedes utilizar la etiqueta “principiante”. Consulta ejemplos de issues para principiantes en todos los repos de ropensci.
+Puedes resaltar hasta 3 issues por repositorio que aparecerán en la parte superior de tu gestor de issues como bonitas tarjetas. Puede ayudar a anunciar cuáles son tus prioridades.
+Puedes crear hitos y asignarles issues, lo que ayuda a ver lo que planeas para la próxima versión de tu paquete, por ejemplo.
+Puedes dirigir a quienes usan tu paquete al foro de rOpenSci, si lo supervisas, o habilitar Discusiones de GitHub para el repositorio de tu paquete. Las discusiones de GitHub pueden convertirse en issues si fuera necesario (y al revés, los issues pueden convertirse en discusiones).
+Lo primero lo primero: ¡estate al tanto de tu repositorio de GitHub!
+no te olvides de vigilar tu repositorio de GitHub para que te notifiquen los issues o pull requests (si trabajas por períodos, puedes informarlo en la guía de contribución).
no olvides hacer push de las actualizaciones que tengas localmente.
desactiva los test que fallan si no puedes arreglarlos, ya que crean ruido en los pull requests que pueden desconcertar quienes comienzan a colaborar.
No hay una regla general en rOpenSci sobre cómo debes incorporar a quienes colaboran en tu paquete al equipo. Deberías ir dándoles más derechos en el repositorio a medida que ganes confianza, y definitivamente deberías reconocer las contribuciones (ver esta sección).
+Puedes pedir a las nuevas personas que se incorporen que hagan PRs (ver la siguiente sección para evaluar un PR localmente, es decir, más allá de las comprobaciones de CI) a dev/main y evaluarlos antes de aceptarlos, y después de un tiempo dejar que hagan push a main. También puede que quieras mantener un sistema de revisión de PRs… ¡incluso para ti una vez que tengas miembros de equipo!
+Jim Hester ofrece un posible modelo de incorporación de miembros de equipo en su repositorio de lintr.
Si tu problema es reclutar nuevas personas, puedes publicar una convocatoria abierta como la de Jim Hester en Twitter, GitHub y, como responsable de un paquete de rOpenSci, puedes pedir ayuda en el Slack de rOpenSci y solicitar al equipo de rOpenSci ideas para reclutar ayuda.
+Las branches son baratas. Utilízalas mucho cuando desarrolles funciones, pruebes nuevas ideas o arregles problemas.
+Si sigues el desarrollo troncal, “agregarás pequeñas y frecuentes actualizaciones” a tu branch principal. Ver también la documentación del Flujo de GitHub y el flujo de GitLab. Es posible que quieras incrementar los números de versión (en DESCRIPTION) frecuentemente. Un aspecto particular del trabajo con otras personas es la revisión de pull requests. Pueden ver algunas guías útiles en:
Puedes modificar la configuración de tu repositorio de GitHub, por ejemplo requeriendo revisiones de pull requests antes de aceptarlas e incorporarlas. También puedes consultar la documentación acerca de propiedad sobre código.
+Para hacer y revisar pull requests recomendamos explorar las funciones del paquete usethis.
+Para tu configuración “git remote” consulta Happy Git with R. También es útil la sección Useful Git patterns for real life en el mismo libro.
+Si una persona contribuye a tu repositorio, considera añadirla en el archivo DESCRIPTION, con el rol de contribución (“ctb”) para pequeñas contribuciones o autoría (“aut”) para contribuciones mayores. Tradicionalmente, cuando se cita un paquete en una publicación científica, sólo se enumeran a quienes están como “aut”, no quienes están como “ctb”. Los sitios web creados con pkgdown listan en la página de inicio sólo a las personas con rol de autoría (“aut”). El resto están listadas en una página dedicada.
Como mínimo, considera la posibilidad de añadir el nombre de quien contribuyó cerca de la línea de la función o corrección de errores en el archivo NEWS.md.
+Te recomendamos reconozcas estas contribuciones generosamente, ya que es algo agradable y porque hará que sea más probable que la gente vuelva a contribuir a tu paquete o a otros repos de la organización.
+Como recordatorio de nuestra guía de empaquetado si tu paquete fue revisado y crees que quienes lo hicieron han hecho una contribución sustancial al desarrollo de tu paquete, puedes usar el campo Authors@R con el rol de revisión ("rev"), así
persona("Bea", "Hernández", rol = "rev",
+ comment = "Bea revisó el paquete (v. X.X.XX) para rOpenSci, véase <https://github.com/ropensci/software-review/issues/116>"),Sólo incluye a quienes hicieron la revisión con su consentimiento. Lee más en esta entrada del blog Thanking Your Reviewers: Gratitude through Semantic Metadata (Agradeciendo a quienes revisaron tu paquete: La gratitud a través de los metadatos semánticos). Ten en cuenta que ‘rev’ generará una NOTA de CRAN a menos que el paquete esté construido con R v3.5. Asegúrate de que utilizas la ultima versión de roxygen2 en CRAN.
Por favor, no incluyas a quienes se encargaron de la edición. ¡Tu participación y contribución a rOpenSci es suficiente agradecimiento!
+Si das a alguien permisos de escritura en el repositorio
+por favor, ponte en contacto con un miembro del quipo para invitar a la organización GitHub “ropensci” de rOpenSci a este nuevo miembro del equipo (en lugar de una colaboración externa)
ponte en contacto con quien gestiona la comunidad de rOpenSci o con otro miembro del equipo para que el nuevo miembro pueda ser invitado al espacio de trabajo de Slack de rOpenSci.
+Este capítulo describe nuestra Guía de contribución, la cual indica cómo puedes contribuir al proyecto rOpenSci, ya sea con código o no. +
+¿Quieres contribuir a rOpenSci? ¡Fantástico! Hemos desarrollado la Guía de Contribución a la Comunidad rOpenSci para darte la bienvenida a rOpenSci y animarte a colaborar. Te ayudará a averiguar lo que podrías ganar aportando tu tiempo, tus conocimientos y tu experiencia, a hacer que tus necesidades coincidan con las cosas que ayudarán a la misión de rOpenSci y a ponerte en contacto con los recursos que te ayudarán en el camino.
+Nuestro equipo y comunidad fomentan activamente un entorno acogedor donde personas de diferentes orígenes y niveles de habilidad aprenden, comparten ideas e innovan juntos abiertamente a través de normas y software compartidos, ya sea que usen o que desarrollen software. La participación en todas las actividades de rOpenSci está respaldada por nuestro Código de Conducta.
+Aceptamos contribuciones de código y de otros tipos de personas con o sin experiencia, en cualquier etapa de su carrera, y en cualquier sector. ¡No es necesario que desarrolles software! Tal vez quieras dedicar 30 minutos compartiendo el caso de uso de tu paquete en nuestro foro público o informando de un error, una hora aprendiendo en una Llamada Comunitaria, cinco horas revisando un paquete de R enviado para una revisión abierta por pares, o tal vez quieras comprometerte de forma continuada para ayudar a mantener un paquete.
+¿Cuáles son algunos de los beneficios de contribuir?
+Consulta nuestra Guía de Contribución y explora la sección What brings you here? (¿Qué te trae por aquí?) para encontrar qué declaraciones Quiero … te representan mejor y elegir tu camino.
+Para ayudar a que te reconozcas en estas declaraciones, las hemos agrupado en: Descubrir, Conectar, Aprender, Construir y Ayudar. Para cada categoría, enumeramos ejemplos de cómo podrían ser esas contribuciones y enlazamos a nuestros recursos para obtener los detalles que necesitas.
+Este capítulo resume la política de gestión propuesta para el mantenimiento continuo de los paquetes desarrollados como parte de las actividades de rOpenSci y/o bajo la organización ropensci en GitHub. Esta política de gestión pretende apoyar estos objetivos: +
++Garantizar que los paquetes proporcionados por rOpenSci estén actualizados y sean de alta calidad. +
++Proporcionar información clara sobre el estado de desarrollo y revisión de cualquier software en los repositorios de rOpenSci. +
++Gestionar el esfuerzo de mantenimiento para el equipo de rOpenSci, quienes mantienen paquetes y quienes contribuyen voluntariamente. +
++Proporcionar un mecanismo para el retiro gradual de paquetes, manteniendo al mismo tiempo las etiquetas de revisión por pares +
+Los elementos de infraestructura necesarios para la aplicación de esta política están, en algunos casos, parcialmente construidos y en otros casos aún no se han iniciado. Nuestro objetivo es adoptar esta política en parte para priorizar el trabajo en estos componentes.
+Los paquetes mantenidos por el equipo son desarrollados y mantenidos por el equipo de rOpenSci como parte de los proyectos de rOpenSci. Estos paquetes pueden ser revisados por pares o no. Muchos son paquetes de infraestructura que están fuera del alcance de la revisión por pares.
+Los paquetes mantenidos por el equipo aparecerán en el registro con la etiqueta “staff_maintained” y aparecerán en la página web de paquetes de rOpenSci o en lugares similares con la etiqueta “staff-maintained”.
Estos paquetes se almacenarán en la organización de GitHub ropensci.
Los paquetes mantenidos por el equipo serán comprobados, y su documentación sera generada por el sistema de rOpenSci. Este sistema no envía notificaciones pero guarda los resultados en forma de estado de commit en GitHub (marca de verificación roja o cruz roja).
Cuando las comprobaciones de un paquete fallen, el equipo de rOpenSci se esforzará en corregir los problemas, priorizando los paquetes en función de la base de las personas que lo usan (descargas), las dependencias inversas o los objetivos estratégicos.
Cada uno o dos años, rOpenSci revisará todos los paquetes que lleven más de un mes con comprobaciones fallidas para determinar si se transfieren a la organización “ropensci-archive”.
Los paquetes que fallan consistentemente y que no tienen un plan para volver al mantenimiento activo pasarán al estado de “archivados”. Estos paquetes serán transferidos a la organización “ropensci-archive” y se les asignará la etiqueta “archived” en el registro. No se comprobarán en el sistema de rOpenSci.
Los paquetes archivados no se mostrarán por defecto en la página web de paquetes. Una pestaña especial de páginas de paquetes los mostrará con "type": "archived", hayan sido revisados por pares o mantenidos por el personal.
Los paquetes archivados pueden desarchivarse cuando una nueva persona, o quien lo mantenía anteriormente, quiera revivirlo y solucionar los problemas. Para ello, ponte en contacto con rOpenSci. Se transferirán a la organización ropenscilabs.
Los paquetes revisados por pares son aquellos aportados a rOpenSci por la comunidad y que han pasado por la revisión por pares. Tienen que estar en el ámbito de aplicación en el momento del envío para ser revisados.
+Una vez aceptados, estos paquetes revisados por pares se transfieren desde el GitHub original a la organización de GitHub ropensci.
Los paquetes revisados por pares estarán en el registro etiquetados como “peer-reviewed” y tendrán una etiqueta de revisado por pares en su archivo README.
Los paquetes revisados por pares aparecerán en la página web de rOpenSci o lugares similares con la etiqueta “peer-reviewed”.
Los paquetes revisados por pares serán comprobados, y su documentación sera generada por el sistema de rOpenSci. Este sistema no envía notificaciones pero guarda los resultados en forma de estado de commit en GitHub (marca de verificación roja o cruz roja).
Si los paquetes están en CRAN, quienes lo mantienen pueden subscribirse a la API de notificaciones de comprobaciones de CRAN.
Cada uno o dos años, el equipo de rOpenSci revisará los paquetes que estén fallando o que han estado fallando durante largos períodos y contactará a quienes los mantienen para determinar los planes de mantenimiento y las actualizaciones previstas. En base a esto, rOpenSci puede optar por mantener el estado actual del paquete con la expectativa de actualizaciones, contribuir a los arreglos, ayudar a alguien más para mantenerlo, o transferir el paquete al estado “archived”.
En función de la base de personas que usan el paquete (medida por las descargas), las dependencias inversas u objetivos estratégicos de rOpenSci, el equipo de rOpenSci puede asistir a los paquetes que fallan a través de PRs revisados por quienes mantienen el paquete, o cambios directos (si quienes lo mantienen no responden por aproximadamente un mes). rOpenSci también proporcionará apoyo a pedido, tanto del equipo como de personas voluntarias de la comunidad, en función del tiempo disponible.
Si quien mantienen un paquete no responde consultas por un mes, o si ésta persona lo pide, rOpenSci puede buscar alguien más para mantener determinados paquetes revisados por pares que considere que tienen un alto valor para la comunidad en función de la base de personas que lo usan (descargas), dependencias inversas o los objetivos estratégicos de rOpenSci.
Cuando se archiven, estos paquetes pasarán de la organización “ropensci” de GitHub a la organización “ropensci-archive” (o a las cuentas de GitHub quienes los mantienen si así lo desean), siguiendo la guía de transferencia. Obtendrán la etiqueta “archived” en el registro. Conservarán las etiquetas e insignias de “peer-reviewed”. No se comprobará en el sistema rOpenSci.
Los paquetes archivados no se mostrarán por defecto en la página web de paquetes. Una pestaña especial de páginas de paquetes los mostrará con "type": "archived", hayan sido revisados por pares o mantenidos por el equipo.
Los paquetes “heredados” son paquetes ni creados ni mantenidos por el equipo de rOpenSci ni revisados por pares, pero que están bajo la organización de rOpenSci GitHub por razones históricas. (Antes de establecer el proceso de revisión por pares y su alcance, rOpenSci absorbía paquetes de la comunidad sin criterios bien definidos).
+rOpenSci transferirá los paquetes heredados de nuevo a las organizaciones y repositorios de quienes los mantienen, si lo desean. Caso contrario, serán transferidos al repositorio “ropensci-archive” siguiendo la guía de transferencia. Si los paquetes están en el ámbito de aplicación, rOpenSci les preguntará si desean someterlos al proceso de revisión del software.
Los paquetes heredados no se incluirán en el registro de paquetes.
Se pueden hacer excepciones para los paquetes que son partes vitales del ecosistema de paquetes de R y/o rOpenSci que son supervisados activamente por el equipo.
Los paquetes “incubados” son paquetes en desarrollo creados por el equipo o miembros de la comunidad como parte de proyectos comunitarios, como los creados en las desconferencias
+Los paquetes incubados vivirán en la organización ropenscilabs.
Los paquetes incubados aparecerán en el registro de paquetes con la etiqueta “incubator”.
Los paquetes incubados no aparecerán por defecto en el sitio web, pero las páginas de paquetes incluirán una pestaña de “paquetes experimentales”.
Los paquetes incubados serán comprobados, y su documentación sera generada por el sistema de rOpenSci. Este sistema no envía notificaciones pero guarda los resultados en forma de estado de commit en GitHub (marca de verificación roja o cruz roja). La documentación indicará claramente que el paquete es experimental.
Semestral o anualmente, rOpenSci se pondrá en contacto con quienes mantienen los paquetes incubados con repositorios de al menos tres meses de antigüedad para consultar por el estado de desarrollo y las preferencias para la migración a revisión por pares, ropensci-archive, o a sus organizaciones. En base a la respuesta, el paquete se migrará inmediatamente, se iniciará la revisión por pares, o la migración se aplazará hasta la próxima revisión. Los paquetes incubados se migrarán a ropensci-archive por defecto después de un año, siguiendo la guía de transferencia.
Los paquetes incubados archivados ganarán la etiqueta “archived”.
La organización incubator también incluirá proyectos que no sean paquetes de R.
Estos proyectos no aparecerán en el registro ni en una página web y no se comprobarán automáticamente.
La política de migración será la misma que para los paquetes R, con ubicaciones de migración adecuadas (por ejemplo, “ropensci-books”).
Si se archivan, los paquetes que no son de R se trasladarán a “ropensci-archive” siguiendo la guía de transferencia.
Los libros de rOpenSci son documentación larga, a menudo con formato de libro, relacionada con los paquetes, proyectos o temas de rOpenSci, creados por el personal de rOpenSci o por miembros de la comunidad.
+Los libros vivirán en la organización ropensci-books.
Los libros se alojarán en books.ropensci.org.
Los libros pueden estar maduros o en desarrollo, pero deben tener un mínimo de contenido antes de migrar a ropensci-books (por ejemplo desde ropenscilabs).
La autoría y el estado de desarrollo de un libro deben estar claramente descritos en su página de inicio y en el archivo README.
rOpenSci puede proporcionar etiquetas o plantillas (por ejemplo, “En desarrollo”, “Mantenido por la comunidad”) para utilizarse en las páginas de inicio de los libros en el futuro.
+Este capítulo presenta nuestra guía para realizar modificaciones a tu paquete: cambiar los nombres de los parámetros, cambiar los nombres de las funciones, eliminar funciones, e incluso retirar y archivar paquetes. +
++Este capítulo fue aportado inicialmente como nota técnica en el sitio web de rOpenSci por Scott Chamberlain; puedes leer la versión original en inglés aquí. +
+Cada persona es libre de tener su propia opinión sobre cuán libremente se pueden cambiar los parámetros, funciones, etc. en un paquete; ni CRAN ni ningún otro sitio impone normas sobre esto. En general, a medida que un paquete madura los cambios en los métodos orientados al uso (es decir, las funciones exportadas en un paquete R) deberían ser muy infrecuentes. Los paquetes de los cuales dependen muchos otros paquetes probablemente sean más cuidadosos con los cambios, y deberían serlo.
+En este capítulo se presentan soluciones que no requieren el paquete lifecycle, pero que pueden resultarte útiles. Te recomendamos leer la documentación de lifecycle.
+A veces hay que cambiar los nombres de los parámetros, ya sea en pos de mayor claridad u otras razones.
+Un posible enfoque es comprobar si los argumentos obsoletos no faltan, y llamar a stop() con un mensaje significativo.
foo_bar <- function(x, y) {
+ if (!missing(x)) {
+ stop("utiliza 'y' en lugar de 'x'")
+ }
+ y^2
+}
+
+foo_bar(x = 5)
+#> Error en foo_bar(x = 5) : utiliza 'y' en lugar de 'x' Si quieres que sea más útil, podrías emitir una advertencia pero tomar automáticamente la acción necesaria
+foo_bar <- function(x, y) {
+ if (!missing(x)) {
+ warning("utiliza 'y' en lugar de 'x'")
+ y <- x
+ }
+ y^2
+}
+
+foo_bar(x = 5)
+#> Warning message:
+#> In foo_bar(x = 5) : utiliza 'y' en lugar de 'x'
+#> 25Ten cuidado con el parámetro .... Si tu función tiene ... y ya has eliminado un parámetro (llamémoslo z), alguien puede tener un código más antiguo que utilice z. Cuando usen z, como no es un parámetro en la definición de la función, es probable que sea capturado por ... y se ignore silenciosamente – no es lo que quieres. En su lugar, deja el argumento z, emitiendo un error si se utiliza.
Si tienes que cambiar el nombre de una función, hazlo gradualmente, como con cualquier otro cambio en tu paquete.
+Digamos que tienes una función foo.
foo <- function(x) x + 1Pero quieres cambiar el nombre de la función a bar.
En lugar de simplemente cambiar el nombre de la función y que foo deje de existir directamente, en la primera versión del paquete donde bar aparezca, haz un alias como
#' foo - añadir 1 a un input
+#' @export
+foo <- function(x) x + 1
+
+#' @export
+#' @rdname foo
+bar <- fooCon la solución anterior, se pueden usar tanto foo() como bar() – cualquiera de los dos hará lo mismo, ya que son la misma función.
También es útil tener un mensaje, pero entonces sólo querrás emitirlo cuando se use la función que va a desaparecer, por ejemplo
+#' foo - añadir 1 a un input
+#' @export
+foo <- function(x) {
+ warning("por favor, utiliza bar() en lugar de foo()", call. = FALSE)
+ bar(x)
+}
+
+#' @export
+#' @rdname foo
+bar <- function(x) x + 1Después de que la versión del paquete con foo y bar haya sido usada durante un tiempo, en la siguiente versión puedes eliminar el antiguo nombre de la función (foo), y tener sólo bar.
#' bar - añadir 1 a un input
+#' @export
+bar <- function(x) x + 1Para eliminar una función de un paquete (digamos que el nombre de tu paquete es holamundo), puedes utilizar el siguiente protocolo
x (por ejemplo v0.2.0)En la propia función, utiliza .Deprecated() para indicar cual es la nueva función que substituye la anterior.
foo <- function() {
+ .Deprecated("bar")
+}Hay opciones en .Deprecated para especificar un nuevo nombre de función, así como un nuevo nombre de paquete, lo que tiene sentido cuando se mueven funciones a paquetes diferentes.
El mensaje que da .Deprecated es una advertencia, por lo que los usuarios pueden suprimirla con suppressWarnings() si lo desean.
Haz una página de manual para las funciones obsoletas por ejemplo:
+#' Funciones obsoletas en holamundo
+#'
+#' Estas funciones aún funcionan pero serán eliminadas (obsoletas) en la próxima versión.
+#'
+#' \itemize {
+#' \item \code{\link{foo}}: Esta función está obsoleta y se eliminará en la
+#' próxima versión de este paquete.
+#' }
+#'
+#' @name holamundo-deprecated
+NULLEsto crea una página de manual a la que los usuarios pueden acceder como `?holamundo-deprecated``` y verán en el índice de la documentación. Añade cualquier función a esta página según sea necesario, y quítala cuando una función caduque (ver más abajo).
v0.3.0) puedes caducar la función (es decir, que desaparezca completamente del paquete, excepto por una página man con una nota sobre ella).En la propia función, utiliza .Defunct() de esta manera:
foo <- function() {
+ .Defunct("bar")
+}Observa que el mensaje en .Defunct es un error para que la función se detenga mientras que .Deprecated utiliza una advertencia que permite que la función continúe.
Además, es bueno añadir ... a todas las funciones caducas para que si los usuarios pasan algún parámetro obtengan el mismo mensaje de caducidad en lugar de un error de argumento no utilizado de esta forma:
foo <- function(...) {
+ .Defunct("bar")
+}Sin ... da:
foo(x = 5)
+#> Error en foo(x = 5) : argumento no utilizado (x = 5)Y con ... da:
foo(x = 5)
+#> Error: 'foo' ha sido eliminada de este paqueteHaz una página de manual para las funciones caducas por ejemplo:
+#' Funciones caducas en holamundo
+#'
+#' Estas funciones han sido removidas, ya no están disponibles.
+#'
+#' \itemize {
+#' \item \code{\link{foo}}: Esta función ha sido removida
+#' }
+#'
+#' @name holamundo-defunct
+NULLEsto crea una página de manual que se accede como `?holamundo-defunct``` y que aparece en el índice de documentación. Añade a esta página las funciones que necesites. Es probable que quieras mantener esta página indefinidamente.
No es necesario que cambies los test de las funciones obsoletas hasta que caduquen.
+.Deprecated dentro de la función, ¿has cambiado los parámetros en la función obsoleta, o has creado una nueva función que sustituye a la función obsoleta, etc.? Hay que testear esos cambios, si se han hecho.suppressWarnings() podría utilizarse para suprimir la advertencia emitida desde .Deprecated. Pero como las pruebas no están orientadas al uso, no es tan malo que las pruebas emitan advertencias, y la advertencia podría incluso utilizarse como recordatorio para quien mantiene el paquete.Una vez que se caduca una función, sus tests se eliminan sin más.
+Por lo general, el software tiene una vida útil finita, y es posible que los paquetes deban ser archivados en algún momento. Los paquetes son archivados y transladados a una organización dedicada de GitHub, ropensci-archive. Antes de archivar, el contenido del archivo README debe trasladarse a una ubicación alternativa (como “README-OLD.md”), y sustituirse por un contenido mínimo que incluya algo como lo siguiente
+# <nombre del paquete>
+
+[](https://www.repostatus.org/#unsupported)
+[](https://github.com/ropensci/software-review/issues/<issue_number>)
+
+Este paquete ha sido archivado. El antiguo README está ahora en [README-OLD](<link-a-README-viejo>).La etiqueta del estado del repositorio debe ser “unsupported” (sin soporte) para los paquetes anteriormente publicados, o “abandoned” (abandonado) para los ex paquetes conceptuales o en proceso, en cuyo caso el código de la etiqueta anterior debe sustituirse por:
+[](https://www.repostatus.org/#abandoned)Un ejemplo de un archivo README mínimo en un paquete archivado está en ropensci-archive/monkeylearn. Una vez que el README se ha copiado en otro lugar y se ha reducido a su forma mínima, hay que seguir los siguientes pasos
+Los paquetes archivados pueden ser desarchivados si quien lo mantenía, o una nueva persona, deciden reanudar el mantenimiento. Para ello, ponte en contacto con rOpenSci y se transferirá el repo a la organización ropenscilabs.
+ + ++Actualmente la gran mayoría de los paquetes de rOpenSci se desarrollan en GitHub. Aquí tienes algunos consejos para aprovechar la plataforma en una sección sobre hacer que tu repo sea más fácil de descubrir y una sección sobre publicitar tu propia cuenta de GitHub después de pasar por la revisión por pares. +
+Las áreas del repositorio de GitHub ayudan a navegar y buscar en los repositorios de GitHub, son usadas por R-universe en paginas de paquetes y para resultados de busquedas. También son usadas por codemetar en las palabras clave del registro de rOpenSci.
Recomendamos:
+Añadir “r”, “r-package” y “rstats” como áreas al repositorio de tus paquetes.
Añadir cualquier otra área relevante al repositorio de tus paquetes.
Es posible que te hagamos sugerencias una vez que tu paquete esté incorporado.
+El lingüista de GitHub asignará un lenguaje a tu repo en función de los archivos que contenga. Algunos paquetes que contienen mucho código en C++ pueden ser clasificados como paquetes de C++ en lugar de R, lo cual está bien y muestra la necesidad de las áreas “r”, “r-package” y “rstats”.
+Recomendamos anular el lingüista de GitHub añadiendo o modificando un archivo .gitattributes a tu repositorio en dos casos:
+Si almacenas archivos html en lugares no estándar (fuera en docs/, por ejemplo, en vignettes/) omite los archivos de documentación. Añade *.html linguist-documentation=true a .gitattributes (como en este ejemplo).
Si tu repo contiene código que no es de tu autoría, por ejemplo, código JavaScript, añade inst/js/* linguist-vendored a .gitattributes (como en este ejemplo).
De este modo, la clasificación lingüística y las estadísticas de tu repositorio reflejarán mejor el código fuente que contiene, además de hacerlo más descubrible. En particular, si el lingüista no reconoce correctamente que tu repositorio contiene principalmente código R, tu paquete no aparecerá en los resultados de búsqueda con el filtro language:R. Del mismo modo, tu repositorio no podrá aparecer entre los repos de R populares.
Más información sobre las anulaciones del lingüista de GitHub aquí.
+Como responsable de un paquete incorporado, ahora eres miembro de la organización GitHub “ropensci” de rOpenSci. Por defecto, la pertenencia a la organización es privada; consulta cómo hacerla pública en la documentación de GitHub.
Incluso después de que el repositorio de tu paquete haya sido transferido a rOpenSci, puedes destacarlo en tu propia cuenta.
En general, recomendamos añadir al menos una imagen de perfil (¡que no tiene por qué ser tu cara!) y tu nombre a tu perfil de GitHub.
Te ayudaremos a promocionar tu paquete, pero aquí hay algunas cosas más para tener en cuenta.
+Si te enteras de un caso de uso de tu paquete, anima a quien lo escribió a publicar el enlace en nuestro foro de debate en la categoría Casos de uso, para recibir un toot (mensaje en Mastodon) de rOpenSci y su posible inclusión en el boletín mensual de rOpenSci. También te recomendamos que añadas un enlace al caso de uso en la sección “casos de uso reales” de tu archivo README.
Cuando publiques una nueva versión de tu paquete o lo publiques en CRAN por primera vez,
Comparte sobre el paquete en Mastodon utilizando el hashtag “#rstats” y etiqueta a rOpenSci! Esto puede ayudar llegar a gente que pueda colaborar o usar el paquete. Ejemplos enviados desde rOpenSci mismo: “A package a day” (un paquete al dia), Help wanted (se necesita ayuda), Use case (caso de uso), Welcome post (mensaje de bienvenida).
+haz un pull request a R Weekly con una mensaje sobre la versión en la sección “New Releases” (o “New Packages” para la primera versión de GitHub/CRAN).
Comparte en tus redes sociales.
Considera enviar un breve artículo sobre el lanzamiento a rOpenSci tech notes. Ponte en contacto con la persona encargada de gestionar la comunidad de rOpenSci, (por ejemplo, a través de Slack o info@ropensci.org). Consulta las recomendaciones sobre cómo contribuir con un artículo en el blog).
Envía tu paquete a listas de paquetes como CRAN Task Views.
Si decides promocionar tu paquete dando una charla sobre él en una reunión o conferencia (¡excelente idea!) lee en este artículo de Jenny Bryan y Mara Averick (en inglés).
+Tu paquete probablemente va a tener diferentes versiones a lo largo del tiempo: instantáneas de un estado del paquete que puedes publicar en CRAN, por ejemplo. Estas versiones deben estar debidamente numeradas, publicadas y descriptas en un archivo NEWS. Más detalles a continuación. +
+
+Ten en cuenta que el proceso de actualización de NEWS y de versionado de tu paquete se puede hacer más fluido utilizando el paquete fledge.
+
Utiliza las funciones usethis::use_release_issue() y devtools::release() para recordar mejor los pasos a seguir.
Etiqueta cada versión en git después de cada envío a CRAN. Más información.
A CRAN no le gustan las actualizaciones demasiado frecuentes. Dicho esto, si observas un problema importante una semana después de una publicación en CRAN, explícalo en el archivo cran-comments.md e intenta publicar una versión más reciente.
Un archivo NEWS que describa los cambios asociados a cada versión facilita ver qué cambia en el paquete y cómo puede afectar los flujos de trabajo. Debes añadir uno para tu paquete, y hacerlo fácil de leer.
+Es obligatorio utilizar un NEWS o NEWS.md en la raíz de tu paquete. Recomendamos utilizar NEWS.md para que el archivo sea más navegable.
Utiliza nuestro archivo NEWS de ejemplo como modelo. Puedes encontrar un buen archivo NEWS real en el repositorio del paquete taxize por ejemplo.
Si utilizas NEWS, añádelo a .Rbuildignore, pero no si usas NEWS.md.
Actualiza el archivo de noticias antes de cada envío a CRAN, con una sección con el nombre del paquete, la versión y la fecha de envío, como (como se ve en nuestro archivo NEWS de ejemplo):
foobar 0.2.0 (2016-04-01)
+=========================Debajo de esa cabecera, agrega las secciones que sean necesarias, incluyendo “Nueva funcionalidad”, “Mejoras menores”, “Bugs resueltos”, “Funciones obsoletas y caducas”, “Mejoras en la documentación” y cualquier epígrafe especial que agrupe un gran número de cambios. Debajo de cada encabezado enumera los elementos según sea necesario (como se ve en nuestro archivo NEWS de ejemplo). Para cada elemento, proporciona una descripción de la nueva característica, mejora, error corregido o función/característica obsoleta. Enlaza a cualquier issue de GitHub relacionado como (#12). El (#12) se reemplazará en GitHub con un enlace a ese issue en el repo.
Después de haber añadido un git tag y lo hayas enviado a GitHub, añade las noticias de esa versión etiquetada a las notas de publicación de una versión en tu repo de GitHub con un título como pkgname v0.1.0. Consulta la documentación de GitHub sobre la creación de una publicación.
Nuestro boletín de noticias describirá los paquetes con nuevas versiones en CRAN. Ver el siguiente capítulo sobre marketing para más ideas sobre cómo informar a más personas que podrían usar tu paquete sobre el lanzamiento.
Para obtener más orientación sobre el archivo NEWS, te sugerimos que leas la guía de estilo de tidyverse.
+foobar 0.2.0 (2016-04-01)
+=========================
+
+### NUEVA FUNCIONALIDAD
+
+ * Nueva función `hacer_algo()` para hacer cosas. (#5)
+
+### MEJORAS MENORES
+
+ * Documentación mejorada para `cosas()`. (#4)
+
+### ERRORES CORREGIDOS
+
+ * Corrige un error en `algo()`. (#3)
+
+### OBSOLETO Y CADUCADO
+
+ * `hola_mundo()` ahora es una función obsoleta y se eliminará en un en una versión futura, utiliza `hola_marte()`.
+
+### CORRECCIONES EN LA DOCUMENTACIÓN
+
+ * Se aclaró el papel de `hola_marte()` vs. `adios_marte()`.
+
+### (algo especial: cualquier epígrafe que agrupe un gran número de cambios bajo un mismo tema)
+
+ * blablabla.
+
+foobar 0.1.0 (2016-01-01)
+=========================
+
+### NUEVA FUNCIONALIDAD
+
+ * publicado en CRAN.+rOpenSci acepta paquetes que cumplen con nuestras recomendaciones a través de un proceso fluido de Revisión por pares de software. Para garantizar un estilo consistente entre todas nuestras herramientas, hemos escrito este capítulo en el que se destacan recomendaciones para el desarrollo de paquetes. Por favor, también lee y aplica nuestro capítulo sobre integración continua (CI). En la tercera sección de este libro, que comienza con un capítulo sobre la colaboración, ofrecemos una guía para continuar luego del proceso de revisión. +
++Recomendamos a quienes desarrollen paquetes que lean el libro de Hadley Wickham y Jenny Bryan sobre el desarrollo de paquetes. Es exhaustivo y está disponible gratis en línea (pero en inglés). Algunas partes de nuestra guía son redundantes con respecto a otros recursos, pero destaca las recomendaciones propias de rOpenSci. +
++Para leer por qué vale la pena enviar un paquete a rOpenSci siguiendo las recomendaciones, echa un vistazo a razones para enviar un paquete. +
+Recomendamos fuertemente elegir nombres cortos y descriptivos en minúsculas. Si tu paquete se conecta con uno o más servicios comerciales, asegúrate de que el nombre no infringe las recomendaciones de la marca. Puedes comprobar si el nombre de tu paquete está disponible, es informativo y no es ofensivo (en inglés) utilizando la función pak::pkg_name_check(); también utiliza un motor de búsqueda porque asi verías si es ofensivo en otras idiomas que inglés. En particular, no elijas un nombre de paquete que no esté disponible en CRAN o en Bioconductor.
Existe un equilibrio entre las ventajas de un nombre de paquete único y un nombre de paquete menos original.
+Este artículo de Nick Tierney (en inglés) lista otras consideraciones interesantes a tener en cuenta al nombrar paquetes de R. En caso de que cambies de opinión sobre el nombre de tu paquete, este segundo artículo de Nick explica cómo cambiar el nombre de tu paquete.
Recomendamos usar el paquete codemetar para crear y actualizar un archivo JSON CodeMeta para tu paquete usando codemetar::write_codemeta(). Incluirá automáticamente toda la información útil, incluyendo temas de GitHub. CodeMeta utiliza términos de Schema.org por lo que, a medida que gane popularidad, los metadatos JSON de tu paquete podrían ser utilizados por servicios de terceros, incluso por motores de búsqueda.
Los nombres de las funciones y los argumentos deben elegirse para que funcionen juntos y formen una API de programación común y lógica que sea fácil de leer y autocompletar.
+objeto_verbo() para las funciones de tu paquete que toman un tipo de datos común o interactúan con una API común. objeto se refiere a los datos/API y verbo a la acción principal. Este esquema ayuda a evitar conflictos de nombres con paquetes que pueden tener verbos similares, y hace que el código sea legible y fácil de autocompletar. Por ejemplo, en stringi las funciones que empiezan con stri_ manipulan cadenas de texto (stri_join(), stri_sort()y en googlesheets las funciones que empiezan con gs_ son llamadas a la API de Google Sheets (gs_auth(), gs_user(), gs_download()).Para las funciones que manipulan un objeto o dato y devuelven un objeto o dato del mismo tipo, haz que el objeto o dato sea el primer argumento de la función para mejorar la compatibilidad con el operador pipe (|> de R base, %>% del paquete magrittr).
Recomendamos fuertemente usar snake_case por sobre todos los otros estilos, a menos que estés usando funciones de un paquete que ya se utilice ampliamente.
Evita los conflictos de nombres de funciones con los paquetes de R base u otros paquetes populares (por ejemplo ggplot2, dplyr, magrittr, data.table)
Los nombres y el orden de los argumentos deben ser coherentes entre las funciones que utilizan inputs similares.
Las funciones del paquete que importan datos no deben importar los datos al entorno global, sino que deben devolver objetos. En general, se debe evitar asignar objectos al entorno global.
Utiliza el paquete cli o las herramientas de R base (message() y warning()) para comunicarte con las personas que usen tus funciones.
Lo más destacado del paquete cli incluye: empaquetado automático, respeto de la convención NO_COLOR muchos elementos semánticos y amplia documentación. Más información en este artículo.
No utilices print() o cat() a menos que sea para un método print.*() o str.*() ya que estos métodos de impresión de mensajes son más difíciles de silenciar.
Proporciona una forma para suprimir la verbosidad, preferiblemente a nivel de paquete: haz que la creación de mensajes dependa de una variable u opción de entorno (como “usethis.quiet” en el paquete usethis), en lugar de en un parámetro de la función. El control de los mensajes podría ser a varios niveles (“ninguno,”informar”, “depurar”) en lugar de lógico (ningún mensaje / todos los mensajes). El control de la verbosidad es útil para usuarios/as finales, pero también en las pruebas. Puedes encontrar más comentarios interesantes en este issue de la guía de diseño de tidyverse.
Si proporcionas una interfaz gráfica de usuario (GUI) (como una aplicación Shiny), para facilitar el flujo de trabajo incluye un mecanismo para reproducir automáticamente los pasos realizados en la GUI. Esto puede incluir la generación automática del código necesario para reproducir los mismos resultados, la generación de valores intermedios producidos en la herramienta interactiva, o simplemente un mapeo claro y bien documentado entre las acciones de la GUI y las funciones usadas. (Ver también “Tests” más abajo).
+El paquete tabulizer por ejemplo, tiene un flujo de trabajo interactivo para extraer tablas, pero también puede extraer sólo coordenadas, por lo que se pueden volver a ejecutar los mismos pasos como un script. Otros dos ejemplos de aplicaciones shiny que generan código son https://gdancik.shinyapps.io/shinyGEO/y https://github.com/wallaceEcoMod/wallace/.
Recomendamos que tu paquete utilice un método coherente de tu elección para comprobar las entradas – ya sea R base, un paquete de R o ayudantes personalizados.
+Si tu paquete accede a una API web o a otro recurso web,
+gh::gh()).Para más información, consulta el artículo del blog Por qué deberías (o no) crear un cliente API.
+Para más información sobre cómo dar estilo a tu código, nombrar funciones y scripts de R dentro de la carpeta R te recomendamos que leas el capítulo “Code” (Código) del libro R Packages. Recomendamos el paquete styler para automatizar parte del estilo del código. También te sugerimos que leas la Guía de estilo de Tidyverse (en inglés).
Puedes optar por utilizar = en lugar de <- siempre que seas coherente con esa elección dentro de tu paquete. Recomendamos evitar el uso de -> para la asignación dentro del paquete. Si utilizas <- en todo tu paquete, y también utilizas R6 en ese paquete, debrás utilizar = para la asignación dentro de la generación de la clase R6Class - esto no se considera una incoherencia porque no puedes usar <- en este caso.
usethis::use_citation()y llenarlo con los valores generados por la función citation().bibentry y no en la forma aceptada previamente de citEntry().citHeader(). Quizás incluso añade la referencia a ese recurso.Como ejemplo, revisa el archivo CITATION de dynamite donde se refiere al manual, así como a otras publicaciones asociadas.
+citHeader("To cite dynamite in publications use:")
+
+bibentry(
+ key = "dynamitepaper",
+ bibtype = "Misc",
+ doi = "10.48550/ARXIV.2302.01607",
+ url = "https://arxiv.org/abs/2302.01607",
+ author = c(person("Santtu", "Tikka"), person("Jouni", "Helske")),
+ title = "dynamite: An R Package for Dynamic Multivariate Panel Models",
+ publisher = "arXiv",
+ year = "2023"
+)
+bibentry(
+ key = "dmpmpaper",
+ bibtype = "Misc",
+ title = "Estimating Causal Effects from Panel Data with Dynamic
+ Multivariate Panel Models",
+ author = c(person("Santtu", "Tikka"), person("Jouni", "Helske")),
+ publisher = "SocArxiv",
+ year = "2022",
+ url = "https://osf.io/preprints/socarxiv/mdwu5/"
+)
+
+bibentry(
+ key = "dynamite",
+ bibtype = "Manual",
+ title = "Bayesian Modeling and Causal Inference for Multivariate
+ Longitudinal Data",
+ author = c(person("Santtu", "Tikka"), person("Jouni", "Helske")),
+ note = "R package version 1.0.0",
+ year = "2022",
+ url = "https://github.com/ropensci/dynamite"
+)CITATION.cff gracias al paquete cffr que también proporciona un flujo de trabajo con GitHub Actions para mantener el archivo CITATION.cff actualizado.Todos los paquetes deben tener un archivo README, llamado README.md en la raíz del repositorio. El README debe incluir, en este orden:
Si utilizas otra etiqueta de estado del repo, como el ciclo de vida, por favor añade también una etiqueta de repostatus.org . Ejemplo de un README de un repo con dos insignias de estado.
+[](https://github.com/ropensci/software-review/issues/<issue_id>)donde issue_id es el número del issue en el repositorio donde se hizo la revisión del software. Por ejemplo, la etiqueta de revisión de rtimicropem utiliza el número 126, ya que es el número de issue de revisión. La etiqueta indicará primero “en revisión” y luego “revisado” una vez que tu paquete haya sido incorporado (issue etiquetado como “aprobado” y cerrado), y estará vinculado con el issue de la revisión.
Si tu README tiene muchas etiquetas, considera la posibilidad de ordenarlas en una tabla HTML para que sea más fácil ver la información de un vistazo. Consulta los ejemplos en el repo de drake y en el repo de qualtRics. Las secciones posibles son:
La tabla debe ser más ancha que larga para enmascarar el resto del README.
+Si tu paquete se conecta a una fuente de datos o a un servicio en línea, o utiliza otro software, ten en cuenta que el README de tu paquete puede ser el punto de entrada para alguien que lo usa por primera vez. Debe proporcionar suficiente información para poder entender la naturaleza de los datos, el servicio o el software, y proporcionar enlaces a otros datos y documentación relevantes. Por ejemplo un README no debe limitarse a decir: “Proporciona acceso a GooberDB”, sino que también debe incluir “…, un repositorio online de avistamientos de Goober en Sudamérica. Se puede encontrar más información sobre GooberDB, y la documentación de la estructura de la base de datos y metadatos en este enlace”.
Recomendamos no crear el README.md directamente, sino a partir de un archivo README.Rmd (un archivo R Markdown) si incluye código de ejemplo. La ventaja del archivo .Rmd es que puedes combinar el texto con el código que puede actualizarse fácilmente cada vez que se actualice tu paquete.
Considera utilizar usethis::use_readme_rmd() para generar una plantilla para el archivo README.Rmd y para configurar automáticamente un chequeo que garantice que README.md sea siempre más reciente que README.Rmd antes de hacer un commit.
Los ejemplos largos deben incluirse sólo en las viñetas. Si quieres que las viñetas sean más accesibles antes de instalar el paquete, te sugerimos crear un sitio web para tu paquete.
Consulta el README de gistr para ver un buen ejemplo de README de un paquete pequeño, y el README de bowerbird para un buen ejemplo de README de un paquete más grande.
Todas las funciones exportadas del paquete deben estar completamente documentadas con ejemplos.
Si existe un posible solapamiento o confusión con otros paquetes que ofrezcan una funcionalidad similar o tengan un nombre parecido, añade una nota en el README, en la viñeta principal y, potencialmente, en el campo descripción de archivo DESCRIPTION. Por ejemlo, el README de rebird README o del paquete slurmR (que no es parte de rOpensci).
El paquete debe contener la documentación general del paquete para ?paquete (o ?`paquete-package``` si hay un conflicto de nombres). Opcionalmente, puedes utilizar tanto `?paquete` como?paquete-package``` para el archivo del manual del paquete utilizando la etiqueta@aliasesde roxygen. [usethis::use_package_doc()`](https://usethis.r-lib.org/reference/use_package_doc.html) añade la plantilla para generar la documentación general.
El paquete debe contener al menos una viñeta en formato HTML que cubra una parte importante de las funciones del paquete, ilustrando casos de uso realistas y cómo se supone que las funciones interactúen entre ellas. Si el paquete es pequeño, la viñeta y el README pueden tener un contenido muy similar.
Al igual que el README, la documentación general o las viñetas puede ser el punto de entrada para alguien que lo usa por primera vez. Si tu paquete se conecta a una fuente de datos o a un servicio en línea, o utiliza otro software, debe proporcionar suficiente información para poder entender la naturaleza de los datos, el servicio o el software, y proporcionar enlaces a otros datos y documentación relevantes. Por ejemplo, la introducción de una viñeta o la documentación no debería limitarse a decir: “Proporciona acceso a GooberDB”, sino incluir también: “…, un repositorio online de avistamientos de Goober en Sudamérica. Puedes encontrar más información sobre GooberDB y la documentación de la estructura de la base de datos y los metadatos en este enlace”. Cualquier viñeta debe incluir que conocimientos previos son necesarios para poder entenderla.
La viñeta general debe presentar una serie de ejemplos que progresen en complejidad desde el uso básico al avanzado.
+La funciones de uso avanzado o que sean usadas sólo para desarrollo pueden incluirse en una viñeta aparte (por ejemplo, la programación usando evaluación no estándar con dplyr).
El README, la documentación del paquete de nivel superior, las viñetas, los sitios web, etc., deben tener suficiente información al principio para obtener una visión general del paquete y de los servicios o datos a los que se conecta, y proporcionar navegación a otras partes de la documentación relevante. Esto es para seguir el principio de múltiples puntos de entrada; es decir, tener en cuenta el hecho de que cualquier pieza de documentación puede ser el primer encuentro de la persona con el paquete y/o la herramienta o los datos que accede.
La(s) viñeta(s) debe(n) incluir citas a software y de artículos cuando corresponda.
Si tu paquete proporciona acceso a una fuente de datos, requerimos que la DESCRIPCIÓN contenga (1) nna breve identificación y/o descripción de la organización responsable de generar datos; y (2) un URL con la página pública que proporciona, describe o permite el acceso a los datos (que a menudo puede diferir de la URL que conduce directamente a la fuente de datos).
Utiliza mensajes de inicio en el paquete sólo cuando sea necesario (cuando algunas funciones son enmascaradas, por ejemplo). Evita los mensajes de inicio del paquete tales como “Esto es paquete 2.4-0” o la guía de cómo citarlo porque pueden ser molestos quien lo usa. Utiliza la documentación para brindar ese tipo de información.
Puedes optar por tener una sección en el README sobre casos de uso de tu paquete (otros paquetes, artículos de blog, etc.). Por ejemplo, esta sección en el README del paquete vcr).
Pedimos que todos los paquetes que se presenten para revisión utilicen roxygen2 para generar la documentación. roxygen2 es un paquete de R que compila automáticamente archivos .Rd en la carpeta man del paquete utilizando etiquetas incluidas antes de cada función. roxygen2 tiene soporte para la sintaxis Markdown. Una ventaja clave de utilizar roxygen2 es que tu archivo NAMESPACE siempre se generará automáticamente y estará actualizado.
Más información sobre el uso de roxygen2 para generar documentación está disponible en el libro R Packages y en el sitio web de roxygen2.
Si escribiste los archivos .Rd directamente sin roxygen2, el paquete Rd2roxygen contiene funciones para convertir la documentación de Rd a documentación de roxygen2.
Todas las funciones deben documentar el tipo de objeto devuelto bajo el encabezado @return.
El valor por defecto de cada parámetro debe estar claramente documentado. Por ejemplo, en lugar de escribir “Un valor lógico que determina si …” deberías escribir “Un valor lógico (por defecto TRUE) que determina si …”. También es una buena práctica indicar los valores por defecto directamente en la definición de tu función:
f <- function(a = TRUE) {
+ # código de la función
+}La documentación debe ayudar a la navegación incluyendo links entre funciones relacionadas y agrupando la documentación de funciones relacionadas en página de ayuda comunes. Para esto recomendamos la etiqueta @seealso, que crea automáticamente enlaces “See also” (ver también, en inglés) y puede agrupan las funciones en sitios web generados con pkgdown. Consulta la sección “manual” del libro R Packages y la sección “Agrupación de funciones” de este capítulo para más detalles.
Puedes reutilizar partes de la documentación (por ejemplo, detalles sobre la autenticación, paquetes relacionados) en las viñetas, README y páginas de manual. Consulta la viñeta de roxygen2 sobre la reutilización de documentación.
Para incluir ejemplos, puedes utilizar el clásico @examples (en plural “examples”), pero también la etiqueta @example <path> (en singular “example”) para almacenar el código de ejemplo en un script R independiente (idealmente en man/), y la etiqueta @exampleIf para ejecutar ejemplos condicionalmente y evitar fallos de R CMD check. Consulta la documentación de roxygen2 sobre ejemplos.
Añade #' @noRd a las funciones internas. Quizá te interese el paquete experimental devtag para obtener páginas de manual locales al utilizar #' @noRd.
A partir de la versión 7.0.0 de roxygen2, las clases R6 son oficialmente compatibles. Consulta la documentación de roxygen2 para saber cómo documentar las clases R6.
Esta subsección es especialmente relevante para quienes deseen enviar su paquete a CRAN. CRAN comprobará las URLs incluidas en la documentación y no permitirá páginas que redirijan a códigos 301. Puedes utilizar el paquete urlchecker para reproducir los checks de CRAN y, en particular, sustituir las URLs originales por las URLs a las que redirigen. Otra opción es mostrar algunas URLs de manera explícita sin link (cambiar <https://ropensci.org/> por https://ropensci.org/o \url{https://ropensci.org/} por https://ropensci.org/), pero si lo haces, tendrás que implementar algún tipo de comprobación de URL para evitar que se rompan sin que te des cuenta. Además, no se podrá hacer click en los enlaces desde la documentación local.
Te recomendamos que crees un sitio web con la documentación de tu paquete utilizando pkgdown. Hay un capítulo sobre pkgdown (en inglés) en libro “R packages”, y, cómo no es de extrañar, el paquete pkgdown tiene su propio sitio web de documentación.
Hay algunos elementos que nos gustaría destacar aquí.
+Sólo tendrás que preocuparte por la construcción automática de tu sitio web cuando se apruebe y se transfiera el repositorio de tu paquete a la organización ropensci; de hecho, después de eso se construirá un sitio web con pkgdown para tu paquete luego de cada push al repositorio de GitHub. Puedes encontrar el estado de estas acciones en https://dev.ropensci.org/job/nombre_paquete (por ejemplo para magick) y el sitio web en https://docs.ropensci.org/nombre_paquete (por ejemplo para magick). La construcción del sitio web utilizará el archivo de configuración de pkgdown si tienes uno, excepto para el estilo, ya que utilizará el paquete rotemplate. El sitio web resultante tendrá una barra de búsqueda local. Por favor, informa de los errores, y haz preguntas o pedidos de nuevas características sobre la construcción del sitio centralizada en https://github.com/ropensci/docs/ y sobre la plantilla en https://github.com/ropensci/rotemplate/.
Si las viñetas de tus paquetes necesitan credenciales (claves de API, tokens, etc.) para generarse, es posible que quieras pregenerar las viñetas ya que las credenciales no se pueden utilizar en el servidor que genera la documentación.
+Antes de presentar y transferir tu paquete, puedes utilizar el enfoque documentado por pkgdown o el paquete tic para construir el sitio web de tu paquete automáticamente. Esto te ahorrará el trabajo de ejecutar (y acordarte de ejecutar) pkgdown::build_site() cada vez que haya que actualizar el sitio. Consulta nuestro capítulo sobre integración continua si ésto no te resulta familiar. En cualquier caso, no olvides actualizar la URL del sitio web en todos los lados donde aparezca después de hacer la transferencia a la organización ropensci.
Cuando tu paquete tenga muchas funciones, es conveniente que aparezcan agrupadas en el índice de la documentación, lo cual se puede hacer de forma más o menos automática.
+Si utilizas roxygen2 versión 6.1.1 o mayor, puedes utilizar la etiqueta @family en la documentación de tus funciones para indicar un grupo al que pertenecen. Esto generará enlaces las funciones en la documentación local del paquete instalado (en la sección “See also”) y te permitirá utilizar la función has_concept de pkgdown en el archivo de configuración de tu sitio web. Puedes ver un ejemplo (de un paquete no perteneciente a rOpenSci) cortesía de optiRum: etiqueta family, archivo de configuración de pkgdown y la sección en el índice resultante. Para personalizar el texto del título de la referencia cruzada creada por roxygen2 (Other {family}:), puedes consultar la documentación de roxygen2 sobre cómo proporcionar una lista rd_family_title en man/roxygen/meta.R.
Menos automáticamente, puedes ver el sitio web de drake y el archivo de configuración asociado como ejemplo.
Una vez que tu paquete sea transferido y obtenga un sitio web utilizando nuestra plantilla de pkgdown, si quieres utilizar Mathjax tendrás que especificarlo en el archivo de configuración de pkgdown de la siguiente manera
template:
+ params:
+ mathjax: truePara utilizar el logo de tu paquete en la página de inicio de pkgdown, consulta usethis::use_logo(). Si tu paquete no tiene ningún logotipo, el generador de documentación de rOpenSci utilizará el logo de rOpenSci en su lugar.
El paquete debe tener una licencia aceptada por CRAN u OSI. Para más detalles sobre las licencias, consulta el libro R packages.
+Todos los paquetes deben aprobar R CMD check/devtools::check() en las plataformas principales.
Todos los paquetes deben tener un conjunto de tests que cubran la funcionalidad principal del paquete. Los tests deben cubrir también el comportamiento del paquete en caso de error.
Es una buena práctica escribir tests unitarios para todas las funciones, y para todo el código del paquete en general, asegurando que se cubra las funcionalidades clave. Si la cobertura de los tests en tu paquete está por debajo del 75% probablemente requerirá tests adicionales o una explicación de la baja cobertura antes de ser enviado para su revisión.
Recomendamos utilizar testthat para escribir los tests. Intenta escribir tests a medida que escribas cada nueva función. Esto responde a la necesidad obvia de tener tests adecuados para el paquete, pero te permite pensar en varias formas en las que una función puede fallar, y programar defensivamente contra esas fallas. Más información sobre tests.
Los tests deben ser fáciles de entender. Te sugerimos que leas el artículo de blog Why Good Developers Write Bad Unit Tests (Por qué las personas que son buenas desarrollando escriben malos tests) de Michael Lynch.
Los paquetes con aplicaciones Shiny deberán generar tests unitarios usando shinytest2 o shinytest para comprobar que las interfaces interactivas funcionan como es esperado.
Para testear las funciones que crean gráficos, sugerimos utilizar vdiffr, una extensión del paquete testthat que esta basada en tests con instantáneas de testthat.
Si tu paquete interactúa con recursos web (APIs web y otras fuentes de datos en la web) el libro HTTP testing in R (Testeando HTTP en R) de Scott Chamberlain y Maëlle Salmon puede resultarte relevante. Algunos paquetes que ayudan a realizar tests HTTP (y sus clientes HTTP correspondientes) son:
+ +El paquete testthat tiene una función skip_on_cran() que puedes utilizar para que algunos tests no se ejecuten en CRAN. Recomendamos utilizarla en todas las funciones que tengan llamadas a APIs web, ya que es muy probable que fallen en CRAN. Estos tests deberán ejecutarse en la integración continua. Ten en cuenta que a partir de testthat 3.1.2, skip_if_offline() llama automáticamente a skip_on_cran(). Más información en CRAN preparedness for API wrappers (Preparación en CRAN para utilización de APIs).
Si tu paquete interactúa con una base de datos, dittodb puede resultarte útil.
Una vez que hayas configurado la integración continua (CI), utiliza el informe de cobertura de tu paquete (revisa esta sección de nuestro libro) para identificar las líneas no testeadas y añadir más tests.
Dado que a menudo algunos tests se omiten en la integración continua, te recomendamos asegurarte de que todos se ejecuten antes de enviar tu paquete ejecutándolos localmente (puede que tengas que establecer Sys.setenv(NOT_CRAN="true")).
Incluye ejemplos extensos en la documentación. Además de demostrar cómo se utiliza el paquete, pueden ser una forma fácil de testear la funcionalidad del paquete antes de que haya tests adecuados. Sin embargo, ten en cuenta que exigimos tests en los paquetes contribuidos.
Puedes ejecutar los ejemplos con devtools::run_examples(). Ten en cuenta que los ejemplos que no estén rodeados de \dontrun{} o \donttest{} serán ejecutados cuando ejecutes R CMD CHECK o su equivalente (por ejemplo, devtools::check()). Consulta la tabla de resumen en la documentación de roxygen2.
Para evitar que los ejemplos se ejecuten en CRAN (por ejemplo, si requieren autenticación), tienes que utilizar \dontrun{}. Sin embargo, para un primer envío, CRAN no te permitirá saltearte todos los ejemplos. En este caso puedes añadir algunos pequeños ejemplos de juguete, o encapsular el código de los ejemplos en try(). Consulta también la etiqueta @exampleIf, que al momento de escribir este artículo, se encuentra en la versión de desarrollo de roxygen2.
Además de ejecutar los ejemplos localmente en tu propia computadora, te aconsejamos fuertemente que ejecutes los ejemplos en uno de los sistemas de integración continua. De nuevo, se ejecutarán los ejemplos que no estén incluidos en \dontrun{} o \donttest{}. Puedes configurar la integración continua para que éstos se ejecuten a través de los argumentos de R CMD --run-dontrun y/o --run-donttest.
Pensa en las ventajas y desventajas de depender de un paquete. Por un lado, las dependencias reducen el esfuerzo de desarrollo, y permite construir en base a funcionalidades útiles desarrolladas por otras personas, especialmente si la dependencia realiza tareas complejas, es de alto rendimiento y/o está bien revisada y probada. Por otro lado, tener muchas dependencias supone una carga de mantenimiento ya que requiere estar al día con los cambios en esos paquetes, con riesgo para la sostenibilidad de tu paquete a largo plazo. También aumenta el tiempo y el tamaño de la instalación, lo que supone principalmente una consideración en el ciclo de desarrollo tuyo y del resto, y en los sistemas de compilación automatizados. Los paquetes “pesados” -los que tienen muchas dependencias, y los que tienen grandes cantidades de código compilado- aumentan este costo. He aquí algunos enfoques para reducir las dependencias:
+Si sólo utilizas unas pocas funciones de una dependencia grande o pesada, puedes copiarlas en tu propio paquete. (Ver la sección Autoría para saber cómo reconocer la autoría del código copiado). Por otro lado, las funciones complejas con muchos casos especiales (por ejemplo, los analizadores sintácticos) requieren considerable testeo y revisión.
+Un ejemplo común de esto es devolver “tibbles” usadas por el tidyverse en las funciones del paquete que proporcionan datos. Se puede evitar el uso del paquete tibble devolviendo un tibble creado modificando un data.frame de la siguiente manera
+class(df) <- c("tbl_df", "tbl", "data.frame") (Ten en cuenta que este enfoque no está universalmente aceptado.)
+Asegúrate de que utilizas la función del paquete donde está definida originalmente y no de un paquete que la re-exporta. Por ejemplo, muchas funciones de devtools pueden encontrarse en paquetes especializados más pequeños, como sessioninfo. La función %>% debe importarse de magrittr donde está definida, en lugar de dplyr que la reexporta y es mucho más pesado.
Algunas dependencias proporcionan nombres de funciones y sintaxis más fáciles de interpretar que los nombres de las funciones y la sintaxis de R base. Si ésta es la razón principal para usar una función en una dependencia pesada, considera incluir el código de R base en una función interna bien nombrada en tu paquete. Consulta, por ejemplo, el script de R de rlang que proporciona funciones con una sintaxis similar a las funciones de purrr.
Si las dependencias tienen funcionalidades redundantes, considera depender de una sola en lo posible.
Puedes encontrar más consejos sobre la gestión de dependencias en [el capítulo “Dependencies: Mindset and Background” (Dependencias: Mentalidad y Contexto) del libro “R packages” y en este artículo de Scott Chamberlain (en Inglés).
Utiliza la sección Imports en lugar de Depends para listar los paquetes cuyas funciones usas en tu paquete. Utiliza sección Suggests para listar los paquetes que usas en los tests (testthat), y para generar la documentación (knitr, roxygen2) (si utilizas usethis para añadir la infraestructura de tests con usethis::use_testthat() o una viñeta mediante usethis::use_vignette() los paquetes necesarios se añadirán a DESCRIPTION). Si utilizas algún paquete en los ejemplos o tests de tu paquete, asegúrate de listarlo en Suggests si no aparece ya en Imports.
Si tu paquete no está en Bioconductor pero depende de paquetes de Bioconductor, asegúrate de que las instrucciones de instalación en el README y la viñeta sean lo suficientemente claras incluso para una persona que no esté familiarizada con el ciclo de publicación de Bioconductor.
+¿Hay que usar BiocManager (recomendado)? Documenta esto.
¿La instalación automática de paquetes de Bioconductor con install.packages() es suficiente? En ese caso, menciona que se debe ejecutar setRepositories() si aún no han configurado los repositorios de Bioconductor necesarios.
Si tu paquete depende de Bioconductor a partir de una determinada versión, menciónalo en el archivo DESCRIPTION y en las instrucciones de instalación.
Especificar las dependencias mínimas (por ejemplo glue (>= 1.3.0) en lugar de sólo glue) debería ser una elección deliberada. Si sabes con certeza que tu paquete se romperá con una dependencia debajo de una determinada versión, especifícalo explícitamente. Pero si no lo sabes, no es necesario especificar una dependencia mínima. En ese caso, puedes agregarlo si una persona informa de un fallo que está explícitamente relacionado con una versión antigua de una dependencia. Considerar las versiones de paquetes locales como la versiones mínimas necesarias para las dependencias es una mala práctica. Eso obligaría a todo el mundo a actualizar las dependencias innecesariamente (causando problemas con otros paquetes) cuando no hay una buena razón detrás de esa elección de versiones.
En la mayoría de los casos en los que debes exponer funciones que vienen de otros paquetes, debes importar y reexportar esas funciones individuales en lugar de listarlos en el campo Depends. Por ejemplo, si las funciones de tu paquete producen objetos raster puedes reexportar, del paquete raster, sólo las funciones de impresión y graficado.
Si tu paquete utiliza una dependencia de sistema, debes
+Indicarla en el archivo DESCRIPTION;
Comprobar que aparece en la lista de sysreqsdb para permitir que las herramientas automáticas lo instalen, o enviar una contribución si no es así;
Comprobar que está instalada usando un script configure (ejemplo) y devolver un mensaje de error útil si no se la encuentra (ejemplo). Los scripts configure pueden ser difíciles de escribir, ya que a menudo requieren soluciones rebuscadas para asegurarse de que dependencias del sistema muy distintas funcionen en todos los sistemas. Utiliza ejemplos como punto de partida (más aquí), pero ten en cuenta que es habitual encontrar errores y casos límite y que a menudo violan las políticas de CRAN. No dudes en pedir ayuda en nuestro foro.
Para las consultas HTTP recomendamos utilizar httr2, httr, curl, crul, en vez de RCurl. El paquete curl es mejor si prefieres los clientes de bajo nivel de HTTP, mientras que httr2, httr o crul son mejores para un control de nivel más alto.
Para parsear JSON, utiliza jsonlite en lugar de rjson o RJSONIO.
Para parsear, crear y manipular XML, recomendamos fuertemente xml2 en la mayoría de los casos. Puedes consultar las notas de Daniel Nüst sobre la migración de XML a xml2 (en Inglés).
Para datos espaciales, el paquete sp debe considerarse obsoleto en favor de sf. Los paquetes rgdal, maptools y rgeos se retirarán a finales de 2023. Recomendamos el uso de las suites espaciales desarrolladas por las comunidades r-spatial y rspatial. Consulta este issue de GitHub para ver las discusiones pertinentes.
Los archivos fuente de tu paquete tienen que estar bajo control de versiones, más concretamente versionados con Git. Puede que el paquete gert te resulte útil, así como algunas de las funciones de usethis relacionadas con Git/GitHub; sin embargo, puedes utilizar git como quieras.
Asegúrate de listar archivos innecesarios, como .DS_Store, en .gitignore. La función usethis::git_vaccinate(), y el paquete gitignore pueden resultarte útil para esto.
Una sección posterior de este libro incluye algunos consejos sobre el flujo de trabajo con git.
Esta es una colección de problemas en CRAN que vale la pena evitar desde el principio.
+pkgdown para saber cómo anular esta restricción.Description de tu archivo DESCRIPTION. Las URL deben ir entre simbolos <>, por ejemplo <https://www.r-project.org>.Title como en Description los nombres de los paquetes u otro software externo deben ir entre comillas simples (por ejemplo Integración de ‘Rcpp’ para la Biblioteca de Álgebra Lineal Armadillo).testthat::skip_on_cran() en los test que toman mucho tiempo para que se omitan en CRAN pero sigan corriendo localmente y en la integración continua.paper.md y archivos de configuración de integración continua, en tu archivo .Rbuildignore.Para más consejos, consulta la lista colaborativa mantenida por ThinkR, “Prepárate para CRAN”.
+Una vez que tu paquete esté en CRAN, será comprobado regularmente en diferentes plataformas. Los fallos de estas comprobaciones, cuando no son falsos positivos, pueden hacer que el equipo de CRAN se ponga en contacto contigo. Puedes revisar el estado de las comprobaciones de CRAN con:
+el paquete foghorn.
Si deseas que tu paquete se envíe a Bioconductor, o si tu paquete está en Bioconductor, consulta las Directrices de paquetes de Bioconductor y el libro de desarrollo actualizado.
+Si envías un paquete a rOpenSci a través del repo de software-review puedes dirigir tus preguntas al equipo de rOpenSci a través de issues o en nuestro foro de discusión.
Lee la guía para quienes crean paquetes.
Lee, incorpora y actúa según los consejos del capítulo Guía de Colaboración.
R Packages (Paquetes de R) de Hadley Wickham y Jenny Bryan es un recurso excelente y fácil de leer sobre el desarrollo de paquetes que está disponible gratis en línea (y se puede comprar impreso).
Writing R Extensions (Escribiendo extensiones de R) es la referencia canónica y normalmente más actualizada, para crear paquetes de R.
Tidyverse design guide (guía de diseño del equipo tidyverse) (trabajo en elaboración) con su boletín de noticias.
Algunos posts del blog de rOpenSci por ejemplo “How to precompute package vignettes or pkgdown articles” (Cómo pregenerar viñetas de paquetes o artículos de pkgdown).
Sección El rincón del desarrollo de paquetes del boletín de rOpenSci.
Algunos posts del blog de tidyverse por ejemplo “Upgrading to testthat edition 3” (Actualizando a la 3ra edición de testthat).
Existe una especialización en Coursera correspondiente al libro de Roger Peng, Sean Kross y Brooke Anderson con un curso específico sobre paquetes de R.
+ + ++Este capítulo explica qué es la integración continua (CI, por sus siglas en inglés) y luego resume nuestras recomendaciones sobre cómo usarla. +
++Junto con el capítulo anterior, forma parte de nuestras directrices para la revisión por pares de software. +
+La integración continua ejecuta tests sobre el software automáticamente. En el caso de rOpenSci, CI significa, en la práctica, que un conjunto de test se ejecutará automáticamente a través de GitHub, cada vez que hagas un commit o pull request a GitHub.
+La CI automatiza la ejecución de tests globales de los paquetes, como R CMD check (ver tests). Es posible configurar la CI antes de escribir tus tests, entonces CI los ejecutará a medida que los envíes al repositorio.
Todos los paquetes de rOpenSci deben utilizar alguna forma de integración continua. Esto asegura que todos los commits, pull requests y nuevas branches pasan por R CMD check. Los resultados de todos los tests se muestran en la página del pull request en GitHub, lo cual proporciona información sobre los problemas y proteje de aceptar cambios que rompan tu paquete. La integración continua de los paquetes de rOpenSci también debe estar vinculada a un servicio de cobertura de código que indique cuántas líneas son chequeadas por los tests unitarios.
Tanto el estado de los tests como el porcentaje de cobertura del código deben informarse mediante etiquetas en el README de tu paquete.
+Los paquetes de R deben tener CI para todos los sistemas operativos (Linux, Mac OSX, Windows) si contienen:
+Código compilado
Dependencias de Java
Dependencias de otros lenguajes
Paquetes con llamadas al sistema
Procesamiento de texto, por ejemplo obtener nombres de personas (para encontrar problemas de codificación).
Cualquier cosa que incluya llamadas al sistema de archivos / rutas de acceso.
Ante la duda de si estos criterios se aplican a tu paquete, es mejor añadir CI para todos los sistemas operativos. La mayoría de los servicios de CI para paquetes de R lo permiten sin mucha complicación utilizando la configuración estándar.
+Existen muchos servicios de integración continua. Algunos son servicios independientes (CircleCI, AppVeyor), mientras que otros están integrados a servicios de alojamiento del código o relacionados (GitHub Actions, GitLab, AWS Code Pipeline). Distintos servicios permiten distintas configuraciones de sistemas operativos.
+GitHub Actions es una opción conveniente para quienes desarrollan paquetes de R y ya utilizan GitHub, ya que está integrado en la plataforma y es compatible con todos los sistemas operativos necesarios.
+Hay acciones compatibles con el ecosistema R así como soporte de primera clase con el paquete usethis. Todos los paquetes enviados a rOpenSci para su revisión por pares son comprobados por nuestro propio sistema, pkgcheck, el cual se describe con más detalle en la Guía de autoría. Estos tests también están disponibles como acción de GitHub en el repositorio ropensci-review-tools/pkgcheck-action. Es recomendable utilizar esta acción para confirmar que el paquete pasa todos los tests antes de enviarlo. Consulta nuestro blog para más información.
El paquete usethis se puede usar con otros sistemas de CI, aunque estas funciones están siendo deprecadas. rOpenSci también provee el paquete circle, el cual ayuda a configurar cadenas de CircleCI, y el paquete tic para la construcción de cadenas de CI más complicadas.
+Requerimos que los paquetes de rOpenSci no sólo se testeen usando la versión más reciente de R, sino también con la anterior y con la versión en desarrollo. Esto garantiza compatibilidad con R base, tanto con versiones futuras como con versiones pasadas.
+Los detalles de cómo ejecutar tests utilizando diferentes versiones de R localmente se pueden encontrar en la viñeta de R-hub sobre la ejecución de Checks locales en Linux con Docker.
+Puedes definir los detalles de los checks para cada una de las versiones utilizando una matriz de tests.
+Si desarrollas un paquete que depende o está destinado para Bioconductor, puede que el paquete biocthis te resulte relevante.
+Puedes utilizar estos consejos para minimizar los tiempos de construcción en CI:
+Puede que encuentres útil el post de Hugo Gruson Dependencias del sistema en paquetes de R y pruebas automáticas.
+Recomendamos dejar de utilizar Travis.
+Para la integración continua en Windows, consulta R + AppVeyor. Configúralo con usethis::use_appveyor().
Aquí tienes consejos para minimizar el tiempo de compilación de AppVeyor:
+Guarda los paquetes instalados en una caché. Mira, por ejemplo, este archivo de configuración. AppVeyor usará la caché automáticamente si lo configuras con usethis::use_appveyor().
Activa los rolling builds.
Ya no transferimos los proyectos de AppVeyor a la cuenta de AppVeyor de rOpenSci, así que después de transferir tu repo a la organización de GitHub “ropensci”, la etiqueta será [](https://ci.appveyor.com/project/individualaccount/pkgname).
Circle CI es utilizado, por ejemplo, por el paquete de rOpenSci bomrang como servicio de integración continua.
La integración continua también debe incluir información sobre la cobertura de los tests a través de un servicio de testing como Codecov o Coveralls.
+Recomendamos utilizar Codecov. Para activar Codecov para tu repo, ejecuta usethis::use_github_action("test-coverage"), el cual crea un archivo .github/workflows/test-coverage.yaml. También tienes que dar acceso a Codecov a tu repositorio de GitHub, ver la guía de inicio rápido de Codecov (en inglés) para saber cómo hacerlo. Luego añade una etiqueta de estado de Codecov en la parte superior de tu README.md, puedes consultar Status Badges (etiquetas de estado) en la documentación de Codecov.
Actualmente, Codecov tiene acceso a todos los repositorios de GitHub de la organización ropensci por defecto. Cuando tu repositorio sea aceptado y transferido a ropensci, el acceso de Codecov debería transferirse automáticamente. Tendrás que actualizar la URL de la etiqueta para que apunte al repositorio alojado en ropensci.
+Para más detalles, consulta el README del paquete covr, así como la documentación de usethis::use_coverage() y usethis::use_github_action().
Si ejecutas la cobertura en varios servicios de CI los resultados se unirán.
+Después de transferir el repo a la organización GitHub “ropensci” de rOpenSci, cada push se chequeará en OpenCPU y la persona que hace el commit recibirá una notificación por correo electrónico. Este es un servicio adicional de CI para que permite correr funciones en paquetes de R de forma remota a través de https://ropensci.ocpu.io/ utilizando la API de opencpu. Para más detalles sobre este servicio, consulta la página de ayuda de OpenCPU que también indica dónde hacer preguntas.
+Después de la transferencia a la organización GitHub “ropensci” de rOpenSci, cada push al repo de GitHub disparará la construcción (o actualización) del sitio web de tu paquete usando pkgdown. Puedes encontrar el estado de este proceso en la URL https://ropensci.r-universe.dev/ui#packages y en el estado del commit. El sitio web estará en https://docs.ropensci.org/package_name (por ejemplo para magick). Si tu paquete tiene un archivo de configuración de pkgdown, rOpenSci docs lo usará para crear el sitio web, excepto para el tema, que se utilizará rotemplate paquete.
Por favor, informa sobre errores, haz preguntas y solicita nuevas funcionalidades sobre este servicio y sobre la plantilla en https://github.com/ropensci-org/rotemplate/.
+ + ++Este es un capítulo en construcción que incluye consejos sobre la gestión de información confidencial en los paquetes y enlaces a lecturas adicionales. +
+Recomendamos el artículo Ten quick tips for staying safe online (Diez consejos rápidos sobre seguridad en Internet) de Danielle Smalls y Greg Wilson.
+Te recomendamos proteger tu cuenta de GitHub con autenticación de dos factores (2FA). Esto es obligatorio para miembros de la organización ropensci en GitHub y quienes colaboren de manera externa, así que asegúrate de habilitarla antes de que se apruebe tu paquete.
También te recomendamos que compruebes regularmente quién tiene acceso al repositorio de tu paquete, y que elimines cualquier acceso no utilizado (como el de personas que hayan dejado de colaborar).
Esta sección incluye consejos para cuando desarrolles un paquete que interactúa con un recurso web que requiere credenciales (claves API, tokens, etc.). Consulta también la viñeta de httr sobre compartir credenciales.
Supongamos que tu paquete necesita una clave para hacer consultas a una API en nombre de quien usa el paquete.
+En la documentación de tu paquete, brinda consejos para que la clave de la API no se almacene en el archivo .Rhistory o en los scripts.
+Fomenta el uso de variables de entorno para almacenar la clave de la API (o incluso elimina la posibilidad de pasarla como argumento a las funciones). Puedes mencionar esta introducción a los archivos de arranque y la función usethis::edit_r_environ().
Otra posibilidad es usar o fomentar el uso del paquete keyring para almacenar variables en los sistemas de almacenamiento de credenciales del sistema operativo (que son más seguros que guardarlas en el archivo .Renviron). Para esto tu paquete tendría una función para guardar la clave en el keyring y una para recuperarla; alternativamente quien use tu paquete podría escribir Sys.setenv(CLAVESUPERSECRETA = keyring::key_get("miservicio")) al principio de su script.
No imprimas la clave de la API en ningún mensaje, advertencia o error, ni siquiera en modo verboso.
La plantilla de issues en GitHub debe advertir de no compartir ninguna credencial. Si alguien comparte accidentalmente las credenciales en un issue, asegúrate de avisarle para que revoque la clave (es decir, pregúntale explícitamente si se ha dado cuenta de que ha compartido su clave).
Durante el desarrollo del paquete tendrás que proteger tus credenciales igual que proteges las credenciales de quienes usan tu paquete, pero hay más cosas a considerar y tener en cuenta.
+Si utilizas vcr o httptest en los test para almacenar las respuestas de la API en caché, tienes que asegurarte de que las consultas grabadas o fixtures no contengan credenciales. Consulta la guía de seguridad de vcr y la guía Redacting and Modifying Recorded Requests (Censurando y modificando consultas grabadas) de httptest e inspecciona tus consultas grabadas y fixtures antes de hacer un primer commit para asegurarte de que tienes la configuración correcta.
Como vcr es un paquete de rOpenSci, puedes hacer cualquier pregunta que tengas en el foro de rOpenSci.
¿Qué pasa con los pull requests de contribuciones externas? En GitHub, por ejemplo, los “secretos” sólo están disponibles para las acciones de GitHub para los pull requests iniciados desde el propio repositorio, no desde el fork. Los test que utilicen tus credenciales fallarán a menos que utilices algún tipo de respuesta simulada/en caché, por lo que es posible que quieras omitirlos dependiendo del contexto. Por ejemplo, en tu cuenta CI podrías crear una variable de entorno llamada ESTE_SOY_YO y luego omitir los test en función de la presencia de esta variable. Obviamente, esto significa que los tests del PR por parte del servicio de CI no serán exhaustivos, por lo que tendrás que comprobar el PR localmente para ejecutar todos los tests.
Documenta el comportamiento de tu paquete frente a PRs externos en CONTRIBUTING.md por el bien de la gente que hace PRs y de la gente que los revisa (tú dentro de unas semanas, y otras personas que mantengan del paquete).
+En CRAN, omite las pruebas y los ejemplos que requieran credenciales utilizando skip_on_cran() y dontrun respectivamente.
También omite las viñetas que requieran credenciales.
+Recursos útiles sobre seguridad:
+Encuentro de la comunidad rOpenSci sobre “Seguridad para R” (grabación, diapositivas, etc.). Ver en particular la lista de recursos;
el artículo de gargle Managing tokens securely (Gestionando claves de forma segura)
¡Te damos la bienvenida! Este libro es una guía para quienes desarrollan y mantienen paquetes y quienes revisan y editan envíos de paquetes a rOpenSci.
+La primera sección del libro contiene nuestras recomendaciones para crear y testear los paquetes de R.
+La segunda sección está dedicada al proceso de revisión por pares de software de rOpenSci: en qué consiste, nuestras políticas y las guías específicas para orientar a quienes crean, mantienen, revisan y editan a lo largo del proceso. Para la revisión de software estadístico, consulta la página web del proyecto y los recursos asociados.
+La tercera y última sección presenta nuestras buenas prácticas para hacer crecer tu paquete una vez que ha sido incorporado a rOpenSci: cómo colaborar con otras personas, cómo documentar cada versión, cómo promover tu paquete y cómo aprovechar GitHub como plataforma de desarrollo. La tercera sección también incluye un capítulo para quienes desean comenzar a contribuir a los paquetes de rOpenSci.
+Esperamos que esta guía te resulte útil y clara, y agradecemos tus sugerencias en las issues del libro. ¡Mucho éxito desarrollando paquetes de R!
+El equipo editorial de rOpenSci.
+Este libro es un documento vivo. Puedes ver las actualizaciones de nuestras buenas prácticas y políticas a través de las notas de cada versión.
+Puedes citar este libro utilizando sus metadatos de Zenodo y su DOI.
Em Markowitz (NOAA) · Sam Albers · Toph Allen · Kaique dos S. Alves · Brooke Anderson · Alison Appling · Denisse Fierro Arcos · Zebulun Arendsee · Taylor Arnold · Al-Ahmadgaid B. Asaad · Dean Attali · Mara Averick · Suzan Baert · James Balamuta · Vikram Baliga · David Bapst · Joëlle Barido-Sottani · Allison Barner · Cale Basaraba · John Baumgartner · Marcus Beck · Gabriel Becker · Jason Becker · Salvador Jesus Fernandez Bejarano · Dom Bennett · Ken Benoit · Aaron Berdanier · Fred Boehm · Carl Boettiger · Will Bolton · Ben Bond-Lamberty · Anne-Sophie Bonnet-Lebrun · Alison Boyer · Abby Bratt · François Briatte · Eric Brown · Julien Brun · Jenny Bryan · Lukas Burk · Lorenzo Busetto · Maria Paula Caldas · Mario Gavidia Calderón · Carlos Cámara-Menoyo · Brad Cannell · Joaquin Cavieres · Kevin Cazelles · Scott Chamberlain · Cathy Chamberlin · Jennifer Chang · Pierre Chausse · Jorge Cimentada · Nicholas Clark · Chase Clark · Jon Clayden · Dena Jane Clink · Will Cornwell · Nic Crane · Enrico Crema · Verónica Cruz-Alonso · Ildiko Czeller · Tad Dallas · Kauê de Sousa · Christophe Dervieux · Amanda Dobbyn · Jasmine Dumas · Dewey Dunnington · Remko Duursma · Mark Edmondson · Paul Egeler · Evan Eskew · Harry Eslick · Alexander Fischer · Kim Fitter · Robert M Flight · Sydney Foks · Stephen Formel · Zachary Stephen Longiaru Foster · Auriel Fournier · Kaija Gahm · Zach Gajewski · Carl Ganz · Duncan Garmonsway · Jan Laurens Geffert · Sharla Gelfand · Monica Gerber · Duncan Gillespie · David Gohel · A. Cagri gokcek · Guadalupe Gonzalez · Rohit Goswami · Laura Graham · Charles Gray · Matthias Grenié · Corinna Gries · Hugo Gruson · Ernest Guevarra · W Kyle Hamilton · Ivan Hanigan · Jeffrey Hanson · Liz Hare · Jon Harmon · Rayna Harris · Ted Hart · Nujcharee Haswell · Verena Haunschmid · Stephanie Hazlitt · Andrew Heiss · Max Held · Anna Hepworth · Bea Hernandez · Jim Hester · Peter Hickey · Roel Hogervorst · Kelly Hondula · Allison Horst · Sean Hughes · James Hunter · Brandon Hurr · Ger Inberg · Christopher Jackson · Najko Jahn · Tamora D James · Veronica Jimenez-Jacinto · Mike Johnson · Will Jones · Max Joseph · Megha Joshi · Krunoslav Juraic · Soumya Kalra · Zhian N. Kamvar · Michael Kane · Andee Kaplan · Tinula Kariyawasam · Hazel Kavılı · Jonathan Keane · Christopher T. Kenny · Os Keyes · Eunseop Kim · Aaron A. King · Michael Koontz · Bianca Kramer · Will Landau · Sam Lapp · Erin LeDell · Thomas Leeper · Sam Levin · Lisa Levinson · Stephanie Locke · Marion Louveaux · Robin Lovelace · Julia Stewart Lowndes · Tim Lucas · Muralidhar, M.A. · Andrew MacDonald · Jesse Maegan · Mike Mahoney · Tristan Mahr · Yohann Mansiaux · Paula Andrea Martinez · Anthony Martinez · Joao Martins · Ben Marwick · Claire Mason · Miles McBain · Lucy D’Agostino McGowan · Amelia McNamara · Elaine McVey · Bryce Mecum · Nolwenn Le Meur · François Michonneau · Mario Miguel · Helen Miller · Beatriz Milz · Jessica Minnier · Priscilla Minotti · Nichole Monhait · Kelsey Montgomery · Ronny A. Hernández Mora · Paula Moraga · Natalia Morandeira · George Moroz · Ross Mounce · Athanasia Monika Mowinckel · Lincoln Mullen · Matt Mulvahill · Maria Victoria Munafó · David Neuzerling · Dillon Niederhut · Joel Nitta · Rory Nolan · Kari Norman · Jakub Nowosad · Matt Nunes · Daniel Nüst · Lauren O’Brien · Joseph O’Brien · Paul Oldham · Samantha Oliver · Dan Olner · Jeroen Ooms · Victor Ordu · Luis Osorio · Philipp Ottolinger · Mark Padgham · Marina Papadopoulou · Edzer Pebesma · Thomas Lin Pedersen · Antonio J. Pérez-Luque · Marcelo S. Perlin · Rafael Pilliard-Hellwig · Rodrigo Neto Pires · Lindsay Platt · Nicholas Potter · Joanne Potts · Josep Pueyo-Ros · Etienne Racine · Manuel Ramon · Nistara Randhawa · David Ranzolin · Quentin Read · Neal Richardson · tyler rinker · Emily Robinson · David Robinson · Alec Robitaille · Francisco Rodriguez-Sanchez · Sam Rogers · Julia Romanowska · Xavier Rotllan-Puig · Bob Rudis · Edgar Ruiz · Kent Russel · Michael Sachs · Sheila M. Saia · Chitra M Saraswati · Alicia Schep · Klaus Schliep · Clemens Schmid · Patrick Schratz · Collin Schwantes · Marco Sciaini · Eric Scott · Heidi Seibold · Julia Silge · Margaret Siple · Peter Slaughter · Mike Smith · Tuija Sonkkila · Øystein Sørensen · Jemma Stachelek · Christine Stawitz · Irene Steves · Kelly Street · Matt Strimas-Mackey · Alex Stringer · Michael Sumner · Chung-Kai Sun · Sarah Supp · Emi Tanaka · Jason Taylor · Filipe Teixeira · Andy Teucher · Jennifer Thompson · Joe Thorley · Nicholas Tierney · Tiffany Timbers · Tan Tran · Tim Trice · Utku Turk · Zoë Turner · Kyle Ueyama · Ted Underwood · Adithi R. Upadhya · Kevin Ushey · Josef Uyeda · Frans van Dunné · Mauricio Vargas · Remi Vergnon · Jake Wagner · Ben Ward · Elin Waring · Rachel Warnock · Leah Wasser · David Watkins · Lukas Weber · Marc Weber · Karissa Whiting · Stefan Widgren · Anna Willoughby · Saras Windecker · Luke Winslow · David Winter · Sebastian Wójcik · Witold Wolski · Kara Woo · Marvin N. Wright · Jacob Wujciak-Jens · Bruna Wundervald · Lauren Yamane · Emily Zabor · Taras Zakharko · Sherry Zhang · Hao Zhu · Chava Zibman · Naupaka Zimmerman · Jake Zwart · Felipe · santikka · kasselhingee · Bri · Flury · Vincent · eholmes · Pachá · Rich · Claudia · Jasmine · Zack · Lluís · becarioprecario · gaurav
+Si quieres contribuir sugerencias o correcciones a este libro, visita el repositorio de GitHub y, en particular, la guía de contribución. ¡Gracias!
+Agradecemos a quienes crean, mantienen, revisan y editan paquetes por ayudarnos a mejorar el sistema y esta guía a lo largo de los años. Gracias también a las siguientes personas que han contribuido a esta guía y a sus versiones anteriores: Katrin Leinweber, John Baumgartner, François Michonneau, Christophe Dervieux, Lorenzo Busetto, Ben Marwick, Nicholas Horton, Chris Kennedy, Mark Padgham, Jeroen Ooms, Sean Hughes, Jan Gorecki, Joseph Stachelek, Dean Attali, Julia Gustavsen, Nicholas Tierney, Rich FitzJohn, Tiffany Timbers, Hilmar Lapp, Miles McBain, Bryce Mecum, Jonathan Carroll, Carl Boettiger, Florian Privé, Stefanie Butland, Daniel Possenriede, Hadley Wickham, Mauro Lepore, Matthew Fidler, Luke McGuinness, Aaron Wolen, Indrajeet Patil, Kevin Wright, Will Landau, Hugo Gruson,, Hao Ye,, Sébastien Rochette,, Edward Wallace,, Alexander Fischer,, Maxime Jaunatre,, Thomas Zwagerman.. Por favor, avísanos si nos olvidamos de reconocer tu contribución.
+ + + +Reemplaza el contenido del sitio web actual con sendos archivos index.html y 404.html. Ambos deben contener:
<html>
+<head>
+<meta http-equiv="refresh" content="0;URL=https://docs.ropensci.org/<nombrepaquete>/">
+</head>
+</html>Puedes configurar la redirección desde tu repositorio principal de GitHub Pages.
+https://github.com/<usuario>/<usuario>.github.io.<nombrepaquete> con dos archivos: index.html y 404.html. Ambos deben redireccionar a la nueva ubicación según lo visto en la sección anterior.https://<usuario>.github.io/<nombrepaquete>/index.html redirecciona a la dirección correcta.Quienes estén a cargo de la edición pueden utilizar la siguiente plantilla de correo electrónico para convocar personas para realizar la revisión.
+
+Estimado/a [REVISOR/A]
+
+Hola, soy [EDITOR/A]. [COMENTARIO AMISTOSO]. Te escribo para preguntarte si te interesa revisar un paquete para rOpenSci. Como probablemente sepas, rOpenSci lleva a cabo la revisión por pares de los paquetes de R aportados a nuestra colección de forma similar a las revistas científicas.
+
+El paquete, [PAQUETE] de [AUTOR(ES)], realiza [FUNCIÓN]. Puedes encontrarlo en GitHub aquí: [ENLACE REPO]. Hacemos nuestro proceso de revisión abierta a través de GitHub, aquí: [ISSUE DE REVISIÓN]
+
+Si aceptas, ten en cuenta que te pediremos completes las revisiones en tres semanas. (Hemos comprobado que lleva un tiempo similar revisar un paquete que un artículo académico).
+
+Nuestra [guía de revisión][guía de revisión] detalla lo que buscamos en la revisión de un paquete, e incluye enlaces a ejemplos de revisiones. Nuestras normas se detallan en nuestra [guía de empaquetado][guía de empaquetado] y proporcionamos una [plantilla][plantilla] para que la utilices en revisión. Por favor, asegúrate de que no tienes un [conflicto de intereses](https://devguide.ropensci.org/policies.html#coi) que te impida revisar este paquete. Si tienes alguna pregunta o comentario, no dudes en preguntarme o enviar un mensaje a la sección del [foro de rOpenSci][foro de rOpenSci].
+
+La comunidad de rOpenSci es nuestro mejor activo.
+Nuestro objetivo es que las revisiones sean abiertas, no conflictivas y centradas en mejorar la calidad del software.
+¡Sé amable!
+Consulta nuestra guía de revisión y el [código de conducta](https://ropensci.org/code-of-conduct/) para más información.
+
+[SI SE SOLICITÓ TUTORÍA: Has indicado en tu formulario que te gustaría tener tutoría para tu primera revisión.
+Sientete libre de contactarme cuando lo necesites durante este proceso, lo que incluye hacer preguntas por correo electrónico y Slack (recibirás una invitación al Slack de rOpenSci), y compartir borradores de revisiones para recibir devoluciones antes de publicarlas.
+También me encantará hacer una breve videollamada para explicar el proceso. Por favor, házmelo saber en tu respuesta si quieres programar una.]
+
+¿Puedes revisar? Si no puedes, siempre nos sirve si puedes sugerir a otras personas. Si no tengo noticias tuyas en el plazo de una semana, supondré que no puedes hacer una revisión en este momento.
+
+Gracias por tu tiempo.
+
+Atentamente,
+
+[EDITOR/A]
+
+[guía de revisión]: https://devguide.ropensci.org/reviewerguide.html
+[guía de empaquetado]: https://devguide.ropensci.org/building.html
+[plantilla]: https://devguide.ropensci.org/reviewtemplate.html
+[foro de rOpenSci]: https://discuss.ropensci.org/
+
+Puedes guardar esto como un archivo R Markdown, o eliminar el YAML y guardarlo como un archivo Markdown.
+---
+title: "review"
+output:
+ rmarkdown::md_document:
+ pandoc_args: [
+ "--wrap=none"
+ ]
+---
+
+## Revisión de un paquete
+
+*Por favor trata de marcar tantas casillas como te sea posible y elabora tu opinión en tus comentarios. Tu revisión no está limitada a estos temas, tal como se describe en la guía de revisión.*
+
+**Describe cualquier relación de trabajo que tengas o hayas tenido con quienes que crearon el paquete**
+
+- [ ] Confirmo que no tengo [conflictos de interés](https://devguide.ropensci.org/policies.html#coi) para hacer la revisión de este trabajo (si no sabes si tienes un conflicto o no, por favor contáctate con la persona a cargo de la edición *antes de* de empezar con la revisión).
+
+#### Documentación
+
+El paquete incluye todos los siguientes tipos de documentación:
+
+- [ ] **Una declaración de necesidades** el archivo *README* que describa claramente los problemas que el software está diseñado para resolver y a quiénes está dirigido.
+- [ ] **Instrucciones de instalación** de la versión de desarrollo del paquete en el archivo *README*, incluyendo cualquier dependencia no estándar.
+- [ ] **Una o varias viñeta** que muestren la funcionalidad principal, que además corren localmente.
+- [ ] **Documentación de todas las funciones exportadas**.
+- [ ] **Ejemplos** (que corren localmente) de todas las funciones exportadas-
+- [ ] **Directrices comunitarias** incluyendo una guía de contribución en el archivo *README* o el archivo *CONTRIBUTING* y un archivo *DESCRIPTION* que incluye `URL`, `BugReports` y `Maintainer` (todos en inglés por convención y para que puedan ser autogenerados por `Authors@R`).
+
+#### Funcionalidad
+
+- [ ] **Instalación:** La instalación se completa con éxito tal como fue documentada.
+- [ ] **Funcionalidad:** Se confirmaron todas las afirmaciones de funcionalidad.
+- [ ] **Desempeño:** Se confirmaron todas las afirmaciones de desempeño.
+- [ ] **Pruebas automáticas:** Hay *tests* unitarios que cubren las funciones esenciales dentro del paquete con un rango razonable de entradas y condiciones. Todas las pruebas corren correctamente en la computadora local.
+- [ ] **Directrices de empaquetado:** El paquete cumple las directrices de empaquetado de rOpenSci.
+
+Estimación de horas dedicadas a la revisión:
+
+- [ ] Si quienes son responsables del paquete lo consideran apropiado, estoy de acuerdo en que se me reconozca en el archivo *DESCRIPTION* del paquete con rol de revisión ("rev").
+
+***
+
+### Comentarios de la revisión${missingFields[0]} field.`,
+ message: `The items being returned for this search do not include all the required fields. Please ensure that your index items include the ${missingFields[0]} field or use index-fields in your _quarto.yml file to specify the field names.`,
+ };
+ } else if (missingFields.length > 1) {
+ const missingFieldList = missingFields
+ .map((field) => {
+ return `${field}`;
+ })
+ .join(", ");
+
+ throw {
+ name: `Error: Search index is missing the following fields: ${missingFieldList}.`,
+ message: `The items being returned for this search do not include all the required fields. Please ensure that your index items includes the following fields: ${missingFieldList}, or use index-fields in your _quarto.yml file to specify the field names.`,
+ };
+ }
+ }
+}
+
+let lastQuery = null;
+function showCopyLink(query, options) {
+ const language = options.language;
+ lastQuery = query;
+ // Insert share icon
+ const inputSuffixEl = window.document.body.querySelector(
+ ".aa-Form .aa-InputWrapperSuffix"
+ );
+
+ if (inputSuffixEl) {
+ let copyButtonEl = window.document.body.querySelector(
+ ".aa-Form .aa-InputWrapperSuffix .aa-CopyButton"
+ );
+
+ if (copyButtonEl === null) {
+ copyButtonEl = window.document.createElement("button");
+ copyButtonEl.setAttribute("class", "aa-CopyButton");
+ copyButtonEl.setAttribute("type", "button");
+ copyButtonEl.setAttribute("title", language["search-copy-link-title"]);
+ copyButtonEl.onmousedown = (e) => {
+ e.preventDefault();
+ e.stopPropagation();
+ };
+
+ const linkIcon = "bi-clipboard";
+ const checkIcon = "bi-check2";
+
+ const shareIconEl = window.document.createElement("i");
+ shareIconEl.setAttribute("class", `bi ${linkIcon}`);
+ copyButtonEl.appendChild(shareIconEl);
+ inputSuffixEl.prepend(copyButtonEl);
+
+ const clipboard = new window.ClipboardJS(".aa-CopyButton", {
+ text: function (_trigger) {
+ const copyUrl = new URL(window.location);
+ copyUrl.searchParams.set(kQueryArg, lastQuery);
+ copyUrl.searchParams.set(kResultsArg, "1");
+ return copyUrl.toString();
+ },
+ });
+ clipboard.on("success", function (e) {
+ // Focus the input
+
+ // button target
+ const button = e.trigger;
+ const icon = button.querySelector("i.bi");
+
+ // flash "checked"
+ icon.classList.add(checkIcon);
+ icon.classList.remove(linkIcon);
+ setTimeout(function () {
+ icon.classList.remove(checkIcon);
+ icon.classList.add(linkIcon);
+ }, 1000);
+ });
+ }
+
+ // If there is a query, show the link icon
+ if (copyButtonEl) {
+ if (lastQuery && options["copy-button"]) {
+ copyButtonEl.style.display = "flex";
+ } else {
+ copyButtonEl.style.display = "none";
+ }
+ }
+ }
+}
+
+/* Search Index Handling */
+// create the index
+var fuseIndex = undefined;
+var shownWarning = false;
+
+// fuse index options
+const kFuseIndexOptions = {
+ keys: [
+ { name: "title", weight: 20 },
+ { name: "section", weight: 20 },
+ { name: "text", weight: 10 },
+ ],
+ ignoreLocation: true,
+ threshold: 0.1,
+};
+
+async function readSearchData() {
+ // Initialize the search index on demand
+ if (fuseIndex === undefined) {
+ if (window.location.protocol === "file:" && !shownWarning) {
+ window.alert(
+ "Search requires JavaScript features disabled when running in file://... URLs. In order to use search, please run this document in a web server."
+ );
+ shownWarning = true;
+ return;
+ }
+ const fuse = new window.Fuse([], kFuseIndexOptions);
+
+ // fetch the main search.json
+ const response = await fetch(offsetURL("search.json"));
+ if (response.status == 200) {
+ return response.json().then(function (searchDocs) {
+ searchDocs.forEach(function (searchDoc) {
+ fuse.add(searchDoc);
+ });
+ fuseIndex = fuse;
+ return fuseIndex;
+ });
+ } else {
+ return Promise.reject(
+ new Error(
+ "Unexpected status from search index request: " + response.status
+ )
+ );
+ }
+ }
+
+ return fuseIndex;
+}
+
+function inputElement() {
+ return window.document.body.querySelector(".aa-Form .aa-Input");
+}
+
+function focusSearchInput() {
+ setTimeout(() => {
+ const inputEl = inputElement();
+ if (inputEl) {
+ inputEl.focus();
+ }
+ }, 50);
+}
+
+/* Panels */
+const kItemTypeDoc = "document";
+const kItemTypeMore = "document-more";
+const kItemTypeItem = "document-item";
+const kItemTypeError = "error";
+
+function renderItem(
+ item,
+ createElement,
+ state,
+ setActiveItemId,
+ setContext,
+ refresh,
+ quartoSearchOptions
+) {
+ switch (item.type) {
+ case kItemTypeDoc:
+ return createDocumentCard(
+ createElement,
+ "file-richtext",
+ item.title,
+ item.section,
+ item.text,
+ item.href,
+ item.crumbs,
+ quartoSearchOptions
+ );
+ case kItemTypeMore:
+ return createMoreCard(
+ createElement,
+ item,
+ state,
+ setActiveItemId,
+ setContext,
+ refresh
+ );
+ case kItemTypeItem:
+ return createSectionCard(
+ createElement,
+ item.section,
+ item.text,
+ item.href
+ );
+ case kItemTypeError:
+ return createErrorCard(createElement, item.title, item.text);
+ default:
+ return undefined;
+ }
+}
+
+function createDocumentCard(
+ createElement,
+ icon,
+ title,
+ section,
+ text,
+ href,
+ crumbs,
+ quartoSearchOptions
+) {
+ const iconEl = createElement("i", {
+ class: `bi bi-${icon} search-result-icon`,
+ });
+ const titleEl = createElement("p", { class: "search-result-title" }, title);
+ const titleContents = [iconEl, titleEl];
+ const showParent = quartoSearchOptions["show-item-context"];
+ if (crumbs && showParent) {
+ let crumbsOut = undefined;
+ const crumbClz = ["search-result-crumbs"];
+ if (showParent === "root") {
+ crumbsOut = crumbs.length > 1 ? crumbs[0] : undefined;
+ } else if (showParent === "parent") {
+ crumbsOut = crumbs.length > 1 ? crumbs[crumbs.length - 2] : undefined;
+ } else {
+ crumbsOut = crumbs.length > 1 ? crumbs.join(" > ") : undefined;
+ crumbClz.push("search-result-crumbs-wrap");
+ }
+
+ const crumbEl = createElement(
+ "p",
+ { class: crumbClz.join(" ") },
+ crumbsOut
+ );
+ titleContents.push(crumbEl);
+ }
+
+ const titleContainerEl = createElement(
+ "div",
+ { class: "search-result-title-container" },
+ titleContents
+ );
+
+ const textEls = [];
+ if (section) {
+ const sectionEl = createElement(
+ "p",
+ { class: "search-result-section" },
+ section
+ );
+ textEls.push(sectionEl);
+ }
+ const descEl = createElement("p", {
+ class: "search-result-text",
+ dangerouslySetInnerHTML: {
+ __html: text,
+ },
+ });
+ textEls.push(descEl);
+
+ const textContainerEl = createElement(
+ "div",
+ { class: "search-result-text-container" },
+ textEls
+ );
+
+ const containerEl = createElement(
+ "div",
+ {
+ class: "search-result-container",
+ },
+ [titleContainerEl, textContainerEl]
+ );
+
+ const linkEl = createElement(
+ "a",
+ {
+ href: offsetURL(href),
+ class: "search-result-link",
+ },
+ containerEl
+ );
+
+ const classes = ["search-result-doc", "search-item"];
+ if (!section) {
+ classes.push("document-selectable");
+ }
+
+ return createElement(
+ "div",
+ {
+ class: classes.join(" "),
+ },
+ linkEl
+ );
+}
+
+function createMoreCard(
+ createElement,
+ item,
+ state,
+ setActiveItemId,
+ setContext,
+ refresh
+) {
+ const moreCardEl = createElement(
+ "div",
+ {
+ class: "search-result-more search-item",
+ onClick: (e) => {
+ // Handle expanding the sections by adding the expanded
+ // section to the list of expanded sections
+ toggleExpanded(item, state, setContext, setActiveItemId, refresh);
+ e.stopPropagation();
+ },
+ },
+ item.title
+ );
+
+ return moreCardEl;
+}
+
+function toggleExpanded(item, state, setContext, setActiveItemId, refresh) {
+ const expanded = state.context.expanded || [];
+ if (expanded.includes(item.target)) {
+ setContext({
+ expanded: expanded.filter((target) => target !== item.target),
+ });
+ } else {
+ setContext({ expanded: [...expanded, item.target] });
+ }
+
+ refresh();
+ setActiveItemId(item.__autocomplete_id);
+}
+
+function createSectionCard(createElement, section, text, href) {
+ const sectionEl = createSection(createElement, section, text, href);
+ return createElement(
+ "div",
+ {
+ class: "search-result-doc-section search-item",
+ },
+ sectionEl
+ );
+}
+
+function createSection(createElement, title, text, href) {
+ const descEl = createElement("p", {
+ class: "search-result-text",
+ dangerouslySetInnerHTML: {
+ __html: text,
+ },
+ });
+
+ const titleEl = createElement("p", { class: "search-result-section" }, title);
+ const linkEl = createElement(
+ "a",
+ {
+ href: offsetURL(href),
+ class: "search-result-link",
+ },
+ [titleEl, descEl]
+ );
+ return linkEl;
+}
+
+function createErrorCard(createElement, title, text) {
+ const descEl = createElement("p", {
+ class: "search-error-text",
+ dangerouslySetInnerHTML: {
+ __html: text,
+ },
+ });
+
+ const titleEl = createElement("p", {
+ class: "search-error-title",
+ dangerouslySetInnerHTML: {
+ __html: ` ${title}`,
+ },
+ });
+ const errorEl = createElement("div", { class: "search-error" }, [
+ titleEl,
+ descEl,
+ ]);
+ return errorEl;
+}
+
+function positionPanel(pos) {
+ const panelEl = window.document.querySelector(
+ "#quarto-search-results .aa-Panel"
+ );
+ const inputEl = window.document.querySelector(
+ "#quarto-search .aa-Autocomplete"
+ );
+
+ if (panelEl && inputEl) {
+ panelEl.style.top = `${Math.round(panelEl.offsetTop)}px`;
+ if (pos === "start") {
+ panelEl.style.left = `${Math.round(inputEl.left)}px`;
+ } else {
+ panelEl.style.right = `${Math.round(inputEl.offsetRight)}px`;
+ }
+ }
+}
+
+/* Highlighting */
+// highlighting functions
+function highlightMatch(query, text) {
+ if (text) {
+ const start = text.toLowerCase().indexOf(query.toLowerCase());
+ if (start !== -1) {
+ const startMark = "";
+ const endMark = "";
+
+ const end = start + query.length;
+ text =
+ text.slice(0, start) +
+ startMark +
+ text.slice(start, end) +
+ endMark +
+ text.slice(end);
+ const startInfo = clipStart(text, start);
+ const endInfo = clipEnd(
+ text,
+ startInfo.position + startMark.length + endMark.length
+ );
+ text =
+ startInfo.prefix +
+ text.slice(startInfo.position, endInfo.position) +
+ endInfo.suffix;
+
+ return text;
+ } else {
+ return text;
+ }
+ } else {
+ return text;
+ }
+}
+
+function clipStart(text, pos) {
+ const clipStart = pos - 50;
+ if (clipStart < 0) {
+ // This will just return the start of the string
+ return {
+ position: 0,
+ prefix: "",
+ };
+ } else {
+ // We're clipping before the start of the string, walk backwards to the first space.
+ const spacePos = findSpace(text, pos, -1);
+ return {
+ position: spacePos.position,
+ prefix: "",
+ };
+ }
+}
+
+function clipEnd(text, pos) {
+ const clipEnd = pos + 200;
+ if (clipEnd > text.length) {
+ return {
+ position: text.length,
+ suffix: "",
+ };
+ } else {
+ const spacePos = findSpace(text, clipEnd, 1);
+ return {
+ position: spacePos.position,
+ suffix: spacePos.clipped ? "…" : "",
+ };
+ }
+}
+
+function findSpace(text, start, step) {
+ let stepPos = start;
+ while (stepPos > -1 && stepPos < text.length) {
+ const char = text[stepPos];
+ if (char === " " || char === "," || char === ":") {
+ return {
+ position: step === 1 ? stepPos : stepPos - step,
+ clipped: stepPos > 1 && stepPos < text.length,
+ };
+ }
+ stepPos = stepPos + step;
+ }
+
+ return {
+ position: stepPos - step,
+ clipped: false,
+ };
+}
+
+// removes highlighting as implemented by the mark tag
+function clearHighlight(searchterm, el) {
+ const childNodes = el.childNodes;
+ for (let i = childNodes.length - 1; i >= 0; i--) {
+ const node = childNodes[i];
+ if (node.nodeType === Node.ELEMENT_NODE) {
+ if (
+ node.tagName === "MARK" &&
+ node.innerText.toLowerCase() === searchterm.toLowerCase()
+ ) {
+ el.replaceChild(document.createTextNode(node.innerText), node);
+ } else {
+ clearHighlight(searchterm, node);
+ }
+ }
+ }
+}
+
+function escapeRegExp(string) {
+ return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
+}
+
+// highlight matches
+function highlight(term, el) {
+ const termRegex = new RegExp(term, "ig");
+ const childNodes = el.childNodes;
+
+ // walk back to front avoid mutating elements in front of us
+ for (let i = childNodes.length - 1; i >= 0; i--) {
+ const node = childNodes[i];
+
+ if (node.nodeType === Node.TEXT_NODE) {
+ // Search text nodes for text to highlight
+ const text = node.nodeValue;
+
+ let startIndex = 0;
+ let matchIndex = text.search(termRegex);
+ if (matchIndex > -1) {
+ const markFragment = document.createDocumentFragment();
+ while (matchIndex > -1) {
+ const prefix = text.slice(startIndex, matchIndex);
+ markFragment.appendChild(document.createTextNode(prefix));
+
+ const mark = document.createElement("mark");
+ mark.appendChild(
+ document.createTextNode(
+ text.slice(matchIndex, matchIndex + term.length)
+ )
+ );
+ markFragment.appendChild(mark);
+
+ startIndex = matchIndex + term.length;
+ matchIndex = text.slice(startIndex).search(new RegExp(term, "ig"));
+ if (matchIndex > -1) {
+ matchIndex = startIndex + matchIndex;
+ }
+ }
+ if (startIndex < text.length) {
+ markFragment.appendChild(
+ document.createTextNode(text.slice(startIndex, text.length))
+ );
+ }
+
+ el.replaceChild(markFragment, node);
+ }
+ } else if (node.nodeType === Node.ELEMENT_NODE) {
+ // recurse through elements
+ highlight(term, node);
+ }
+ }
+}
+
+/* Link Handling */
+// get the offset from this page for a given site root relative url
+function offsetURL(url) {
+ var offset = getMeta("quarto:offset");
+ return offset ? offset + url : url;
+}
+
+// read a meta tag value
+function getMeta(metaName) {
+ var metas = window.document.getElementsByTagName("meta");
+ for (let i = 0; i < metas.length; i++) {
+ if (metas[i].getAttribute("name") === metaName) {
+ return metas[i].getAttribute("content");
+ }
+ }
+ return "";
+}
+
+function algoliaSearch(query, limit, algoliaOptions) {
+ const { getAlgoliaResults } = window["@algolia/autocomplete-preset-algolia"];
+
+ const applicationId = algoliaOptions["application-id"];
+ const searchOnlyApiKey = algoliaOptions["search-only-api-key"];
+ const indexName = algoliaOptions["index-name"];
+ const indexFields = algoliaOptions["index-fields"];
+ const searchClient = window.algoliasearch(applicationId, searchOnlyApiKey);
+ const searchParams = algoliaOptions["params"];
+ const searchAnalytics = !!algoliaOptions["analytics-events"];
+
+ return getAlgoliaResults({
+ searchClient,
+ queries: [
+ {
+ indexName: indexName,
+ query,
+ params: {
+ hitsPerPage: limit,
+ clickAnalytics: searchAnalytics,
+ ...searchParams,
+ },
+ },
+ ],
+ transformResponse: (response) => {
+ if (!indexFields) {
+ return response.hits.map((hit) => {
+ return hit.map((item) => {
+ return {
+ ...item,
+ text: highlightMatch(query, item.text),
+ };
+ });
+ });
+ } else {
+ const remappedHits = response.hits.map((hit) => {
+ return hit.map((item) => {
+ const newItem = { ...item };
+ ["href", "section", "title", "text", "crumbs"].forEach(
+ (keyName) => {
+ const mappedName = indexFields[keyName];
+ if (
+ mappedName &&
+ item[mappedName] !== undefined &&
+ mappedName !== keyName
+ ) {
+ newItem[keyName] = item[mappedName];
+ delete newItem[mappedName];
+ }
+ }
+ );
+ newItem.text = highlightMatch(query, newItem.text);
+ return newItem;
+ });
+ });
+ return remappedHits;
+ }
+ },
+ });
+}
+
+let subSearchTerm = undefined;
+let subSearchFuse = undefined;
+const kFuseMaxWait = 125;
+
+async function fuseSearch(query, fuse, fuseOptions) {
+ let index = fuse;
+ // Fuse.js using the Bitap algorithm for text matching which runs in
+ // O(nm) time (no matter the structure of the text). In our case this
+ // means that long search terms mixed with large index gets very slow
+ //
+ // This injects a subIndex that will be used once the terms get long enough
+ // Usually making this subindex is cheap since there will typically be
+ // a subset of results matching the existing query
+ if (subSearchFuse !== undefined && query.startsWith(subSearchTerm)) {
+ // Use the existing subSearchFuse
+ index = subSearchFuse;
+ } else if (subSearchFuse !== undefined) {
+ // The term changed, discard the existing fuse
+ subSearchFuse = undefined;
+ subSearchTerm = undefined;
+ }
+
+ // Search using the active fuse
+ const then = performance.now();
+ const resultsRaw = await index.search(query, fuseOptions);
+ const now = performance.now();
+
+ const results = resultsRaw.map((result) => {
+ const addParam = (url, name, value) => {
+ const anchorParts = url.split("#");
+ const baseUrl = anchorParts[0];
+ const sep = baseUrl.search("\\?") > 0 ? "&" : "?";
+ anchorParts[0] = baseUrl + sep + name + "=" + value;
+ return anchorParts.join("#");
+ };
+
+ return {
+ title: result.item.title,
+ section: result.item.section,
+ href: addParam(result.item.href, kQueryArg, query),
+ text: highlightMatch(query, result.item.text),
+ crumbs: result.item.crumbs,
+ };
+ });
+
+ // If we don't have a subfuse and the query is long enough, go ahead
+ // and create a subfuse to use for subsequent queries
+ if (
+ now - then > kFuseMaxWait &&
+ subSearchFuse === undefined &&
+ resultsRaw.length < fuseOptions.limit
+ ) {
+ subSearchTerm = query;
+ subSearchFuse = new window.Fuse([], kFuseIndexOptions);
+ resultsRaw.forEach((rr) => {
+ subSearchFuse.add(rr.item);
+ });
+ }
+ return results;
+}
diff --git a/es/sitemap.xml b/es/sitemap.xml
new file mode 100644
index 000000000..f36fd8aa3
--- /dev/null
+++ b/es/sitemap.xml
@@ -0,0 +1,123 @@
+
++Esta guía condensa el proceso de revisión por pares desde el punto de vista de quienes crean paquetes. +
+pkgcheck localmente para confirmar que el paquete está listo para ser enviado. Otra forma aún más fácil de asegurarse de que un paquete está listo para su envío es utilizar la acción de GitHub pkgcheck para ejecutar pkgcheck como una Acción de GitHub, como se describe en esta publicación en nuestro blog.pkgcheck que tu paquete no pueda aprobar, explica los motivos en la plantilla de envío.<!---variable--->). Éstas son utilizadas por nuestro bot (ropensci-review-bot) y no deben modificarse. Los valores de las variables deben completarse ente los puntos de inicio y fin, así:<!---variable--->insertar valor aquí<!---end-variable>pkgcheck, el cual confirmará si está listo para ser revisado o no.ropensci-software-review.pkgcheck, se puede solicitar un nuevo chequeo con el comando @ropensci-review-bot check package.Nuestro código de conducta es obligatorio para la participación en nuestro proceso de revisión.
+ + ++La revisión por pares de software en rOpenSci es gestionada por un equipo editorial. Estamos probando un sistema donde el rol de Líder Editorial (LE) va rotando. +
++Este capítulo presenta las responsabilidades quien lidera el equipo editorial, de cualquiera a cargo de editar un envío, cómo responder a un envío fuera del alcance de rOpenSci y cómo gestionar la publicación de una nueva versión de la guía de desarrollo. +
++Si estás en el rol de edición de forma invitada, ¡gracias por tu ayuda! Si tienes alguna duda, ponte en contacto con la persona que te invitó a encargarte del proceso de revisión de un paquete. +
+++Asume siempre que quienes participan en el sistema de revisión de software (tanto en la edición, como la revisión y la autoría de paquetes) están dando su mayor esfuerzo, y comunícate con amabilidad, especialmente cuando preguntes por qué hay un retraso.
+
Además de ocuparse de los paquetes (unos 4 al año), quienes realizan la edición intervienen en las decisiones editoriales del equipo (como si un paquete está dentro del ámbito de aplicación) y determinan las actualizaciones de nuestras políticas. Generalmente lo hacemos a través de Slack, que esperamos que los miembros del equipo puedan consultar con regularidad.
También rotamos Responsabilidades del Líder Editorial (decisiones de alcance en primera instancia y asignación de roles editoriales) entre los miembros del equipo aproximadamente cada tres meses.
No tienes que hacer un seguimiento de otros envíos, pero si observas un problema con un paquete que está siendo gestionado por otra persona, no dudes en plantear ese problema directamente a quien está a cargo de la edición, o publica la preocupación en el canal exclusivo para el equipo editorial en Slack. Por ejemplo:
+@ropensci-review-bot assign @username as editor. Esto también añadirá la etiqueta 1/editor-checks al issue.@ropensci-review-bot check package”.pkgreviewr creado por la editora asociada Anna Krystalli. Procura terminar las comprobaciones y empezar a buscar personas para hacer la revisión en un plazo de 5 días laborables.usethis y styler y recursos en línea (secciones de esta guía, secciones del Libro R Packages) para facilitar tu devolución. Ejemplo de comprobaciones de una editora.@ropensci-review-bot put on hold. Recibirás un recordatorio cada 90 días (en el issue) para que te pongas en contacto con las personas a cargo del paquete.@ropensci-review-bot seeking reviewers.@ropensci-review-bot assign @username as reviewer. add también puede utilizarse en lugar de assign y to reviewers (plural) en lugar de as reviewer (singular). Por lo tanto, lo siguiente también es válido: @ropensci-review-bot add @username to reviewers. Debe generarse una orden para cada persona. Si es necesario sacar a alguien de la revisión, usa @ropensci-review-bot remove @username from reviewers.@ropensci-review-bot set due date for @username to YYYY-MM-DD.Como responsable de la edición, utiliza
+Cuando estas fuentes de información no sean suficientes,
+Puedes utilizar filtros, clasificación y búsqueda para identificar personas para la revisión con una experiencia concreta:
+
Comprueba la revisión más reciente de la persona y evita a cualquiera que haya revisado en los últimos seis meses. Asimismo, comprueba si una persona que es nueva revisando ha indicado que requiere tutoría en el camporequire_mentorship. En caso afirmativo, utiliza la parte de tutoría de la plantilla de correo electrónico y prepárate para proporcionar orientación adicional.
Estos son los criterios que debes tener en cuenta a la hora de elegir a alguien para realizar la revisión. Puede que tengas que reunir esta información buscando en CRAN y en su página GitHub, así como en su presencia general en Internet (sitio web personal, Twitter).
+Cada envío debe ser revisado por dos personas. Aunque está bien que una de ellas tenga menos experiencia en el desarrollo de paquetes y más conocimientos del dominio, la revisión no debe dividirse en dos. Ambas deben revisar el paquete de forma exhaustiva, aunque desde su perspectiva particular. En general, al menos una debe tener experiencia previa en revisiones y, por supuesto, invitar gente nueva amplía nuestro grupo de revisión.
+@ropensci-review-bot submit review <review-url> time <time in hours>. Por ejemplo, para la reseña https://github.com/ropensci/software-review/issues/329#issuecomment-809783937 el comentario sería @ropensci-review-bot submit review https://github.com/ropensci/software-review/issues/329#issuecomment-809783937 time 4.5/awaiting-reviewer-response y pide a las personas a cargo de la revisión que indiquen su aprobación con la [plantilla de aprobación de revisión]{#approval2template}.@ropensci-review-bot approve <package-name>@ropensci/blog-editors para su seguimiento.ropensci-books organización de GitHub.Quien ocupa el rol de LE desempeña sus funciones durante 3 meses o el tiempo que acuerden todos los miembros del equipo editorial. Tiene derecho a tomar decisiones de alcance y solapamiento con la mayor independencia posible (pero puede solicitar ayuda/asesoramiento). En detalle, el rol de LE implica las siguientes funciones
+Vigila todos los issues publicados en el repositorio de revisión del software (se suscribe a las notificaciones del repositorio en GitHub, o vigila la página #software-peer-review-feed en Slack).
Etiqueta el issue con 0/editorial-team-prep
Usa @ropensci-review-bot check srr sobre consultas previas a la presentación de software estadístico. Revisar los capítulos correspondientes a la Guía de desarrollo de estadística para más detalles.
Asigna los envíos de paquetes a otros miembros del equipo editorial, incluyéndose, para que se encarguen de ellos. En la mayoría de los casos, esta responsabilidad rota entre los miembros del equipo editorial a menos que quien sea LE considere que un miembro en particular es especialmente adecuado para algún paquete, o que alguien rechace encargarse del envío por no tener tiempo o por tener un conflicto de intereses.
+@ropensci-review-bot assign @username as editorSupervisa el ritmo del proceso de revisión y recuerda a otros miembros del equipo editorial que hagan avanzar los paquetes según sea necesario.
Al asumir el rol de LE, revisa el estado de las revisiones abiertas actuales y recuerda a quienes las editan que respondan o actualicen el estado según sea necesario.
Responde a los issues publicados en el repositorio software-review-meta
Toma decisiones sobre el alcance y solapamiento de las consultas previas a la presentación, las recomendaciones desde JOSS u otros socios de publicación, y las presentaciones si ven un caso ambiguo (este último caso también puede ser realizado por personas que están a cargo de la edición de un paquete (ver más abajo)). Para iniciar el debate, debe publicar en el canal exclusivo para el equipo editorial del Slack de rOpenSci junto con un pequeño resumen de lo que trata la presentación (pre)enviada/remitida, y sus dudas, es decir, digerir un poco la información. Si al cabo de uno o dos días considera que no ha recibido suficientes respuestas, puede enviar una notificación a todo el equipo editorial.
+@ropensci-review-bot out-of-scope” en el issue.Solicita a alguien más para cubrir el rol de LE cuando finalice su rotación (establece un recordatorio en el calendario antes de la fecha prevista de finalización y pide reemplazos en el canal de Slack del equipo editorial).
En algunos casos, la documentación en línea es escasa. Un README mínimo y la ausencia de un sitio web de pkgdown dificultan la evaluación. En ese caso, por favor, pide más detalles: aunque el paquete se considere fuera de alcance, la documentación del paquete habrá mejorado, así que no nos molesta pedir estos esfuerzos.
+Ejemplo de texto
+Hola <nombre> y muchas gracias por su envío.
+
+Estamos discutiendo si el paquete está dentro del ámbito de aplicación y necesitamos un poco más de información.
+
+¿Le importaría añadir más detalles y contexto al *README*?
+Después de leerlo alguien con poco conocimiento del dominio debería tener suficiente información sobre el objetivo, las metas y la funcionalidad del paquete.
+
+<opcional>
+Si un paquete tiene funcionalidad que se solapa con otros paquetes, requerimos que demuestre en la documentación [por qué es el mejor de su clase](https://devguide.ropensci.org/policies.html#overlap). Podrías añadir una comparación más detallada con los paquetes que mencionas en el *README* para que podamos evaluarlo?
+</opcional>Tras debatirlo con otros miembros del equipo, quien sea LE puede invitar a una persona externa para que se encargue de un envío (por ejemplo, si el volumen de envíos es grande, si todos los miembros del equipo de edición tienen un conflicto de intereses, si se necesitan conocimientos específicos, o como prueba antes de enviar una invitación a formar parte del equipo de edición).
+Cuando invites a alguien para realizar una edición de forma invitada:
+Si la persona acepta (¡bien!),
+ropensci/editors y a la organización ropensci;Una vez finalizado el proceso de revisión (paquete aprobado, issue cerrado),
+ropensci/editors (pero no de la organización ropensci).Agradece a quienes presentaron el paquete por el envío, explica los motivos de la decisión y propone otros lugares de publicación, si corresponde, y al foro de debate de rOpenSci. Utiliza el texto de Objetivos y alcance en particular en lo que respecta a la evolución del alcance a lo largo del tiempo, y al solapamiento y las diferencias entre el desarrollo de unconf/personal/revisión de software.
+Ejemplos de envíos y respuestas fuera del ámbito de aplicación.
+Las personas que hacen revisiones pueden pedir devoluciones sobre, por ejemplo, el tono de su revisión. Además de darles las orientaciones generales de esta guía, pregunta a los miembros del equipo de edición o abre un issue cuando falten indicaciones. Aquí tienes algunos ejemplos de reseñas que pueden ser útiles:
+slopes que acabó siendo rediseñado fundamentalmente en respuesta a las revisiones. Todas las revisiones fueron en todo momento totalmente constructivas, lo que parece haber desempeñado un papel importante a la hora de motivar a quienes desarrollaron el paquete a embarcarse en una revisión tan importante. Comentarios como, “este paquete no…” o “no tiene …” iban seguidas invariablemente de sugerencias constructivas sobre lo que se podría hacer (hay, por ejemplo, varias en una de las primeras revisiones).tic expresaban educadamente sus reservas: https://github.com/ropensci/software-review/issues/305#issuecomment-504762517 y https://github.com/ropensci/software-review/issues/305#issuecomment-508271766
+bowerbird recibió una útil “revisión previa” que dio lugar a una división del paquete antes de las revisiones propiamente dichas.Si te encargas de gestionar una versión de este mismo libro que estás leyendo, utiliza la guía para la publicación de libros como plantilla de issue para publicar en el gestor de issues de la guía de desarrollo y no dudes en hacer preguntas al resto del equipo de edición.
+Para modificaciones muy pequeñas de la guía de desarrollo, no es necesaria la revisión del PR. Para enmiendas mayores, solicita la revisión de al menos varios miembros del equipo de edición (si ninguno participó en la discusión relacionada con la enmienda, solicita una revisión de todos en GitHub, y en ausencia de cualquier reacción aprueba el PR después de una semana).
+Dos semanas antes del lanzamiento de una nueva versión de la guía de desarrollo, una vez que el PR de dev a master y la publicación en el blog estén listos para su revisión, todos los miembros del equipo de edición deben recibir una notificación de GitHub (“solicitud de revisión” en el PR de dev a main) y Slack, pero no es necesario que todos aprueben explícitamente la publicación.
+El artículo del blog sobre una nueva edición será revisado por el equipo de edición y por alguien de @ropensci/blog-editors.
Consulta la guía general para blogs rOpenSci y las orientaciones más específicas a continuación.
+Primer ejemplo de un artículo de este tipo; segundo ejemplo.
+El artículo del blog debe mencionar todos los elementos importantes del registro de cambios organizados en (sub)secciones: por ejemplo, una sección sobre el gran cambio A, otra sobre el gran cambio B, y otra sobre cambios menores agrupados. Menciona primero los cambios más importantes.
+Por cada cambio realizado por una persona que colabora de manera externa, agradéceselo explícitamente utilizando la información del registro de cambios. Por ejemplo [Matt Fidler](https://github.com/mattfidler/) arregló nuestra sección sobre mensajes en la Consola [ropensci/dev_guide#178](https://github.com/ropensci/dev_guide/pull/178)..
Al final del post, menciona los próximos cambios enlazando a los issues abiertos en el repositorio, e invita a quienes leen a contribuir a la guía de desarrollo abriendo issues y participando en los debates abiertos. Plantilla de conclusiones:
+En este post resumimos los cambios incorporados a nuestro libro ["rOpenSci Packages: Development, Maintenance, and Peer Review"](https://devguide.ropensci.org/) en los últimos X meses.
+Agradecemos todas las personas cuyas contribuciones han hecho posible esta versión.
+Ya estamos trabajando en actualizaciones para nuestra próxima versión, como *ISSUE1*, *ISSUE2.*
+Echa un vistazo a [la lista de *issues*](https://github.com/ropensci/dev_guide/issues/) si quieres contribuir.+Guía para gestionar el equipo editorial. +
+Reclutar nuevas personas y mantener un equipo editorial funcional y equilibrado es responsabilidad de quien Lidere la Revisión de Software con el apoyo y asesoramiento del comité editorial.
+Estos son los pasos a seguir:
+Crea un canal privado para discutir la invitación; de este modo, el historial de conversación no queda disponible en el canal al que luego se unirán los nuevos miembros del equipo, lo que podría ser incómodo.
Haz un ping a las personas del equipo editorial para asegurarte de que reciban una notificación, ya que se trata de un tema importante.
Espera a que la mayoría de del equipo intervenga antes de realizar la invitación. Dales una semana para que respondan.
Los posibles nuevos miembros pueden empezar realizando una edición de forma invitada. Haz la invitación como invitarías a cualquier otra persona por otros motivos.
Si el posible nuevo miembro realiza una edición invitada, evalúa cómo ha sido el proceso una vez abordada la presentación. Vuelve a pedir consejo a otras personas del equipo.
Envía un correo electrónico:
Nos gustaría invitarte a formar parte del consejo editorial de rOpenSci como miembro en pleno derecho. [RAZONES ESPECÍFICAS PARA LA INVITACIÓN (MENCIONA LAS CONTRIBUCIONES A ROPENSCI)].
+Creemos que serías una magnífica incorporación al equipo.
+
+[SI REALIZÓ EDICIÓN DE FORMA INVITADA: Ya conoces el rol de edición ya que has sido editora/o invitada/o]. Nuestro objetivo es que los miembros del comité editorial se encarguen de cuatro paquetes al año ([SI REALIZÓ EDICIÓN DE FORMA INVITADA: ¡incluyendo el que acabas de terminar!]).
+Pedimos a los miembros del comité editorial que se comprometan de manera informal a prestar servicio durante dos años, y que reevalúen su participación luego de ese periodo.
+A corto plazo, cualquier persona puede rechazar encargarse de un paquete o decir: "Tengo mi agenda completa, no puedo encargarme de un nuevo paquete hasta dentro de unas semanas".
+
+Además de encargarse de los paquetes, los miembros del equipo editorial opinan sobre las decisiones editoriales del grupo, como por ejemplo si un paquete está dentro de nuestro alcance, y determinan las actualizaciones de nuestras políticas.
+Generalmente usamos Slack, donde esperamos que los miembros del equipo participen regularmente.
+Tenemos reuniones anuales del equipo editorial.
+También rotamos las responsabilidades de Lider Editorial (quien toma decisiones de alcance en primera instancia y asigna personas para editar envíos) entre el equipo aproximadamente cada trimestre.
+Tendrás la oportunidad de entrar en esta rotación cuando lleves un tiempo en el equipo, normalmente al menos seis meses.
+Algunos mimebros del equipo también asumimos proyectos más grandes para mejorar el proceso de revisión por pares, aunque esto es totalmente opcional.
+
+¡Esperamos que te unas al equipo!
+Es un momento emocionante para la revisión por pares en rOpenSci.
+
+Por favor, reflexiónalo, pregúntanos cualquier duda que tengas y haznos saber si puedes unirte.
+
+Te deseamos lo mejor,
+[NOMBRE], en nombre del equipo editorial de rOpenSci.Pide a quien gestiona la comunidad de rOpenSci que
+Solicita al nuevo miembro que active la autenticación de dos factores (2FA) en GitHub si aún no lo han hecho.
Invítalo a la organización GitHub de rOpenSci y a los equipos editors y data-pkg-editors o stats-board, según corresponda. Esto le dará los permisos adecuados y le permitirá recibir notificaciones específicas del equipo.
Dale acceso a la base de datos de revisión de software de AirTable.
Dale acceso al canal privado del equipo editorial en el espacio de trabajo de Slack de rOpenSci (y al espacio de trabajo de Slack en general si no lo tenía previamente, en ese caso pregunta a quien maneja la comunidad de rOpenSci).
Publica un mensaje de bienvenida en el canal, haciendo ping a @editors.
Agrégalo al equipo editors de Slack para que @editors también le envíe una notificación.
Añade su nombre a:
+Tanto la dev_guide como el REAMDE de revisión de software se renderizan automáticamente con integración continua.
Agradece su trabajo.
Elimínalo del canal del equipo editorial y del equipo @editors de Slack.
Elimínalo del equipo editors y del sub-equipo correspondiente en GitHub.
Informa a quien maneja la comunidad de rOpenSci o a algún otro miembro del personal para moverlo a la sección de ex-integrantes en el sitio web.
Elimina su acceso al espacio de trabajo de Airtable.
Elimínalo de:
+Tanto la dev_guide como el REAMDE de revisión de software se renderizan automáticamente con integración continua.
+Este capítulo contiene una introducción general a nuestro sistema de revisión por pares de software para paquetes, razones para enviar un paquete, razones para ofrecerse para revisar, por qué nuestras revisiones son abiertas, y agradecimientos a quienes participan del sistema. +
++Nuestro sistema se ha ampliado recientemente a la revisión por pares de software estadístico. +
++Si utilizas nuestros estándares, listas de tareas, etc. al revisar software en otro lugar, cuenta que estos materiales proceden de rOpenSci a quienes reciben la revisión (por ejemplo, quien edita la revista, estudiantes, colegas durante una revisión interna de código), y también cuéntanoslo en nuestro foro público, o por correo electrónico si prefieres comentarlo en forma privada. +
+La suite de paquetes de rOpenSci recibe aportes tanto de personal de la organización, como por miembros de la comunidad, lo que significa que se nutre de una gran diversidad de habilidades y experiencias. Pero, ¿cómo asegurar un buen nivel de calidad? Ahí es donde entra en juego la revisión por pares de software: los paquetes aportados por la comunidad se someten a un proceso de revisión transparente, constructivo, no conflictivo y abierto. El mismo se sustenta principalmente en el trabajo voluntario: desde el rol de edición asociada, gestionando el flujo de información y garantizando que los envíos progresen; personas que crean, envían y mejoran su paquete; personas que revisan paquetes (dos por envío), examinan el código y la experiencia de usuario. Este artículo del blog, escrito por miembros del equipo editorial de rOpenSci es una buena introducción a la revisión por pares de software de rOpenSci. Puedes encontrar más artículos en el blog de rOpenSci sobre el proceso y los paquetes que pasaron por el mismo en la etiqueta “software-peer-review”.
+Puedes reconocer los paquetes de rOpenSci que han sido revisados por pares mediante una etiqueta verde que dice “peer-reviewed” en su README (ej. el paquete restez) y por el icono azul en su descripción en la página de paquetes de rOpenSci. Ambos contienen links a la revisión.
+En cuanto a la parte técnica, le sacamos el jugo a GitHub: cada proceso de revisión es un issue en el repositorio ropensci/software-review. Por ejemplo, haz click aquí para leer el hilo de revisión del paquete ropenaq. El proceso es una conversación activa hasta que el paquete es aceptado, con dos revisiones externas como momentos importantes. Además, utilizamos funcionalidades de GitHub como las plantillas de issues (como plantilla de envío), y el etiquetado que utilizamos para seguir el progreso de los envíos (desde las revisiones iniciales hasta la aprobación).
ropensci-books para ser listado en books.ropensci.org.Nuestros hilos de revisión son públicos. Todas las personas involucradas (en roles de autoría, revisión y edición) conocen la identidad del resto y la comunidad en general puede ver o incluso participar en la conversación a medida que se produce. Esto proporciona un incentivo para realizar una revisión minuciosa y proporcionar revisiones constructivas y no conflictivas. Tanto quienes envían paquete como quienes los revisan dicen disfrutar y aprender más de este intercambio abierto y directo. También tiene el beneficio de construir una comunidad, ya que quienes participan tienen la oportunidad de interactuar de manera significativa con nuevas personas. Nuevas colaboraciones han nacido gracias a las ideas surgidas durante el proceso de revisión.
+Somos conscientes de que los sistemas abiertos pueden tener inconvenientes. Por ejemplo, en la revisión académica tradicional la revisión por pares con doble ciego puede aumentar la representación de autoras femeninas, lo que sugiere un sesgo en las revisiones abiertas. También es posible que quienes hacen la revisión sean menos críticos en la revisión abierta. Sin embargo, proponemos que la apertura de la conversación de la revisión proporciona un control de la calidad de la revisión y del sesgo; es más difícil hacer comentarios no fundamentados o subjetivos en público sin la cobertura del anonimato. En definitiva, creemos que la comunicación directa y pública quienes desarrollaron el paquete y quienes lo revisan mejora la calidad y la imparcialidad de las revisiones.
+Además, tanto quienes envían paquete y quienes los revisan tienen la posibilidad de contactar al equipo editorial por privado si tienen alguna duda o pregunta.
+docs.ropensci.org que podrás enlazar en el archivo DESCRIPTION.El proceso de revisión por pares del software de rOpenSci está dirigido por
+Agradecemos a las siguientes personas que han ofrecido su tiempo y experiencia para revisar los paquetes enviados a rOpenSci:
+Em Markowitz (NOAA) · Sam Albers · Toph Allen · Kaique dos S. Alves · Brooke Anderson · Alison Appling · Denisse Fierro Arcos · Zebulun Arendsee · Taylor Arnold · Al-Ahmadgaid B. Asaad · Dean Attali · Mara Averick · Suzan Baert · James Balamuta · Vikram Baliga · David Bapst · Joëlle Barido-Sottani · Allison Barner · Cale Basaraba · John Baumgartner · Marcus Beck · Gabriel Becker · Jason Becker · Salvador Jesus Fernandez Bejarano · Dom Bennett · Ken Benoit · Aaron Berdanier · Fred Boehm · Carl Boettiger · Will Bolton · Ben Bond-Lamberty · Anne-Sophie Bonnet-Lebrun · Alison Boyer · Abby Bratt · François Briatte · Eric Brown · Julien Brun · Jenny Bryan · Lukas Burk · Lorenzo Busetto · Maria Paula Caldas · Mario Gavidia Calderón · Carlos Cámara-Menoyo · Brad Cannell · Joaquin Cavieres · Kevin Cazelles · Scott Chamberlain · Cathy Chamberlin · Jennifer Chang · Pierre Chausse · Jorge Cimentada · Nicholas Clark · Chase Clark · Jon Clayden · Dena Jane Clink · Will Cornwell · Nic Crane · Enrico Crema · Verónica Cruz-Alonso · Ildiko Czeller · Tad Dallas · Kauê de Sousa · Christophe Dervieux · Amanda Dobbyn · Jasmine Dumas · Dewey Dunnington · Remko Duursma · Mark Edmondson · Paul Egeler · Evan Eskew · Harry Eslick · Alexander Fischer · Kim Fitter · Robert M Flight · Sydney Foks · Stephen Formel · Zachary Stephen Longiaru Foster · Auriel Fournier · Kaija Gahm · Zach Gajewski · Carl Ganz · Duncan Garmonsway · Jan Laurens Geffert · Sharla Gelfand · Monica Gerber · Duncan Gillespie · David Gohel · A. Cagri gokcek · Guadalupe Gonzalez · Rohit Goswami · Laura Graham · Charles Gray · Matthias Grenié · Corinna Gries · Hugo Gruson · Ernest Guevarra · W Kyle Hamilton · Ivan Hanigan · Jeffrey Hanson · Liz Hare · Jon Harmon · Rayna Harris · Ted Hart · Nujcharee Haswell · Verena Haunschmid · Stephanie Hazlitt · Andrew Heiss · Max Held · Anna Hepworth · Bea Hernandez · Jim Hester · Peter Hickey · Roel Hogervorst · Kelly Hondula · Allison Horst · Sean Hughes · James Hunter · Brandon Hurr · Ger Inberg · Christopher Jackson · Najko Jahn · Tamora D James · Veronica Jimenez-Jacinto · Mike Johnson · Will Jones · Max Joseph · Megha Joshi · Krunoslav Juraic · Soumya Kalra · Zhian N. Kamvar · Michael Kane · Andee Kaplan · Tinula Kariyawasam · Hazel Kavılı · Jonathan Keane · Christopher T. Kenny · Os Keyes · Eunseop Kim · Aaron A. King · Michael Koontz · Bianca Kramer · Will Landau · Sam Lapp · Erin LeDell · Thomas Leeper · Sam Levin · Lisa Levinson · Stephanie Locke · Marion Louveaux · Robin Lovelace · Julia Stewart Lowndes · Tim Lucas · Muralidhar, M.A. · Andrew MacDonald · Jesse Maegan · Mike Mahoney · Tristan Mahr · Yohann Mansiaux · Paula Andrea Martinez · Anthony Martinez · Joao Martins · Ben Marwick · Claire Mason · Miles McBain · Lucy D’Agostino McGowan · Amelia McNamara · Elaine McVey · Bryce Mecum · Nolwenn Le Meur · François Michonneau · Mario Miguel · Helen Miller · Beatriz Milz · Jessica Minnier · Priscilla Minotti · Nichole Monhait · Kelsey Montgomery · Ronny A. Hernández Mora · Paula Moraga · Natalia Morandeira · George Moroz · Ross Mounce · Athanasia Monika Mowinckel · Lincoln Mullen · Matt Mulvahill · Maria Victoria Munafó · David Neuzerling · Dillon Niederhut · Joel Nitta · Rory Nolan · Kari Norman · Jakub Nowosad · Matt Nunes · Daniel Nüst · Lauren O’Brien · Joseph O’Brien · Paul Oldham · Samantha Oliver · Dan Olner · Jeroen Ooms · Victor Ordu · Luis Osorio · Philipp Ottolinger · Mark Padgham · Marina Papadopoulou · Edzer Pebesma · Thomas Lin Pedersen · Antonio J. Pérez-Luque · Marcelo S. Perlin · Rafael Pilliard-Hellwig · Rodrigo Neto Pires · Lindsay Platt · Nicholas Potter · Joanne Potts · Josep Pueyo-Ros · Etienne Racine · Manuel Ramon · Nistara Randhawa · David Ranzolin · Quentin Read · Neal Richardson · tyler rinker · Emily Robinson · David Robinson · Alec Robitaille · Francisco Rodriguez-Sanchez · Sam Rogers · Julia Romanowska · Xavier Rotllan-Puig · Bob Rudis · Edgar Ruiz · Kent Russel · Michael Sachs · Sheila M. Saia · Chitra M Saraswati · Alicia Schep · Klaus Schliep · Clemens Schmid · Patrick Schratz · Collin Schwantes · Marco Sciaini · Eric Scott · Heidi Seibold · Julia Silge · Margaret Siple · Peter Slaughter · Mike Smith · Tuija Sonkkila · Øystein Sørensen · Jemma Stachelek · Christine Stawitz · Irene Steves · Kelly Street · Matt Strimas-Mackey · Alex Stringer · Michael Sumner · Chung-Kai Sun · Sarah Supp · Emi Tanaka · Jason Taylor · Filipe Teixeira · Andy Teucher · Jennifer Thompson · Joe Thorley · Nicholas Tierney · Tiffany Timbers · Tan Tran · Tim Trice · Utku Turk · Zoë Turner · Kyle Ueyama · Ted Underwood · Adithi R. Upadhya · Kevin Ushey · Josef Uyeda · Frans van Dunné · Mauricio Vargas · Remi Vergnon · Jake Wagner · Ben Ward · Elin Waring · Rachel Warnock · Leah Wasser · David Watkins · Lukas Weber · Marc Weber · Karissa Whiting · Stefan Widgren · Anna Willoughby · Saras Windecker · Luke Winslow · David Winter · Sebastian Wójcik · Witold Wolski · Kara Woo · Marvin N. Wright · Jacob Wujciak-Jens · Bruna Wundervald · Lauren Yamane · Emily Zabor · Taras Zakharko · Sherry Zhang · Hao Zhu · Chava Zibman · Naupaka Zimmerman · Jake Zwart · Felipe · santikka · kasselhingee · Bri · Flury · Vincent · eholmes · Pachá · Rich · Claudia · Jasmine · Zack · Lluís · becarioprecario · gaurav
+También agradecemos a las siguientes personas que han tomado el rol de edición de forma invitada:
+ + + ++Este capítulo contiene las políticas de la Revisión por Pares de Software de rOpenSci. +
++En particular, encontrarás nuestras políticas sobre a la revisión por pares de software en sí misma: el proceso de presentación de revisiones (incluyendo nuestras políticas sobre conflictos de intereses) y los objetivos y alcance del sistema de revisión por pares de software. Este capítulo también presenta nuestras políticas sobre propiedad y mantenimiento de los paquetes. +
++Por último, pero no menos importante, encontrarás el código de conducta de la Revisión por Pares de Software de rOpenSci. +
+Para que un paquete sea considerado para ingresar a rOpenSci, quienes crearon el paquete deben iniciar una solicitud en el repositorio ropensci/software-review.
Los paquetes se revisan en su calidad, adecuación, documentación y claridad. El proceso de revisión es bastante similar al de la revisión de un artículo científico (véase nuestra guía de empaquetado y guía de revisión para más detalles). A diferencia de la revisión de un artículo científico, este proceso será una conversación continua.
Una vez resueltas todas las cuestiones y preguntas importantes que puedan solucionarse con un esfuerzo razonable, la persona responsable de la edición tomará una decisión (aceptar, esperar o rechazar). Los rechazos suelen hacerse pronto (antes de que comience el proceso de revisión; ver la sección de objetivos y alcance), pero en raras ocasiones un paquete puede no ser aceptado después de la revisión. En última instancia, es decisión de quien hace la edición rechazar o no el paquete en función de cómo se aborden las revisiones.
La comunicación entre quienes enviaron el paquete, quienes lo revisan y editan tendrá lugar principalmente en GitHub, aunque puedes optar por ponerte en contacto con quien hace la edición por correo electrónico o por Slack para algunas cuestiones. Cuando envíes un paquete, asegúrate de que tu configuración de notificaciones de GitHub sea correcta para que no te pierdas un comentario.
Quien envía el paquete puede elegir que su envío se ponga en espera (en cuyo caso se le aplica la etiqueta holding). El estado de espera se revisará cada 3 meses, y después de un año el issue se cerrará.
Si quien envió el paquete no ha solicitado una etiqueta de espera, pero no responde a las consultas, podremos cerrar el issue en el plazo de un mes desde el último intento de contacto. Este intento incluirá un comentario etiquetando a la persona, pero también un correo electrónico utilizando la dirección de correo electrónico que aparece en el archivo DESCRIPTION del paquete. Este es uno de los raros casos en los que quien hace la edición intentará ponerse en contacto con el autor por correo electrónico.
Para volver a enviar un paquete cuyo envío fue cerrado hay que iniciar un nuevo envío. Si el paquete sigue siendo relevante, habrá que responder a las revisiones iniciales antes de que la persona encargada de la edición empiece a buscar nuevas personas para la revisarlo.
Te recomendamos fuertemente que envíes tu paquete para su revisión antes de publicarlo en CRAN o enviar un artículo de software que describa el paquete a una revista. Las devoluciones de las revisiones pueden dar pie a importantes mejoras y actualizaciones de tu paquete, incluso cambiar el nombre o modificaciones incompatibles con versiones previas. Consideramos que la publicación previa en CRAN o en otros lugares no es razón suficiente para rechazar las recomendaciones surgidas del proceso de revisión.
No envíes tu paquete para su revisión mientras éste o un artículo científico asociado también esté siendo revisado en otro lugar, ya que esto puede dar lugar a recomendaciones incompatibles.
Los siguientes criterios pretenden ser una guía de lo que constituye un conflicto de intereses para quien hace la edición o revisión. Existe un conflicto de intereses si:
+En el caso de que ninguno de los miembros del equipo editorial pueda realizar la edición, se invitará a una persona externa para que la realice.
+rOpenSci tiene como objetivo apoyar paquetes que permiten la investigación reproducible y la gestión del ciclo de vida de los datos para quienes hacen ciencia. Los paquetes enviados a rOpenSci deben encajar en una o más de las categorías indicadas a continuación. El software estadístico también puede ser enviado para su revisión por pares, para lo cual tenemos un conjunto de directrices y normas. Mientras que el resto de este capítulo se aplica a ambos tipos de software, las categorías que aparecen a continuación son para el software general, y no para el estadístico. Si te queda claro si tu paquete encaja en una de las categorías generales o estadísticas, abre un issue como consulta previa a la presentación (Ejemplos).
+Como se trata de un documento vivo, estas categorías pueden cambiar con el tiempo y no todos los paquetes incluidos anteriormente estarían en el ámbito de aplicación en la actualidad. Por ejemplo, los paquetes de visualización de datos ya no están incluidos. Aunque nos esforzamos por ser coherentes, evaluamos los paquetes caso por caso y podemos hacer excepciones.
+Ten en cuenta que no todos los proyectos y paquetes de rOpenSci están incluidos en el ámbito de aplicación o pasan por una revisión por pares.\
+Los proyectos desarrollados por el personal o en conferencias pueden ser experimentales, exploratorios, abordar las prioridades de la infraestructura básica y, por tanto, no entrar en estas categorías. Busca la etiqueta de revisión por pares (ver más abajo) para identificar los paquetes revisados por pares en el repositorio de rOpenSci.
+
obtención de datos: Paquetes para acceder y descargar datos de fuentes en línea con usos científicos. Nuestra definición de “usos científicos” es amplia. Incluye servicios de almacenamiento de datos, revistas y otros servidores remotos, ya que existe una gran variedad de fuentes de datos que pueden ser de interés para quienes hacen ciencia. Sin embargo, los paquetes de obtención de datos deben centrarse en las fuentes o temas de los datos y no en servicios. Por ejemplo, un cliente general para el almacenamiento de datos de Amazon Web Services no estaría en nuestro ámbito. (Ejemplos: rotl, gutenbergr)
extracción de datos: Paquetes que ayudan a extraer datos de fuentes no estructuradas, como texto, imágenes y PDFs, así como a leer datos en formatos científicos y salidas de equipamiento científico. Las bibliotecas estadísticas o de machine learning para el modelado o la predicción no suelen incluirse en esta categoría, como tampoco los analizadores de código. Los modelos entrenados que actúan como utilidades (por ejemplo, para el reconocimiento óptico de caracteres) podrían calificar. (Ejemplos: tabulador para extraer tablas de documentos PDF, genbankr para segmentar archivos de GenBank, treeio para la lectura filogenética en archivos de árboles filogenéticos, lightr para segmentar archivos de instrumentos espectroscópicos)
manipulación de datos: Paquetes para procesar datos obtenidos de los formatos anteriores. Esta área no incluye las herramientas de manipulación de datos en general, como reshape2 o tidyr o herramientas para extraer datos del propio código de R. Más bien, se centra en herramientas para manipular datos en formatos científicos específicos generados a partir de flujos de trabajo científicos o exportados desde instrumentos científicos. (Ejemplos: plateR para leer datos estructurados como mapas de placas de instrumentos científicos, o phonfieldwork para procesar archivos de audio anotados para la investigación fonética)
depósito de datos: Paquetes que apoyan el depósito de datos en repositorios de investigación, incluyendo el proceso de dar formato a los datos y la generación de metadatos. (Ejemplo: EML)
validación y comprobación de datos: Herramientas que permiten la validación y comprobación automatizada de la calidad e integridad de los datos como parte de flujos de trabajo científico. (Ejemplo: assertr)
automatización del flujo de trabajo: Herramientas que automatizan y encadenan flujos de trabajo, como los sistemas de construcción y las herramientas para gestionar la integración continua. No incluye las herramientas generales para la programación literiaria (por ejemplo, las extensiones de R markdown que no están en los temas anteriores). (Ejemplo: drake)
control de versiones: Herramientas que facilitan el uso del control de versiones en los flujos de trabajo científico. Ten en cuenta que esto no incluye todas las herramientas que interactúan con los servicios de control de versiones en línea (por ejemplo, GitHub), a menos que encajen en otra categoría. (Ejemplo: git2rdata)
gestión de citas y bibliometría: Herramientas que facilitan la gestión de las referencias, como por ejemplo para escribir publicaciones científicas, crear CVs o atribuir de otra manera las contribuciones científicas, o acceder, manipular o trabajar de otra manera con datos bibliométricos. (Ejemplo: RefManageR)
capa de interfaz de software científico: Paquetes que permiten correr aplicaciones usadas en la investigación científica desde R. Estos programas deben ser específicos de los campos de investigación, no utilidades informáticas generales. Las capas deben ser no triviales, en el sentido de que debe haber un valor añadido significativo por encima del uso de system() o de vincular el programa, ya sea en darle formato a las entradas entradas y salidas, en el manejo de datos, etc. La mejora del proceso de instalación, o la ampliación de la compatibilidad a más plataformas, puede constituir un valor añadido si la instalación es compleja. Esto no incluye las capas de interfaz de otros paquetes de R o bibliotecas de C/C++ que puedan incluirse en los paquetes de R. Tampoco se incluyen los paquetes que son clientes de API web, que deben pertenecer a una de las otras categorías. Animamos encarecidamente crear capas de interfaz a utilidades de código abierto y de licencia abierta; las excepciones se evaluarán caso por caso, teniendo en cuenta si existen opciones de código abierto. (Ejemplos: babette, nlrx)
herramientas de reproducibilidad de campo y laboratorio: Paquetes que mejoran la reproducibilidad de los flujos de trabajo del mundo real mediante la estandarización y la automatización de los protocolos de campo y de laboratorio. Por ejemplo, el seguimiento y el etiquetado de las muestras, la generación de formularios y hojas de datos, la interconexión con los equipos de laboratorio o los sistemas de información, y la ejecución de diseños experimentales. (Ejemplo: baRcodeR)
enlaces a software de bases de datos: Enlaces y capas de interfaz para las API genéricas de bases de datos (Ejemplo: rrlite)
Además, tenemos algunos temas especializados con un alcance algo más amplio.
+datos geoespaciales: Aceptamos paquetes centrados en el acceso, manipulación y conversión entre formatos de datos geoespaciales. (Ejemplos: osmplotr, tidync).
traducción: Como parte de nuestro trabajo en publicación multilingüe tenemos especial interés en paquetes que faciliten la traducción y publicación de recursos científicos y de programación a múltiples lenguages (humanos) para que sean accesibles a públicos más amplios y diversos. Podría tratarse de interfaces para programas de traducción automática, infraestructura para gestionar la documentación en varios lenguages o programas que accedan a recursos lingüísticos especializados. Se trata de un ámbito nuevo y experimental, por lo que te rogamos que abras un issue para preguntar si el software está dentro del alcance de rOpenSci si te interesa presentar un paquete en esta categoría.
Los paquetes deben ser generales en el sentido de que deben resolver un problema de la forma más amplia posible, manteniendo una interfaz de usuario y una base de código coherentes. Por ejemplo, si varias fuentes de datos utilizan una API idéntica, preferimos un paquete que proporcione acceso a todas las fuentes de datos, en lugar de una sola.
+Los paquetes que incluyan herramientas interactivas para facilitar los flujos de trabajo científico (por ejemplo, las shiny apps) deben tener un mecanismo para que el flujo de trabajo interactivo sea reproducible, como la generación de código o una API que permita la creación de scripts.
+Para los paquetes que no están en el ámbito de rOpenSci, animamos a presentarlos en CRAN, BioConductor, así como en otras iniciativas de desarrollo de paquetes de R (por ejemplo cloudyr), y a las revistas de software como JOSS, JSS o la revista R, dependiendo del alcance actual de esas revistas.
+Ten en cuenta que los paquetes desarrollados internamente por rOpenSci, a través de nuestros eventos o mediante colaboraciones, no están todos en el ámbito de nuestro proceso de revisión por pares de software.
+rOpenSci fomenta la competencia entre paquetes, la bifurcación y la reimplementación, dado que éstas mejoran las opciones de quienes los usan en general. Sin embargo, como queremos que los paquetes del universo de rOpenSci sean nuestras principales recomendaciones para las tareas que realizan, pretendemos evitar la duplicación de la funcionalidad de los paquetes de R existentes en cualquier repo sin mejoras significativas. Un paquete que replica la funcionalidad de un paquete existente puede ser considerado para su inclusión en rOpenSci si mejora significativamente las alternativas en cualquier repositorio (RO, CRAN, BioC) al ser
+Estos factores deben considerarse en su conjunto para determinar si el paquete es una mejora significativa. Un nuevo paquete no cumpliría esta norma sólo por seguir nuestras directrices sobre paquetes mientras otros no lo hacen, a menos que esto suponga una diferencia significativa en las áreas mencionadas.
+Recomendamos que los paquetes destaquen en su README y/o en sus viñetas las diferencias con respecto a los paquetes que se solapan y las mejoras que introducen.
+Animamos a quienes desarrollaron paquetes que no son aceptados debido al solapamiento a que sigan considerando su envío a otros repositorios o revistas.
+Quienes crearon los paquetes mantienen esencialmente la misma propiedad que tenían antes de que su paquete se uniera al conjunto paquetes de rOpenSci. Estas personas seguirán manteniendo y desarrollando su software luego de su aceptación en rOpenSci. A menos que se les añada explícitamente con rol de colaboración, el equipo de rOpenSci no interferirá mucho en las actividades cotidianas. Sin embargo, el equipo puede intervenir con correcciones de errores críticos, o abordar cuestiones urgentes si quienes son responsables de los paquetes no responden de manera oportuna (ver la sección sobre la capacidad de respuesta de quienes mantienen los paquetes).
+Si quienes matienen los paquetes no responden a tiempo a las solicitudes de corrección de de CRAN o de rOpenSci, enviaremos recordatorios varias veces, pero después de 3 meses (o un plazo más corto, dependiendo de lo crítica que sea la corrección) haremos los cambios.
+Lo anterior es un poco impreciso, por lo que a continuación se presentan algunos ejemplos a considerar.
+foo es importado por uno o más paquetes en CRAN, y foo tiene problemas, y por tanto generará problemas en los paquetes que dependan de foo.bar puede no ser usado por otros paquetes que se encuentran en CRAN, pero es muy utilizado, por lo que arreglar rápidamente los problemas es muy importante.hello no está en CRAN, o está en CRAN, pero no tiene dependencias inversas (no hay paquetes que dependan de de hello).world necesita algunas correcciones. La persona responsable ha respondido, pero simplemente está muy ocupada con un nuevo trabajo, u otra razón, y atenderá el problema pronto.Instamos a quienes mantienen paquetes a asegurarse de que reciben las notificaciones de GitHub, y de que los correos electrónicos del equipo de rOpenSci y de CRAN no van a su bandeja de correo no deseado. Invitaremos al Slack de rOpenSci a quienes hayan desarrollado paquetes que son incorporados a rOpenSci para charlar con el equipo y la comunidad de rOpenSci en general. Cualquier persona puede sumarse a la conversación con la comunidad rOpenSci en el foro de discusión de rOpenSci.
+Si quienes desarrollaron un paquete abandonan su mantenimiento y se trata de un paquete utilizado activamente, consideraremos la posibilidad de solicitar a CRAN que transfiera el estatus de mantenedor del paquete a rOpenSci.
+rOpenSci se esfuerza por desarrollar y promover software de investigación de alta calidad. Para asegurarnos de que tu software cumple nuestros criterios, revisamos todos los envíos como parte del proceso de revisión por pares del software, e incluso después de la aceptación seguiremos interviniendo con mejoras y correcciones de errores.
+A pesar de nuestros esfuerzos por apoyar el software contribuido, los errores son responsabilidad de quien mantiene el paquete. El software con errores y sin mantenimiento puede ser eliminado de nuestra suite de paquetes en cualquier momento.
+En el improbable caso de que quien colabora con de un paquete solicite que su paquete sea retirado de la suite, nos reservamos el derecho de mantener una versión del paquete en nuestra suite con fines de archivo.
+Los paquetes de rOpenSci y otras herramientas se utilizan para diversos fines, pero nuestro foco está en las herramientas para la investigación. Esperamos que las herramientas permitan un uso ético por parte de quienes hacen investigación, quienes tienen la obligación de seguir códigos éticos como la Declaración de Helsinki y el Informe Belmont. Quienes investigan son responsables del uso que hacen del software, pero quienes desarrollan el software deben considerar el uso ético de sus productos y deben adherir a los códigos éticos para profesionales de la informática, como los expresados por el IEEE y ACM. Quienes colaboran en rOpenSci a menudo desempeñan el papel de investigación y desarrollo de software.
+Pedimos que quienes desarrollan software se pongan en el papel de quienes investigan y consideren los requisitos de un flujo de trabajo ético utilizando el software. Dada la variación y la velocidad de los cambios en los enfoques éticos para los análisis basados en Internet, es necesario evaluar cada caso en lugar de elaborar recetas. La Guía de Ética de la Asociación de Investigadores de Internet proporciona un marco sólido y animamos tanto a quienes mantienen paquetes como a quienes los revisan y editan, a utilizarlo a la hora de evaluar su trabajo. En general, la adhesión a los requisitos legales o reglamentarios mínimos puede no ser suficiente, aunque éstos (p. ej, GDPR), pueden ser relevantes. Quienes crean los paquetes deben dirigir a quienes los usan a los recursos pertinentes para el uso ético del software.
+Algunos paquetes pueden ser sujetos a un mayor escrutinio debido a la naturaleza de los datos que manejan. En estos casos, quienes hacen la edición pueden exigir funcionalidad adicional (o reducida) y una sólida documentación, valores por defecto y advertencias para dirigir a quienes usan el paquete a las prácticas éticas pertinentes. Los siguientes temas pueden merecer un mayor escrutinio:
+Poblaciones vulnerables: Quienes crean paquetes y flujos de trabajo que tratan con información relacionada con poblaciones vulnerables tienen la responsabilidad de protegerlas de posibles daños.
Datos personales o sensibles: La divulgación de datos identificables o sensibles es potencialmente perjudicial. Esto incluye los datos “razonablemente identificables”, que una persona motivada podría rastrear hasta la persona propietaria o creadora, incluso si los datos son anónimos. Esto incluye tanto los casos en los que los datos identificadores (por ejemplo, nombre, fecha de nacimiento) están disponibles como parte de los datos, y también si los seudónimos o nombres de usuario están vinculados a mensajes de texto completo, a través de los cuales se puede puede vincular a las personas individuales mediante referencias cruzadas con otros conjuntos de datos.
Aunque la mejor respuesta a los problemas éticos dependerá del contexto, se deben seguir estas directrices generales cuando se presenten los desafíos anteriores:
+Los paquetes deben adherirse a las condiciones de uso de la fuente de datos, expresadas en los términos y condiciones del sitio web, archivos “robots.txt”, políticas de privacidad y otras otras restricciones relevantes, y enlazarlas de forma destacada en la documentación del paquete. Los paquetes deben proporcionar o documentar la funcionalidad para cumplir restricciones (por ejemplo, el scrapeado sólo de los servicios permitidos, el uso de limitación de velocidad adecuada en el código, los ejemplos o las viñetas). Ten en cuenta que aunque los Términos y Condiciones, las políticas de privacidad, etc., pueden no ofrecer límites suficientes para un uso ético, pueden proporcionar límites mínimos.
Una herramienta clave para abordar los riesgos que plantea el estudio de poblaciones vulnerables o utilizar datos de identificación personal es el consentimiento informado. Quienes crean los paquetes deben permitir la obtención del consentimiento informado cuando sea pertinente. Esto puede incluir proveer enlaces al método preferido por la fuente de datos para adquirir el consentimiento, información de contacto de quienes proveen los datos (por ejemplo, quienes moderan un foro), documentación de los protocolos de consentimiento informado, u obtener la aprobación previa para los usos generales de un paquete.
+Ten en cuenta que el consentimiento no se concede implícitamente sólo porque los datos sean accesibles. Los datos accesibles no son necesariamente públicos, ya que diferentes personas y contextos tienen diferentes expectativas normativas de privacidad (véase el trabajo de Social Data Lab).
+Los paquetes que acceden a información personal identificable deben tener especial cuidado en seguir las buenas prácticas de seguridad (por ejemplo, el uso exclusivo de protocolos de Internet seguros, mecanismos fuertes para almacenar credenciales, etc.).
Los paquetes que acceden o manejan datos personales identificables o sensibles deben habilitar, documentar y demostrar los flujos de trabajo para la desidentificación, el almacenamiento seguro, y otras buenas prácticas para minimizar el riesgo de daños.
A medida que las normas de privacidad de los datos y la investigación siguen evolucionando, agradeceremos los aportes de quienes desarrollan paquetes sobre las consideraciones específicas de su software y la documentación complementaria, como la aprobación de los comités de revisión ética de las universidades. Estos pueden adjuntarse a los issues de los envíos de paquetes o a las consultas previas al envío, o transmitirse directamente a quienes se encargan de la edición si es necesario. En general, sugerencias pueden enviarse como issue en el repositorio de este libro.
+Los siguientes recursos pueden ser útiles para quienes investigan, desarrollan paquetes, hacen la edición o revisión a la hora de abordar cuestiones éticas relacionadas con la privacidad y el software de investigación.
+La comunidad de rOpenSci es nuestro mejor recurso. Tanto si colaboras habitualmente como si recién llegas, nos esforzamos para que éste lugar sea seguro para ti y te apoyamos en lo que necesites. Tenemos un Código de Conducta que se aplica a todas las personas que participan en la comunidad de rOpenSci, incluidos el equipo y la dirección de rOpenSci y a todos las formas de interacción en línea o en persona. El Código de Conducta se mantiene en el sitio web de rOpenSci.
+ + ++¡Gracias por aceptar revisar un paquete para rOpenSci! Este capítulo incluye nuestras recomendaciones para preparar, enviar y realizar un seguimiento de tu revisión. +
++Puedes ponerte en contacto con la persona encargada de la edición del paquete si tienes dudas sobre el proceso en general o tu revisión en particular. +
++Trata de completar tu revisión en un plazo de 3 semanas desde aceptar participar de la misma. Intentaremos recordar a quienes hacen una revisión las fechas de vencimiento próximas y pasadas. La persona encargada de la edición puede asignar personas adicionales o alternativas si una revisión se retrasa excesivamente. +
++La comunidad de rOpenSci es lo más importante. Nuestro objetivo es que las revisiones sean abiertas, no conflictivas y con el objetivo de mejorar la calidad del software. ¡Sé amable! y comportate con respeto. Consulta nuestra guía para quienes realizan una revisión y el [código de conducta] (https://ropensci.org/code-of-conduct/) para más información. +
++Si utilizas nuestros estándares, listas de tareas, etc. al revisar software en otro lugar, cuenta que estos materiales proceden de rOpenSci a quienes reciben la revisión (por ejemplo, quien edita la revista, estudiantes, colegas durante una revisión interna de código), y también cuéntanoslo en nuestro foro público, o por correo electrónico si prefieres comentarlo en forma privada. +
+Gracias por tu deseo de participar en la revisión de software de rOpenSci revisando paquetes.
+Por favor, completa nuestro formulario de voluntariado.
+Si ves una presentación vigente que te sea particularmente interesante, por favor envía un correo electrónico a info@ropensci.org, incluyendo el nombre del paquete, la URL del issue de presentación y el nombre de la persona responsable de la edición. Sin embargo, ten en cuenta que las invitaciones a revisar quedan a discreción quien se encuentra a cargo de la edición, y es muy posible que ya haya realizado invitaciones. Por favor, no te ofrezcas para revisar en todos los issues y no te presentes a través de la interfaz de GitHub.
Para otras formas de contribuir, consulta la Guía de contribución de rOpenSci.
+Las revisiones deben basarse en la versión actual de GitHub en la rama por defecto, a menos que se indique lo contrario. Todos los envíos generan un informe detallado sobre la estructura y funcionalidad del paquete, generado por nuestro paquete pkgcheck. Si el paquete ha cambiado sustancialmente desde las últimas revisiones, puedes solicitar una nueva revisión con el comando @ropensci-review-bot check package. Ten en cuenta que, al instalar el paquete para revisarlo, debes asegurarte de que tienes todas las dependencias necesarias (por ejemplo usa pak::pak()).
Para revisar un paquete, empieza por copiar nuestra plantilla de revisión (o nuestra plantilla de revisión en español) y utilízala como lista de verificación general. Además de marcar los criterios mínimos, te pedimos que hagas comentarios generales sobre lo siguiente:
+Por favor, en tus revisiones dirígete con respeto y amabilidad hacia las personas que presentaron el paquete. Nuestro código de conducta es obligatorio para quienes participan en nuestro proceso de revisión. Esperamos que envíes tu revisión en un plazo de 3 semanas, según el plazo establecido por la persona a cargo de la edición. Por favor, ponte en contacto con esta persona directamente o mediante el issue de envío para informarle de posibles retrasos.
+Te recomendamos usar herramientas automatizadas para facilitar tu revisión. Éstas incluyen
+@ropensci-review-bot.devtools::check() y devtools::test() en el paquete para encontrar cualquier error que haya pasado desapercibido en la computadora de quien desarrolló el paquete.skip_on_cran() en tests que usan una API versus saltearse todos los tests en un determinado sistema operativo).pkgdown no va a estar necesariamente actualizada, por lo que recomendamos revisar la documentación del paquete localmente ejecutando pkgdown::build_site().Puedes volver a correr la comprobación del paquete de @ropensci-review-bot en cualquier momento enviando un comentario en el issue de revisión con el contenido “@ropensci-review-bot check package”.
Si interactúas con quienes desarrollaron el paquete y hablas de la revisión fuera de un issue de revisión (en chats, DMs, en persona, issues en el repositorio del proyecto), asegúrate de que tu revisión refleje y/o enlace los elementos de estas conversaciones que sean relevantes para el proceso.
+Si es la primera vez que revisas un paquete, puede resultarte útil leer algunas revisiones anteriores. En general, puedes encontrar issues de presentación de paquetes aceptados aquí. Estas son algunas revisiones seleccionadas en inglés (ten en cuenta que tus reseñas no tienen que ser tan largas como estos ejemplos):
+rtika revisión 1 y revisión 2
NLMR revisión 1 y revisión 2
bowerbird comentario previo a la revisión, revisión 1, revisión 2.
rusda revisión (previo a que tuviéramos una plantilla de revisión)
Puedes leer los artículos del blog sobre experiencias al revisar paquetes a través de este enlace. En particular esta publicación de Mara Averick (en inglés) habla como puedes proporcionar una devolución útil aún careciendo de experticia en el tema o en la implementación del paquete adoptando el rol de “persona ingenua” y preguntándote “¿Qué creo que hace esta cosa? ¿lo hace? ¿qué cosas me producen rechazo?” En otro artículo de blog Verena Haunschmid explica cómo alternó entre usar el paquete y revisar el código.
+Como antiguo revisor y autor de paquetes, Adam Sparks escribió lo siguiente “[escribe] una buena crítica de la estructura del paquete y de las mejores prácticas de escritura de código. Si sabes cómo hacer algo mejor, dímelo. Como desarrollador es fácil pasar por alto oportunidades de documentación, pero como al hacer la revisión, tienes una visión diferente. Eres una persona que puede dar devolución. ¿Qué no está claro en el paquete? ¿Cómo puede hacerse más claro? Si lo utilizas por primera vez, ¿es fácil? ¿Conoces otro paquete R que quizás debería utilizar? ¿O hay alguno que esté utilizando y que quizás no debería? Si puedes contribuir al paquete, ofrécete”.
+Si trabajas en RStudio, puedes agilizar tu flujo de trabajo de revisión utilizando el paquete pkgreviewr creado por la editora asociada Anna Krystalli. Digamos que aceptas revisar el paquete refnet, escribirías
remotes::install_github("ropensci-org/pkgreviewr")
+library(pkgreviewr)
+pkgreview_create(pkg_repo = "embruna/refnet",
+ review_parent = "~/Documents/workflows/rOpenSci/reviews/")Esto
+refnet,Ten en cuenta que si el paquete no se envía a través de la branch principal o por defecto, tienes que cambiar a la branch usada para enviar antes de comenzar tu revisión.
+Te animamos a que preguntes y opines sobre el proceso de revisión en nuestro foro.
+Las personas que enviaron el paquete a revisón deben responder en un plazo de 2 semanas con sus cambios en el paquete en respuesta a tu revisión. En esta fase, te pedimos que respondas si los cambios abordan suficientemente las cuestiones planteadas en tu revisión. Fomentamos el debate continuo entre quienes enviaron el paquete y quienes lo revisan, y también puedes pedir que quienes están a cargo de la edición aclaren cosas en el mismo hilo.
+Guide for package authors, maintainers, reviewers and editors in rOpenSci software peer-review system. 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.
+
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License. Refer to its Zenodo DOI to cite it.
@software{ropensci_2024_10797633,
+ author = {rOpenSci and
+ Anderson, Brooke and
+ Chamberlain, Scott and
+ DeCicco, Laura and
+ Gustavsen, Julia and
+ Krystalli, Anna and
+ Lepore, Mauro and
+ Mullen, Lincoln and
+ Ram, Karthik and
+ Ross, Noam and
+ Salmon, Maëlle and
+ Vidoni, Melina and
+ Riederer, Emily and
+ Sparks, Adam and
+ Hollister, Jeff},
+ title = {rOpenSci Packages: Development, Maintenance, and
+ Peer Review
+ },
+ month = mar,
+ year = 2024,
+ publisher = {Zenodo},
+ version = {0.9.0},
+ doi = {10.5281/zenodo.10797633},
+ url = {https://doi.org/10.5281/zenodo.10797633},
+}
+You can also read the PDF version of this book.
+ + ++This chapter presents our guidance for taking 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 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 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.
+role = c("aut", "cre"), and make the former maintainer aut only.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:
+How much can/should you change in the package?
+For general help on changing code in a package, see the Package 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.
+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.
++A reminder of infrastructure and contact channels for maintainers of rOpenSci packages. +
+If you need punctual help (say, a PR review; or some CI troubleshooting), or help looking for co-maintainers or a new maintainer, or if you need us to retire your package, ping us in GitHub via @ropensci/admin or email info@ropensci.org. You can also use our slack package maintenance channel.
Never hesitate to ask for help.
+You should have administrative access to your package’s GitHub repository. If that is no longer the case (say, the automated process failed; or you lost access after having to temporarily deactivate two-factor authentication), please contact us via info@ropensci.org.
If you have any GitHub question or request (adding a collaborator to the GitHub organization for instance) you can use a public channel of the rOpenSci slack workspace or ping @ropensci/admin on GitHub.
See rOpenSci docs.
+Package maintainers and developers should get access to rOpenSci slack. If you did not get the invitation or did not accept it in time, or if you want a new regular contributor receive an invitation please email info@ropensci.org, indicating to which email address you wish to receive the invitation.
You might find the #package-maintenance channel relevant for Q&A as well as friendly commiseration when needed.
+Refer to our blog guide.
+Label issues with “help wanted” to get them broadcasted to the community.
+You can report use cases of your package or encourage users to report them via our forum to get them published on our website and in our newsletter.
+ + ++Having contributors will improve your package, and if you onboard some of them as package authors with write permissions to the repo, your package will be more sustainably developed. It can also be very enjoyable to work as a team! +
++This chapter contains our guidance for collaboration, in a section about making your repo contribution- and collaboration-friendly by infrastructure (code of conduct, contribution guidelines, issue labels); and a section about how to collaborate with new contributors, in particular in the context of the rOpenSci’s “ropensci” GitHub organization. +
++Besides these mostly technical tips, it is important to remember to be kind, and to take others’ perspective into account especially when their priorities differ from yours. +
+After transfer to our GitHub organization, rOpenSci Code of Conduct will apply to your project. Please add this text to the README
+Please note that this package is released with a [Contributor
+Code of Conduct](https://ropensci.org/code-of-conduct/).
+By
+contributing to this project, you agree to abide by its terms.And delete the package current code of conduct if there was one.
+You can use issue, pull request and contributing guidelines. Having a contributing file as .github/CONTRIBUTING.md or docs/CONTRIBUTING.md is compulsory. An easy way to insert a template for a contributing guide is the use_tidy_contributing() function from the usethis package, which inserts this template as .github/CONTRIBUTING.md. A more extensive example is this template by Peter Desmet, or the comprehensive GitHub wiki pages for the mlr3 package. These and other templates will generally need to be modified for use with an rOpenSci package, particularly by referring and linking to our Code of Conduct, as described elsewhere in this book. Modifying a generic contributing guide to add a personal touch also tends to make it look less generic and more sincere. Personal preferences in a contributing guide include:
Style preferences? You might however prefer to make style a configuration (of lintr, styler) or to fix code style yourself especially if you don’t use a popular code style like the tidyverse coding style.
Infrastructure like roxygen2?
Workflow preferences? Issue before a PR?
A scope statement, like in the skimr package?
Sandbox account creation? Mocking in tests? Linking to external docs?
rOpenSci further encourages contributing guides to include a lifecycle statement clarifying visions and expectations for the future development of your package, like in this example. Statistical packages are required to have a lifecycle statement, as specified in General Statistical Stanards G1.2. That links provides a template for a simple lifecycle statement. CONTRIBUTING.md files can also describe how you acknowledge contributions (see this section).
+We encourage you to direct feedback that is not a bug report or a feature request to rOpenSci forum, after making sure you’d see such questions on the forum. Users can use the forum to ask questions about use and report their use cases, and you can subscribe to individual categories and tags to receive notifications about your package. Feel free to mention this in the docs of your package and/or the contributing guidelines/issue template. Please direct your users to tag posts with the package name.
+Once a pull request is closer to being merged, you could use a GitHub Actions PR workflow to style the code with styler.
+By using GitHub features around issues you can help potential contributors find them, and make your roadmap public.
+You could use one or several issue template(s) to help users fill better bug reports or feature requests. When there are several issue templates, users who click on opening a new issue see a menu that guide their choices.
+You can even configure one of the choices to point to somewhere outside of your repository (for instance a discussion forum).
+Refer to GitHub docs.
+You can use labels such as “help wanted” and “good first issue” to help potential collaborators, including newbies, find your repo. Cf GitHub article. You can also use the “Beginner” label. See examples of beginner issues over all ropensci repos.
+You can pin up to 3 issues by repository that will then appear at the top of your issue tracker as nice issue cards. It can help advertise what your priorities are.
+You can create milestones and assign issues to them, which help see what you plan for the next version of your package for instance.
+You can point users to rOpenSci forum if you monitor it, or enable GitHub Discussions for your package repository. Each GitHub discussion can be converted to an issue if needed (and the other way round, issues can be converted to discussions).
+First thing first: keep in touch with your GitHub repository!
+do not forget to watch your GitHub repository to be notified of issues or pull requests (alternatively, if you work in bursts, maybe add the information to the contributing guide).
do not forget to push updates you have locally.
disable failing tests if you cannot fix them as they create noise in PRs that can puzzle new contributors.
There’s no general rOpenSci rule as to how you should onboard collaborators. You should increase their rights to the repo as you gain trust, and you should definitely acknowledge contributions (see this section).
+You can ask a new collaborator to make PRs (see following section for assessing a PR locally, i.e. beyond CI checks) to dev/main and assess them before merging, and after a while let them push to main, although you might want to keep a system of PR reviews… even for yourself once you have team mates!
+A possible model for onboarding collaborators is provided by Jim Hester in his lintr repo.
If your problem is recruiting collaborators, you can post an open call like Jim Hester’s on Twitter, GitHub, and as an rOpenSci package author, you can ask for help in rOpenSci slack and ask rOpenSci team for ideas for recruiting new collaborators.
+Branches are cheap. Use them extensively when developing features, testing out new ideas, fixing problems.
+One of the branches is the default / main branch, where, if you follow trunk-based development, you “merge small, frequent updates”. See also GitHub flow and GitLab flow docs. You might want to frequently increment version numbers (in DESCRIPTION). One particular aspect of working with collaborators is reviewing pull requests, with some useful guidance in:
You might want to tinker with your GitHub repository settings to, for instance, require pull request reviews before merging. See also GitHub docs about “code owners”.
+For making and reviewing pull requests we recommend exploring usethis functions.
+For your “git remote” setup refer to happy git with r. See also Useful Git patterns for real life in the same book.
+If someone contributes to your repository consider adding them in DESCRIPTION, as contributor (“ctb”) for small contributions, author (“aut”) for bigger contributions. Traditionally when citing a package in a scientific publication only “aut” authors are listed, not “ctb” contributors; and on pkgdown websites only “aut” names are listed on the homepage, all authors being listed on the authors/ page.
At a minimum consider adding the name of contributors near the feature/bug fix line in NEWS.md.
+We recommend your being generous with such acknowledgements, because it is a nice thing to do and because it will make folks more likely to contribute again to your package or other repos of the organization.
+As a reminder from our packaging guidelines if your package was reviewed and you feel that your reviewers have made a substantial contribution to the development of your package, you may list them in the Authors@R field with a Reviewer contributor type ("rev"), like so:
person("Bea", "Hernández", role = "rev",
+ comment = "Bea reviewed the package (v. X.X.XX) for rOpenSci, see <https://github.com/ropensci/software-review/issues/116>"),Only include reviewers after asking for their consent. Read more in this blog post “Thanking Your Reviewers: Gratitude through Semantic Metadata”. Note that ‘rev’ will raise a CRAN NOTE unless the package is built using R v3.5. Make sure you use roxygen2’s latest CRAN version.
Please do not list editors as contributors. Your participation in and contribution to rOpenSci is thanks enough!
+If you give someone write permissions to the repository,
+please contact a staff member so that this new contributor might get invited to rOpenSci’s “ropensci” GitHub organization (instead of being an outside collaborator)
please contact rOpenSci’s community manager or another staff member so that this new contributor might get get invited to rOpenSci Slack workspace.
+This chapter describes our Contributing Guide that outlines how you can make code and non-code contributions to the rOpenSci project. +
+So you want to contribute to rOpenSci? Fantastic! We developed the rOpenSci Community Contributing Guide to welcome you to rOpenSci and help you recognize yourself as a potential contributor. It will help you figure out what you might gain by giving your time, expertise, and experience, match your needs with things that will help rOpenSci’s mission, and connect you with resources to help you along the way.
+Our staff and community actively foster a welcoming environment where users and developers from different backgrounds and skill levels learn, share ideas and innovate together openly through shared norms and shared software. Participation in all rOpenSci activities is supported by our Code of Conduct.
+We welcome code and non-code contributions from new and seasoned coders at any career stage, and in any sector. You don’t have to be a developer! Maybe you want to spend 30 minutes sharing your package use case in our public forum or reporting a bug, one hour learning by attending a Community Call, five hours reviewing an R package submitted for open peer review, or maybe you want to make an ongoing commitment to help maintain a package.
+What are some benefits of contributing?
+Consult our Contributing Guide and browse “What brings you here?” to find which I want to … statements fit you best and choose your path! To help you recognize yourself, we’ve grouped these into: Discover; Connect; Learn; Build; Help. For each category, we list examples of what those contributions might look like and we link to our resources for the details you need.
+ + + ++This chapter summarizes a proposed curation policy for rOpenSci’s ongoing maintenance of packages developed as part of rOpenSci activities and/or under the rOpenSci GitHub organization. This curation policy aims to support these goals: +
++Ensure packages provided by rOpenSci are up-to-date and high quality +
++Provide clarity as to the development status and and review status of any software in rOpenSci repositories +
++Manage maintenance effort for rOpenSci staff, package authors, and volunteer contributors +
++Provide a mechanism to gracefully sunset packages while maintaining peer-review badging +
+Elements of infrastructure described below needed for implementation of the policy are in some cases partly built and in other cases not yet begun. We aim to adopt this policy in part to prioritize work on these components.
+Staff-maintained packages are developed and maintained by rOpenSci staff as part of rOpenSci projects. These packages may also be peer-reviewed packages, but are not necessarily peer reviewed. Many are infrastructure packages that fall out of scope for peer review.
+Staff-maintained packages will be listed in the registry with tag “staff_maintained” and listed on rOpenSci’s packages web page or similar venues with tag “staff-maintained”
These packages will be stored in the “ropensci” GitHub organization
Staff-maintained packages and their docs will be built by rOpenSci system. This system does not send notifications but it outputs results as GitHub commit status (red check mark or red cross).
When the packages fail checks, rOpenSci staff will endeavor to fix changes, prioritizing packages based on user base (downloads), reverse dependencies, or strategic goals.
On a biannual or annual basis, rOpenSci will review all packages that have been failing for over a month to determine whether to transfer them to the “ropensci-archive” GitHub organization.
Packages consistently failing and without an ongoing plan to return to active maintenance will move to “archive” status. When archived, staff packages will move to the “ropensci-archive” repository (to be created) and and gain the “archived” type in the registry. They will not be built on rOpenSci system.
Archived packages will not be displayed by default on the packages web page. A special tab of packages pages will display these with "type": "archived" that were either peer-reviewed or staff-maintained.
Archived packages can be unarchived when the old or a new maintainer is willing to address the problems and wants to revive the package. For that please contact rOpenSci. They are transferred to the ropenscilabs organization.
Peer-reviewed packages are those contributed to the rOpenSci by the community and have passed through peer review. They need to be in-scope at the time of submission to be reviewed.
+Upon acceptance, these peer-reviewed packages are transferred from the author’s GitHub to the “ropensci” GitHub organization
Peer-reviewed packages will be in the registry tagged as “peer-reviewed” and have a peer-reviewed badge in their README.
Peer-reviewed packages will be listed on rOpenSci’s web page or similar venues with tag “peer-reviewed”
Peer-reviewed packages and their docs will be built by rOpenSci system. This system does not send notifications but it outputs results as GitHub commit status (red check mark or red cross).
Annually or bi-annually, rOpenSci staff will review packages in a failing state or have been failing for extended periods, and contact the authors to determine ongoing maintenance status and expected updates. Based on this exchange, rOpenSci may opt to retain the package’s current status with the expectation of an updates, contribute support or seek a new maintainer, or transfer the package to “archived” status.
Based on user base (measured by downloads), reverse dependencies, or rOpenSci strategic goals, rOpenSci staff may support failing packages via PRs reviewed by package authors, or direct changes (if authors are unresponsive for approximately a month). rOpenSci will also provide support to package authors on request, both by staff and community volunteers, based on time available.
At the author’s request, or if authors are unresponsive to inquiries for approximately a month, rOpenSci may seek a new maintainer for select peer-reviewed packages it deems have high community value based on user base/downloads, reverse dependencies, or rOpenSci strategic goals.
When archived, these packages will move from the “ropensci” GitHub organization to the “ropensci-archive” organization (or author GitHub accounts if desired), following transfer guidance. They will gain the “archived” type in the registry. They will retain “peer-reviewed” tags and badges. They will not be built on rOpenSci system.
Archived packages will not be displayed by default. A special tab of packages pages will display these with "type": "archived" that were either peer-reviewed or staff-maintained.
“Legacy” packages are packages not created or maintained by rOpenSci staff and not peer reviewed, but are under the rOpenSci GitHub organization(s) due to historical reasons. (Prior to establishing the peer review process and its scope, rOpenSci absorbed packages from various developers without well-defined criteria.)
+rOpenSci will transfer legacy packages back to author organizations and repositories. If authors are uninterested, we will transfer them to the “ropensci-archive” repository following transfer guidance. If packages are in-scope, rOpenSci will inquire if authors would like to submit them to the Software Review process.
Legacy packages will not be listed in the package registry.
Exceptions may be made for packages that are vital parts of the R and/or rOpenSci package ecosystem which are actively monitored by staff.
“Incubator” packages are in-development packages created by staff or community members as part of community projects, such as those created at unconferences
+Incubator packages will live in the “ropenscilabs” organization.
Incubator packages will appear in the package registry with the “incubator” tag
Incubator packages will not appear on the website by default, but packages pages will include an “experimental packages” tab.
Incubator packages and their docs will be built by rOpenSci system. This system does not send notifications but it outputs results as GitHub commit status (red check mark or red cross). The docs will indicate clearly the package is experimental.
Biannually or annually, rOpenSci will contact incubator maintainers about repositories at least three months old, inquiring about development status and author preferences for migration to peer-review, ropensci-archive, or to author organizations. Based on response, package will be migrated immediately, peer review will be initiated, or migration will be deferred to the next review. Incubator packages will be migrated to ropensci-archive by default after one year, following transfer guidance.
Archived incubator packages will gain the “archived” type.
The “incubator” organization will also include non-R-package projects.
These projects will not be listed in the registry or appear on a web page, and will not be automatically built.
Migration policy will be the same as for R packages, with appropriate migration locations (e.g., ropensci-books)
If archived, non-R-packages will move to “ropensci-archive” following transfer guidance.
rOpenSci books are long-form documentation, often bookdown-formatted, related to rOpenSci packages, projects, or themes, created by both rOpenSci staff and community members.
+Books will live in the “ropensci-books” organization
Books will be hosted at books.ropensci.org
Books may be mature or in-development, but must have minimal outlines/content before migrating into “ropensci-books” (e.g. from “ropenscilabs”).
The authorship and development status of a book should be clearly described on its home page and README.
rOpenSci may provide badges or templates (e.g., “In development,” “Community Maintained,”) for authors to use on book home pages in the future
+This chapter presents our guidance for changing stuff in your package: changing parameter names, changing function names, deprecating functions, and even retiring and archiving packages. +
++This chapter was initially contributed as a tech note on rOpenSci website by Scott Chamberlain; you can read the original version here. +
+Everyone’s free to have their own opinion about how freely parameters/functions/etc. are changed in a library - rules about package changes are not enforced by CRAN or otherwise. Generally, as a library gets more mature, changes to user facing methods (i.e., exported functions in an R package) should become very rare. Libraries that are dependencies of many other libraries are likely to be more careful about changes, and should be.
+This chapter presents solutions that do not require the lifecycle package but you might still find it useful. We recommend reading the lifecycle documentation.
+Sometimes parameter names must be changed for clarity, or some other reason.
+A possible approach is check if deprecated arguments are not missing, and stop providing a meaningful message.
+foo_bar <- function(x, y) {
+ if (!missing(x)) {
+ stop("use 'y' instead of 'x'")
+ }
+ y^2
+}
+
+foo_bar(x = 5)
+#> Error in foo_bar(x = 5) : use 'y' instead of 'x' If you want to be more helpful, you could emit a warning but automatically take the necessary action:
+foo_bar <- function(x, y) {
+ if (!missing(x)) {
+ warning("use 'y' instead of 'x'")
+ y <- x
+ }
+ y^2
+}
+
+foo_bar(x = 5)
+#> 25Be aware of the parameter .... If your function has ..., and you have already removed a parameter (lets call it z), a user may have older code that uses z. When they pass in z, it’s not a parameter in the function definition, and will likely be silently ignored – not what you want. Instead, leave the argument around, throwing an error if it used.
If you must change a function name, do it gradually, as with any other change in your package.
+Let’s say you have a function foo.
foo <- function(x) x + 1However, you want to change the function name to bar.
Instead of simply changing the function name and foo no longer existing straight away, in the first version of the package where bar appears, make an alias like:
#' foo - add 1 to an input
+#' @export
+foo <- function(x) x + 1
+
+#' @export
+#' @rdname foo
+bar <- fooWith the above solution, the user can use either foo() or bar() – either will do the same thing, as they are the same function.
It’s also useful to have a message but then you’ll only want to throw that message when they use the old function, e.g.,
+#' foo - add 1 to an input
+#' @export
+foo <- function(x) {
+ warning("please use bar() instead of foo()", call. = FALSE)
+ bar(x)
+}
+
+#' @export
+#' @rdname foo
+bar <- function(x) x + 1After users have used the package version for a while (with both foo and bar), in the next version you can remove the old function name (foo), and only have bar.
#' bar - add 1 to an input
+#' @export
+bar <- function(x) x + 1To remove a function from a package (let’s say your package name is helloworld), you can use the following protocol:
x (e.g., v0.2.0)In the function itself, use .Deprecated() to point to the replacement function:
foo <- function() {
+ .Deprecated("bar")
+}There’s options in .Deprecated for specifying a new function name, as well as a new package name, which makes sense when moving functions into different packages.
The message that’s given by .Deprecated is a warning, so can be suppressed by users with suppressWarnings() if desired.
Make a man page for deprecated functions like:
+#' Deprecated functions in helloworld
+#'
+#' These functions still work but will be removed (defunct) in the next version.
+#'
+#' \itemize{
+#' \item \code{\link{foo}}: This function is deprecated, and will
+#' be removed in the next version of this package.
+#' }
+#'
+#' @name helloworld-deprecated
+NULLThis creates a man page that users can access like ?`helloworld-deprecated` and they’ll see in the documentation index. Add any functions to this page as needed, and take away as a function moves to defunct (see below).
v0.3.0) you can make the function defunct (that is, completely gone from the package, except for a man page with a note about it).In the function itself, use .Defunct() like:
foo <- function() {
+ .Defunct("bar")
+}Note that the message in .Defunct is an error so that the function stops whereas .Deprecated uses a warning that let the function proceed.
In addition, it’s good to add ... to all defunct functions so that if users pass in any parameters they’ll get the same defunct message instead of a unused argument message, so like:
foo <- function(...) {
+ .Defunct("bar")
+}Without ... gives:
foo(x = 5)
+#> Error in foo(x = 5) : unused argument (x = 5)And with ... gives:
foo(x = 5)
+#> Error: 'foo' has been removed from this packageMake a man page for defunct functions like:
+#' Defunct functions in helloworld
+#'
+#' These functions are gone, no longer available.
+#'
+#' \itemize{
+#' \item \code{\link{foo}}: This function is defunct.
+#' }
+#'
+#' @name helloworld-defunct
+NULLThis creates a man page that users can access like ?`helloworld-defunct` and they’ll see in the documentation index. Add any functions to this page as needed. You’ll likely want to keep this man page indefinitely.
You don’t have to change the tests of deprecated functions until they are made defunct.
+.Deprecated inside the function, did you change the parameters at all in the deprecated function, or create a new function that replaces the deprecated function, etc. Those changes should be tested if any made.suppressWarnings() could be used to suppress the warning thrown from .Deprecated, but tests are not user facing, so it is not that bad if the warning is thrown in tests, and the warning could even be used as a reminder to the maintainer.Once a function is made defunct, its tests are simply removed.
+Software generally has a finite lifespan, and packages may eventually need to be archived. Archived packages are archived and moved to a dedicated GitHub organization, ropensci-archive. Prior to archiving, the contents of the README file should be moved to an alternative location (such as “README-OLD.md”), and replaced with minimal contents including something like the following:
+# <package name>
+
+[](https://www.repostatus.org/#unsupported)
+[](https://github.com/ropensci/software-review/issues/<issue_number>)
+
+This package has been archived. The former README is now in [README-old](<link-to-README-old>).The repo status badge should be “unsupported” for formerly released packages, or “abandoned” for former concept or WIP packages, in which case the badge code above should be replaced with:
+[](https://www.repostatus.org/#abandoned)An example of a minimal README in an archived package is in ropensci-archive/monkeylearn. Once the README has been copied elsewhere and reduced to minimal form, the following steps should be followed:
+Archived packages may be unarchived if authors or a new person opt to resume maintenance. For that please contact rOpenSci. They are transferred to the ropenscilabs organization.
+ + ++rOpenSci packages are currently in their vast majority developed on GitHub. Here are a few tips to leverage the platform in a section about making your repo more discoverable and a section about marketing your own GitHub account after going through peer review. +
+GitHub repo topics help browsing and searching GitHub repos, are used by R-universe on package pages and for search results, and are digested by codemetar for rOpenSci registry keywords.
We recommend:
+Adding “r”, “r-package” and “rstats” as topics to your package repo.
Adding any other relevant topics to your package repo.
We might make suggestions to you after your package is onboarded.
+GitHub linguist will assign a language for your repo based on the files it contains. Some packages containing a lot of C++ code might get classified as C++ rather than R packages, which is fine and shows the need for the “r”, “r-package” and “rstats” topics.
+We recommend overriding GitHub linguist by adding or modifying a .gitattributes to your repo in two cases:
+If you store html files in non standard places (not in docs/, e.g. in vignettes/) use the documentation overrides. Add *.html linguist-documentation=true to .gitattributes (Example in the wild)
If your repo contains code you haven’t authored, e.g. JavaScript code, add inst/js/* linguist-vendored to .gitattributes (Example in the wild)
This way the language classification and statistics of your repository will more closely reflect the source code it contains, as well as making it more discoverable. Notably, if linguist does not correctly recognize your repo as containing mainly R code, your package won’t appear in search results with the language:R filter. Similarly, your repo cannot be listed among the trending R repos.
More info about GitHub linguist overrides here.
+As the author of an onboarded package, you are now a member of rOpenSci’s “ropensci” GitHub organization. By default, organization memberships are private; see how to make it public in GitHub docs.
Even after your package repo has been transferred to rOpenSci, you can pin it under your own account.
In general we recommend adding at least an avatar (which doesn’t need to be your face!) and your name to your GitHub profile.
+We will help you promoting your package but here are some more things to keep in mind. +
+If you hear of an use case of your package, please encourage its author to post the link to our discussion forum in the Use Cases category, for a toot (Mastodon post) from rOpenSci and inclusion in the rOpenSci monthly newsletter. We also recommend you to add a link to the use case in a “use cases in the wild” section of your README.
Post about your package on Mastodon using the “#rstats” hashtag and tag rOpenSci! This might help with contributor/user engagement. Example posts from rOpenSci itself: A package a day, Help wanted post, Use cases, Welcome post.
When you release a new version of your package or release it to CRAN for the first time,
+Make a pull request to R Weekly with a line about the release under the “New Releases” section (or “New Packages” for the first GitHub/CRAN release).
Post about it on social media.
Consider submitting a short post about the release to rOpenSci tech notes. Contact rOpenSci Community Manager, (e.g. via Slack or info@ropensci.org). Refer to the guidelines about contributing a blog post).
Submit your package to lists of packages such as CRAN Task Views.
If you choose to market your package by giving a talk about it at a meetup or conference (excellent idea!) read this article of Jenny Bryan’s and Mara Averick’s.
+Your package should have different versions over time: snapshots of a state of the package that you can release to CRAN for instance. These versions should be properly numbered, released and described in a NEWS file. More details below. +
+
+Note that you could streamline the process of updating NEWS and versioning your package by using the fledge package.
+
Using usethis::use_release_issue() and devtools::release() will help you remember about more checks.
Git tag each release after every submission to CRAN. more info
CRAN does not like too frequent updates. That said, if you notice a major problem one week after a CRAN release, explain it in cran-comments.md and try releasing a newer version.
A NEWS file describing changes associated with each version makes it easier for users to see what’s changing in the package and how it might impact their workflow. You must add one for your package, and make it easy to read.
+NEWS or NEWS.md file in the root of your package. We recommend using NEWS.md to make the file more browsable.taxize package repo for instance.NEWS, add it to .Rbuildignore, but not if you use NEWS.md
+foobar 0.2.0 (2016-04-01)
+=========================NEW FEATURES, MINOR IMPROVEMENTS, BUG FIXES, DEPRECATED AND DEFUNCT, DOCUMENTATION FIXES and any special heading grouping a large number of changes. Under each header, list items as needed (as seen in our example NEWS file). For each item give a description of the new feature, improvement, bug fix, or deprecated function/feature. Link to any related GitHub issue like (#12). The (#12) will resolve on GitHub in Releases to a link to that issue in the repo.git tag and pushed up to GitHub, add the news items for that tagged version to the Release notes of a release in your GitHub repo with a title like pkgname v0.1.0. See GitHub docs about creating a release.
+foobar 0.2.0 (2016-04-01)
+=========================
+
+### NEW FEATURES
+
+ * New function added `do_things()` to do things (#5)
+
+### MINOR IMPROVEMENTS
+
+ * Improved documentation for `things()` (#4)
+
+### BUG FIXES
+
+ * Fix parsing bug in `stuff()` (#3)
+
+### DEPRECATED AND DEFUNCT
+
+ * `hello_world()` now deprecated and will be removed in a
+ future version, use `hello_mars()`
+
+### DOCUMENTATION FIXES
+
+ * Clarified the role of `hello_mars()` vs. `goodbye_mars()`
+
+
+### (a special: any heading grouping a large number of changes under one thing)
+
+ * blablabla.
+
+foobar 0.1.0 (2016-01-01)
+=========================
+
+### NEW FEATURES
+
+ * released to CRAN+rOpenSci accepts packages that meet our guidelines via a streamlined Software Peer Review process. To ensure a consistent style across all of our tools we have written this chapter highlighting our guidelines for package development. Please also read and apply our chapter about continuous integration (CI). Further guidance for after the review process is provided in the third section of this book starting with a chapter about collaboration. +
++We recommend that package developers read Hadley Wickham and Jenny Bryan’s thorough book on package development which is available for free online. Our guide is partially redundant with other resources but highlights rOpenSci’s guidelines. +
++To read why submitting a package to rOpenSci is worth the effort to meet guidelines, have a look at reasons to submit. +
+We strongly recommend short, descriptive names in lower case. If your package deals with one or more commercial services, please make sure the name does not violate branding guidelines. You can check if your package name is available, informative and not offensive by using the pak::pkg_name_check() function; also use a search engine as you’d thus see if it’s offensive in a language other than English. In particular, do not choose a package name that’s already used on CRAN or Bioconductor.
There is a trade-off between the advantages of a unique package name and a less original package name.
+Find other interesting aspects of naming your package in this blog post by Nick Tierney, and in case you change your mind, find out how to rename your package in this other blog post of Nick’s.
We recommend you to use the codemetar package for creating and updating a JSON CodeMeta metadata file for your package via codemetar::write_codemeta(). It will automatically include all useful information, including GitHub topics. CodeMeta uses Schema.org terms so as it gains popularity the JSON metadata of your package might be used by third-party services, maybe even search engines.
Functions and arguments naming should be chosen to work together to form a common, logical programming API that is easy to read, and auto-complete.
+object_verb() naming scheme for functions in your package that take a common data type or interact with a common API. object refers to the data/API and verb the primary action. This scheme helps avoid namespace conflicts with packages that may have similar verbs, and makes code readable and easy to auto-complete. For instance, in stringi, functions starting with stri_ manipulate strings (stri_join(), stri_sort(), and in googlesheets functions starting with gs_ are calls to the Google Sheets API (gs_auth(), gs_user(), gs_download()).For functions that manipulate an object/data and return an object/data of the same type, make the object/data the first argument of the function so as to enhance compatibility with the pipe operators (base R’s |>, magrittr’s %>%).
We strongly recommend snake_case over all other styles unless you are porting over a package that is already in wide use.
Avoid function name conflicts with base packages or other popular ones (e.g. ggplot2, dplyr, magrittr, data.table)
Argument naming and order should be consistent across functions that use similar inputs.
Package functions importing data should not import data to the global environment, but instead must return objects. Assignments to the global environment are to be avoided in general.
Use either the cli package, or base R’s tools (message() and warning()) to communicate with the user in your functions.
Highlights of the cli package include: automatic wrapping, respect of the NO_COLOR convention, many semantic elements, and extensive documentation. Read more in a blog post.
Please do not use print() or cat() unless it’s for a print.*() or str.*() methods, as these methods of printing messages are harder for users to suppress.
Provide a way for users to opt out of verbosity, preferably at the package level: make message creation dependent on an environment variable or option (like “usethis.quiet” in the usethis package), rather than on a function parameter. The control of messages could be on several levels (“none,”inform”, “debug”) rather than logical (no messages at all / all messages). Control of verbosity is useful for end users but also in tests. More interesting comments can be found in an issue of the tidyverse design guide.
If providing graphical user interface (GUI) (such as a Shiny app), to facilitate workflow, include a mechanism to automatically reproduce steps taken in the GUI. This could include auto-generation of code to reproduce the same outcomes, output of intermediate values produced in the interactive tool, or simply clear and well-documented mapping between GUI actions and scripted functions. (See also “Testing” below.)
+The tabulizer package e.g. has an interactive workflow to extract tables, but can also only extract coordinates so one can re-run things as a script. Besides, two examples of shiny apps that do code generation are https://gdancik.shinyapps.io/shinyGEO/, and https://github.com/wallaceEcoMod/wallace/.
We recommend your package use a consistent method of your choice for checking inputs – either base R, an R package, or custom helpers.
+If your package accesses a web API or another web resource,
+gh::gh()).For more information refer to the blog post Why You Should (or Shouldn’t) Build an API Client.
+For more information on how to style your code, name functions, and R scripts inside the R/ folder, we recommend reading the code chapter in The R Packages book. We recommend the styler package for automating part of the code styling. We suggest reading the Tidyverse style guide.
You can choose to use = over <- as long you are consistent with one choice within your package. We recommend avoiding the use of -> for assignment within a package. If you do use <- throughout your package, and you also use R6 in that package, you’ll be forced to use = for assignment within your R6Class construction - this is not considered an inconsistency because you can’t use <- in this case.
If your package does not yet have a CITATION file, you can create one with usethis::use_citation(), and populate it with values generated by the citation() function.
CRAN requires CITATION files to be declared as bibentry items, and not in the previously-accepted form of citEntry().
If you archive each release of your GitHub repo on Zenodo, add the Zenodo top-level DOI to the CITATION file.
If one day after review at rOpenSci you publish a software publication about your package, add it to the CITATION file.
Less related to your package itself but to what supports it: if your package wraps a particular resource such as data source or, say, statistical algorithm, remind users of how to cite that resource via e.g. citHeader(). Maybe even add the reference for the resource.
As an example see the dynamite CITATION file which refers to the R manual as well as other associated publications.
+citHeader("To cite dynamite in publications use:")
+
+bibentry(
+ key = "dynamitepaper",
+ bibtype = "Misc",
+ doi = "10.48550/ARXIV.2302.01607",
+ url = "https://arxiv.org/abs/2302.01607",
+ author = c(person("Santtu", "Tikka"), person("Jouni", "Helske")),
+ title = "dynamite: An R Package for Dynamic Multivariate Panel Models",
+ publisher = "arXiv",
+ year = "2023"
+)
+
+bibentry(
+ key = "dmpmpaper",
+ bibtype = "Misc",
+ title = "Estimating Causal Effects from Panel Data with Dynamic
+ Multivariate Panel Models",
+ author = c(person("Santtu", "Tikka"), person("Jouni", "Helske")),
+ publisher = "SocArxiv",
+ year = "2022",
+ url = "https://osf.io/preprints/socarxiv/mdwu5/"
+)
+
+bibentry(
+ key = "dynamite",
+ bibtype = "Manual",
+ title = "Bayesian Modeling and Causal Inference for Multivariate
+ Longitudinal Data",
+ author = c(person("Santtu", "Tikka"), person("Jouni", "Helske")),
+ note = "R package version 1.0.0",
+ year = "2022",
+ url = "https://github.com/ropensci/dynamite"
+)CITATION.cff thanks to the cffr package. It also provides a GitHub Action workflow to keep the CITATION.cff file up-to-date.All packages should have a README file, named README.md, in the root of the repository. The README should include, from top to bottom:
If you use another repo status badge such as a lifecycle badge, please also add a repostatus.org badge. Example of a repo README with two repo status badges.
+[](https://github.com/ropensci/software-review/issues/<issue_id>)where issue_id is the number of the issue in the software-review repository. For instance, the badge for rtimicropem review uses the number 126 since it’s the review issue number. The badge will first indicated “under review” and then “peer-reviewed” once your package has been onboarded (issue labelled “approved” and closed), and will link to the review issue.
If your README has many badges consider ordering them in an html table to make it easier for newcomers to gather information at a glance. See examples in drake repo and in qualtRics repo. Possible sections are
If your package connects to a data source or online service, or wraps other software, consider that your package README may be the first point of entry for users. It should provide enough information for users to understand the nature of the data, service, or software, and provide links to other relevant data and documentation. For instance, a README should not merely read, “Provides access to GooberDB,” but also include, “…, an online repository of Goober sightings in South America. More information about GooberDB, and documentation of database structure and metadata can be found at link”.
We recommend not creating README.md directly, but from a README.Rmd file (an R Markdown file) if you have any demonstration code. The advantage of the .Rmd file is you can combine text with code that can be easily updated whenever your package is updated.
Consider using usethis::use_readme_rmd() to get a template for a README.Rmd file and to automatically set up a pre-commit hook to ensure that README.md is always newer than README.Rmd.
Extensive examples should be kept for a vignette. If you want to make the vignettes more accessible before installing the package, we suggest creating a website for your package.
See the gistr README for a good example README to follow for a small package, and bowerbird README for a good example README for a larger package.
All exported package functions should be fully documented with examples.
If there is potential overlap or confusion with other packages providing similar functionality or having a similar name, add a note in the README, main vignette and potentially the Description field of DESCRIPTION. Examples in rtweet README, rebird README, and the non-rOpensci package slurmR.
The package should contain top-level documentation for ?foobar, (or ?`foobar-package` if there is a naming conflict). Optionally, you can use both ?foobar and ?`foobar-package` for the package level manual file, using @aliases roxygen tag. usethis::use_package_doc() adds the template for the top-level documentation.
The package should contain at least one HTML vignette providing a substantial coverage of package functions, illustrating realistic use cases and how functions are intended to interact. If the package is small, the vignette and the README may have very similar content.
As is the case for a README, top-level documentation or vignettes may be the first point of entry for users. If your package connects to a data source or online service, or wraps other software, it should provide enough information for users to understand the nature of the data, service, or software, and provide links to other relevant data and documentation. For instance, a vignette intro or documentation should not merely read, “Provides access to GooberDB,” but also include, “…, an online repository of Goober sightings in South America. More information about GooberDB, and documentation of database structure and metadata can be found at link”. Any vignette should outline prerequisite knowledge to be able to understand the vignette upfront.
The general vignette should present a series of examples progressing in complexity from basic to advanced usage.
+Functionality likely to be used by only more advanced users or developers might be better put in a separate vignette (e.g. programming/NSE with dplyr).
The README, the top-level package docs, vignettes, websites, etc., should all have enough information at the beginning to get a high-level overview of the package and the services/data it connects to, and provide navigation to other relevant pieces of documentation. This is to follow the principle of multiple points of entry i.e. to take into account the fact that any piece of documentation may be the first encounter the user has with the package and/or the tool/data it wraps.
The vignette(s) should include citations to software and papers where appropriate.
If your package provides access to a data source, we require that DESCRIPTION contains both (1) A brief identification and/or description of the organisation responsible for issuing data; and (2) The URL linking to public-facing page providing, describing, or enabling data access (which may often differ from URL leading directly to data source).
Only use package startup messages when necessary (function masking for instance). Avoid package startup messages like “This is foobar 2.4-0” or citation guidance because they can be annoying to the user. Rely on documentation for such guidance.
You can choose to have a README section about use cases of your package (other packages, blog posts, etc.), example.
We request all submissions to use roxygen2 for documentation. roxygen2 is an R package that compiles .Rd files to your man folder in your package from tags written above each function. roxygen2 has support for Markdown syntax. One key advantage of using roxygen2 is that your NAMESPACE will always be automatically generated and up to date.
More information on using roxygen2 documentation is available in the R packages book and in roxygen2 website itself.
If you were writing Rd directly without roxygen2, the Rd2roxygen package contains functions to convert Rd to roxygen documentation.
All functions should document the type of object returned under the @return heading.
The default value for each parameter should be clearly documented. For example, instead of writing A logical value determining if ..., you should write A logical value (default `TRUE`) determining if .... It is also good practice to indicate the default values directly in your function definition:
f <- function(a = TRUE) {
+ # function code
+}Documentation should support user navigation by including useful cross-links between related functions and documenting related functions together in groups or in common help pages. In particular, the @family tags, that automatically creates “See also” links and can help group functions together on pkgdown sites, is recommended for this purpose. See the “manual” section of The R Packages book and the “function grouping” section of the present chapter for more details.
You can re-use documentation pieces (e.g. details about authentication, related packages) across the vignettes/README/man pages. Refer to roxygen2 vignette on documentation reuse.
For including examples, you can use the classic @examples tag (plural “examples”) but also the @example <path> tag (singular “example”) for storing the example code in a separate R script (ideally under man/), and the @exampleIf tag for running examples conditionally and avoiding R CMD check failures. Refer to roxygen2 documentation about examples.
Add #' @noRd to internal functions. You might be interested in the devtag experimental package for getting local manual pages when using #' @noRd.
Starting from roxygen2 version 7.0.0, R6 classes are officially supported. See the roxygen2 docs for details on how to document R6 classes.
This subsection is particularly relevant to authors wishing to submit their package to CRAN. CRAN will check URLs in your documentation and does not allow redirect status codes such as 301. You can use the urlchecker package to reproduce these checks and, in particular, replace URLs with the URLs they redirect to. Others have used the option to escape some URLs (change <https://ropensci.org/> to https://ropensci.org/, or \url{https://ropensci.org/} to https://ropensci.org/.), but if you do so, you will need to implement some sort of URL checking yourself to prevent them from getting broken without your noticing. Furthermore, links would not be clickable from local docs.
We recommend creating a documentation website for your package using pkgdown. The R packages book features a chapter on pkgdown, and of course pkgdown has its own documentation website.
There are a few elements we’d like to underline here.
+You only need to worry about automatic deployment of your website until approval and transfer of your package repo to the ropensci organization; indeed, after that a pkgdown website will be built for your package after each push to the GitHub repo. You can find the status of these builds at https://dev.ropensci.org/job/package_name, e.g. for magick; and the website at https://docs.ropensci.org/package_name, e.g. for magick. The website build will use your pkgdown config file if you have one, except for the styling that will use the rotemplate package. The resulting website will have a local search bar. Please report bugs, questions and feature requests about the central builds at https://github.com/ropensci/docs/ and about the template at https://github.com/ropensci/rotemplate/.
If your package vignettes need credentials (API keys, tokens, etc.) to knit, you might want to precompute them since credentials cannot be used on the docs server.
+Before submission and before transfer, you could use the approach documented by pkgdown or the tic package for automatic deployment of the package’s website. This would save you the hassle of running (and remembering to run) pkgdown::build_site() yourself every time the site needs to be updated. First refer to our chapter on continuous integration if you’re not familiar with continuous integration. In any case, do not forget to update all occurrences of the website URL after transfer to the ropensci organization.
When your package has many functions, use grouping in the reference, which you can do more or less automatically.
+If you use roxygen2 above version 6.1.1, you should use the @family tag in your functions documentation to indicate grouping. This will give you links between functions in the local documentation of the installed package (“See also” section) and allow you to use the pkgdown has_concept function in the config file of your website. Non-rOpenSci example courtesy of optiRum: family tag, pkgdown config file and resulting reference section. To customize the text of the cross-reference title created by roxygen2 (Other {family}:), refer to roxygen2 docs regarding how to provide a rd_family_title list in man/roxygen/meta.R.
Less automatically, see the example of drake website and associated config file.
Once your package is transferred and it gets a website using our pkgdown template, if you want to use Mathjax you’ll need to specify it in the pkgdown config file like so:
template:
+ params:
+ mathjax: trueTo use your package logo in the pkgdown homepage, refer to usethis::use_logo(). If your package doesn’t have any logo, the rOpenSci docs builder will use rOpenSci logo instead.
The package needs to have a CRAN or OSI accepted license. For more explanations around licensing, refer to the R packages book.
+All packages should pass R CMD check/devtools::check() on all major platforms.
All packages should have a test suite that covers major functionality of the package. The tests should also cover the behavior of the package in case of errors.
It is good practice to write unit tests for all functions, and all package code in general, ensuring key functionality is covered. Test coverage below 75% will likely require additional tests or explanation before being sent for review.
We recommend using testthat for writing tests. Strive to write tests as you write each new function. This serves the obvious need to have proper testing for the package, but allows you to think about various ways in which a function can fail, and to defensively code against those. More information.
Tests should be easy to understand. We suggest reading the blog post “Why Good Developers Write Bad Unit Tests” by Michael Lynch.
Packages with Shiny apps should use a unit-testing framework such as shinytest2 or shinytest to test that interactive interfaces behave as expected.
For testing your functions creating plots, we suggest using vdiffr, an extension of the testthat package that relies on testthat snapshot tests.
If your package interacts with web resources (web APIs and other sources of data on the web) you might find the HTTP testing in R book by Scott Chamberlain and Maëlle Salmon relevant. Packages helping with HTTP testing (corresponding HTTP clients):
+ +testthat has a function skip_on_cran() that you can use to not run tests on CRAN. We recommend using this on all functions that are API calls since they are quite likely to fail on CRAN. These tests should still run on continuous integration. Note that from testthat 3.1.2 skip_if_offline() automatically calls skip_on_cran(). More info on CRAN preparedness for API wrappers.
If your package interacts with a database you might find dittodb useful.
Once you’ve set up continuous integration (CI), use your package’s code coverage report (cf this section of our book) to identify untested lines, and to add further tests.
Even if you use continuous integration, we recommend that you run tests locally prior to submitting your package (you might need to set Sys.setenv(NOT_CRAN="true")).
Include extensive examples in the documentation. In addition to demonstrating how to use the package, these can act as an easy way to test package functionality before there are proper tests. However, keep in mind we require tests in contributed packages.
You can run examples with devtools::run_examples(). Note that when you run R CMD CHECK or equivalent (e.g., devtools::check()) your examples that are not wrapped in \dontrun{} or \donttest{} are run. Refer to the summary table in roxygen2 docs.
To safe-guard examples (e.g. requiring authentication) to be run on CRAN you need to use \dontrun{}. However, for a first submission CRAN won’t let you have all examples escaped so. In this case you might add some small toy examples, or wrap example code in try(). Also refer to the @exampleIf tag present, at the time of writing, in roxygen2 development version.
In addition to running examples locally on your own computer, we strongly advise that you run examples on one of the continuous integration systems. Again, examples that are not wrapped in \dontrun{} or \donttest{} will be run, but for those that are you can configure your continuous integration builds to run them via R CMD check arguments --run-dontrun and/or --run-donttest.
Consider the trade-offs involved in relying on a package as a dependency. On one hand, using dependencies reduces coding effort, and can build on useful functionality developed by others, especially if the dependency performs complex tasks, is high-performance, and/or is well vetted and tested. On the other hand, having many dependencies places a burden on the maintainer to keep up with changes in those packages, at risk to your package’s long-term sustainability. It also increases installation time and size, primarily a consideration on your and others’ development cycle, and in automated build systems. “Heavy” packages - those with many dependencies themselves, and those with large amounts of compiled code - increase this cost. Here are some approaches to reducing dependencies:
+Small, simple functions from a dependency package may be better copied into your own package if the dependency if you are using only a few functions in an otherwise large or heavy dependency. (See Authorship section above for how to acknowledge original authors of copied code.) On the other hand, complex functions with many edge cases (e.g. parsers) require considerable testing and vetting.
+An common example of this is in returning tidyverse-style “tibbles” from package functions that provide data. One can avoid the modestly heavy tibble package dependency by returning a tibble created by modifying a data frame like so:
+class(df) <- c("tbl_df", "tbl", "data.frame") (Note that this approach is not universally endorsed.)
+Ensure that you are using the package where the function is defined, rather than one where it is re-exported. For instance many functions in devtools can be found in smaller specialty packages such as sessioninfo. The %>% function should be imported from magrittr, where it is defined, rather than the heavier dplyr, which re-exports it.
Some dependencies are preferred because they provide easier to interpret function names and syntax than base R solutions. If this is the primary reason for using a function in a heavy dependency, consider wrapping the base R approach in a nicely-named internal function in your package. See e.g. the rlang R script providing functions with a syntax similar to purrr functions.
If dependencies have overlapping functionality, see if you can rely on only one.
More dependency-management tips can be found in the chapter “Dependencies: Mindset and Background” of the R packages book and in a post by Scott Chamberlain.
Use Imports instead of Depends for packages providing functions from other packages. Make sure to list packages used for testing (testthat), and documentation (knitr, roxygen2) in your Suggests section of package dependencies (if you use usethis for adding testing infrastructure via usethis::use_testthat() or a vignette via usethis::use_vignette(), the necessary packages will be added to DESCRIPTION). If you use any package in the examples or tests of your package, make sure to list it in Suggests, if not already listed in Imports.
If your (not Bioconductor) package depends on Bioconductor packages, make sure the installation instructions in the README and vignette are clear enough even for an user who is not familiar with the Bioconductor release cycle.
+Should the user use BiocManager (recommended)? Document this.
Is the automatic installation of Bioconductor packages by install.packages() enough? In that case, mention that the user needs to run setRepositories() if they haven’t set the necessary Bioconductor repositories yet.
If your package depends on Bioconductor after a certain version, mention it in DESCRIPTION and in the installation instructions.
Specifying minimum dependencies (e.g. glue (>= 1.3.0) instead of just glue) should be a conscious choice. If you know for a fact that your package will break below a certain dependency version, specify it explicitly. But if you don’t, then no need to specify a minimum dependency. In that case when a user reports a bug which is explicitly related to an older version of a dependency then address it then. An example of bad practice would be for a developer to consider the versions of their current state of dependencies to be the minimal version. That would needlessly force everyone to upgrade (causing issues with other packages) when there is no good reason behind that version choice.
For most cases where you must expose functions from dependencies to the user, you should import and re-export those individual functions rather than listing them in the Depends fields. For instance, if functions in your package produce raster objects, you might re-export only printing and plotting functions from the raster package.
If your package uses a system dependency, you should
+Indicate it in DESCRIPTION;
Check that it is listed by sysreqsdb to allow automatic tools to install it, and submit a contribution if not;
Check for it in a configure script (example) and give a helpful error message if it cannot be found (example). configure scripts can be challenging as they often require hacky solutions to make diverse system dependencies work across systems. Use examples (more here) as a starting point but note that it is common to encounter bugs and edge cases and often violate CRAN policies. Do not hesitate to ask for help on our forum.
For HTTP requests we recommend using httr2, httr, curl, or crul over RCurl. If you like low level clients for HTTP, curl is best, whereas httr2, httr and crul are better for higher level access.
For parsing, creating, and manipulating XML, we strongly recommend xml2 for most cases. You can refer to Daniel Nüst’s notes about migration from XML to xml2.
For spatial data, the sp package should be considered deprecated in favor of sf, and the packages rgdal, rgdal, and rgdal will be retired by the end of 2023. We recommend use of the spatial suites developed by the r-spatial and rspatial communities. See this GitHub issue for relevant discussions.
Your package source files have to be under version control, more specifically tracked with Git. You might find the gert package relevant, as well as some of usethis Git/GitHub related functionality; you can however use git as you want.
Make sure to list “scrap” such as .DS_Store files in .gitignore. You might find the usethis::git_vaccinate() function, and the gitignore package relevant.
A later section of this book contains some git workflow tips.
This is a collection of CRAN gotchas that are worth avoiding at the outset.
+pkgdown documentation to learn how to override this.Description field of your DESCRIPTION file. URLs should be enclosed in angle brackets, e.g. <https://www.r-project.org>.Title and Description fields, the names of packages or other external software must be quoted using single quotes (e.g., ‘Rcpp’ Integration for the ‘Armadillo’ Templated Linear Algebra Library).testthat::skip_on_cran in tests to skip things that take a long time but still test them locally and on continuous integration.paper.md, continuous integration configuration files, in your .Rbuildignore file.For further gotchas, refer to the collaborative list maintained by ThinkR, “Prepare for CRAN”.
+Once your package is on CRAN, it will be regularly checked on different platforms. Failures of such checks, when not false positives, can lead to the CRAN team’s reaching out. You can monitor the state of the CRAN checks via
+the foghorn package.
the CRAN checks badges.
If you intend your package to be submitted to, or if your package is on, Bioconductor, refer to Bioconductor packaging guidelines and the updated developer book.
+If you are submitting a package to rOpenSci via the software-review repo, you can direct further questions to the rOpenSci team in the issue tracker, or in our discussion forum.
Read the authors guide.
Read, incorporate, and act on advice from the Collaboration Guide chapter.
Hadley Wickham and Jenny Bryan’s R packages book is an excellent, readable resource on package development which is available for free online (and can be bought in print).
Writing R Extensions is the canonical, usually most up-to-date, reference for creating R packages.
Mastering Software Development in R by Roger D. Peng, Sean Kross, and Brooke Anderson.
Tidyverse design guide (WIP) and the accompanying newsletter.
Your first R package in 1 hour by Shannon Pileggi.
Some posts of the rOpenSci blog e.g. “How to precompute package vignettes or pkgdown articles”.
Package Development Corner section of rOpenSci newsletter.
Some posts of the tidyverse blog e.g. “Upgrading to testthat edition 3”.
There is a Coursera specialization corresponding to the book by Roger Peng, Sean Kross and Brooke Anderson, with a course specifically about R packages.
+ + ++This chapter summarizes our guidelines about continuous integration after explaining what continuous integration is. +
++Along with the previous chapter, it forms our guidelines for Software Peer Review. +
+Continuous integration automatically runs tests on software. In the case of rOpenSci, CI practically means that a set of tests will be automatically run via GitHub, every time that you make a commit or pull request to GitHub.
+CI automates the running of general package checks such as R CMD check, see testing. It is possible to set up CI before your tests are written, then CI will run the tests as you commit them to the repository.
All rOpenSci packages must use one form of continuous integration. This ensures that all commits, pull requests and new branches are run through R CMD check. The results of all tests are displayed on the pull request page on GitHub, providing another layer of information about problems and protection against breaking your package before merging changes. rOpenSci packages’ continuous integration must also be linked to a code coverage service, indicating how many lines are covered by unit tests.
Both test status and code coverage should be reported via badges in your package README.
+R packages should have CI for all operating systems (Linux, Mac OSX, Windows) when they contain:
+Compiled code
Java dependencies
Dependencies on other languages
Packages with system calls
Text munging such as getting people’s names (in order to find encoding issues).
Anything with file system / path calls
In case of any doubt regarding the applicability of these criteria to your package, it’s better to add CI for all operating systems. Most CI services standards setups for R packages allow this with not much hassle.
+There are a number of continuous integration services, including standalone services (CircleCI, AppVeyor), and others integrated into code hosting or related services (GitHub Actions, GitLab, AWS Code Pipeline). Different services support different operating system configurations.
+GitHub Actions is a convenient option for many R developers who already use GitHub as it is integrated into the platform and supports all needed operating Systems. There are actions supported for the R ecosystem, as well and first-class support in the {usethis} package. All packages submitted to rOpenSci for peer review are checked by our own pkgcheck system, described further in the Guide for Authors. These checks are also provided as a GitHub Action in the ropensci-review-tools/pkgcheck-action repository. Packages authors are encouraged to use that action to confirm prior to submission that a package passes all of our checks. See our blog post for more information.
usethis supports CI setup for other systems, though these functions are soft-deprecated. rOpenSci also supports the circle package, which aids in setting up CircleCI pipelines, and the tic package for building more complicated CI pipelines.
+We require that rOpenSci packages are tested against the latest, previous and development versions of R to ensure both backwards and forwards compatibility with base R.
+Details of how to run tests/checks using different versions of R locally can be found in the R-hub vignette on running Local Linux checks with Docker.
+You can fine tune the deployment of tests with each versions by using a testing matrix.
+If you develop a package depending on or intended for Bioconductor, you might find biocthis relevant.
+You can use these tips to minimize build time on CI:
+You might find Hugo Gruson’s post System Dependencies in R Packages & Automatic Testing useful.
+We recommend moving away from Travis.
+For continuous integration on Windows, see R + AppVeyor. Set it up using usethis::use_appveyor().
Here are tips to minimize AppVeyor build time:
+Cache installation of packages. Example in a config file. It’ll already be in the config file if you set AppVeyor CI up using usethis::use_appveyor().
Enable rolling builds.
We no longer transfer AppVeyor projects to ropensci AppVeyor account so after transfer of your repo to rOpenSci’s “ropensci” GitHub organization the badge will be [](https://ci.appveyor.com/project/individualaccount/pkgname).
Circle CI is used, for example, by rOpenSci package bomrang as continuous integration service.
Continuous integration should also include reporting of test coverage via a testing service such as Codecov or Coveralls.
+We recommend using Codecov. To activate Codecov for your repo, run usethis::use_github_action("test-coverage") to create a file .github/workflows/test-coverage.yaml. You also need to give Codecov access to your github repository, see Codecov quick start guide for how to set up access. Then add a Codecov status badge to the top of your README.md, see Codecov status badges.
Currently, Codecov has access to all ropensci github repositories by default. When your repository is accepted and transferred to ropensci, Codecov access should transfer automatically. You will need to update the URL of the badge to point to the rOpenSci-hosted repository.
+For more details, see the README for the covr package for instructions, as well as usethis::use_coverage() and usethis::use_github_action().
If you run coverage on several CI services the results will be merged.
+After transfer to rOpenSci’s “ropensci” GitHub organization, each push to the repo will be built on OpenCPU and the person committing will receive a notification email. This is an additional CI service for package authors that allows for R functions in packages to be called remotely via https://ropensci.ocpu.io/ using the opencpu API. For more details about this service, consult the OpenCPU help page that also indicates where to ask questions.
+After transfer to rOpenSci’s “ropensci” GitHub organization, a pkgdown website will be built for your package after each push to the GitHub repo. You can find the status of these builds at https://ropensci.r-universe.dev/ui#packages and in the commit status. The website build will use your pkgdown config file if you have one, except for the styling that will use the rotemplate package.
Please report bugs, questions and feature requests about the central builds and about the template at https://github.com/ropensci-org/rotemplate/.
+ + ++This work-in-progress chapter includes guidance about managing secrets in packages and links for further reading. +
+We recommend the article Ten quick tips for staying safe online by Danielle Smalls and Greg Wilson.
+We recommend you secure your GitHub account with two-factor (authentication) 2FA. It is compulsory for all ropensci GitHub organization members and outside collaborators so make sure to enable it before your package is approved.
We also recommend you regularly check who has access to your package repository, and that you prune any unused access (such as from former collaborators).
This section contains guidance for when you develop a package interacting with a web resource requiring credentials (API keys, tokens, etc.). Also refer to the httr vignette about sharing secrets.
Say your package needs an API key for making requests on behalf of users of your package.
+In your package documentation, guide the user so the API key doesn’t end up in the .Rhistory/script of users of your package.
+Encourage the use of environment variables to store the API key (or even remove the possibility to pass it as an argument to the functions?). You could link to this intro to startup files and usethis::edit_r_environ().
Or your package could depend on, or encourage the use of, keyring to help user store variables in the specific OS’ credential stores (more secure than .Renviron): i.e. you’d create a function for setting the key, and have another one for retrieving the key; or the user would write Sys.setenv(SUPERSECRETKEY = keyring::key_get("myservice")) at the beginning of their script.
Do not print the API key even in verbose mode in any message, warning, error.
In the GitHub issue template, it should be stated not to share any credentials. If an user of your package accidentally shares credentials in an issue, make sure they’re aware of that so they can revoke the key (i.e. ask them explicitly in an answer whether they realized they shared their key).
You’ll need to protect your secrets as you protect secrets of users, but there’s more to take into account and keep in mind.
+If you use vcr or httptest in tests for caching API responses, you need to make sure the recorded requests / fixtures do not contain secrets. Refer to vcr security guidance and httptest guidance “Redacting and Modifying Recorded Requests”, and inspect your recorded requests / fixtures before committing them the first time to be sure you got the setup right.
vcr being an rOpenSci package, you can post any question you might have to rOpenSci forum.
What about pull requests from external contributors? On GitHub for instance, secrets are only available for GitHub Actions for pull requests started from the repository itself, not from fork. Tests using your secrets will fail unless you use some sort of mocked/cached response, so you might want to skip them depending on the context. For instance, in your CI account you could create an environment variable called THIS_IS_ME and then skip tests based on the presence of this variable. This obviously means the PR checks by the CI are not exhaustive, so you’ll need to check out the PR locally to run all tests.
Document the behavior of your package for external PRs in CONTRIBUTING.md for the sake of people making PRs and of people reviewing them (you in a few weeks, and other authors of the package).
+On CRAN, skip any tests (skip_on_cran()) and examples (dontrun) requiring credentials.
Precompute vignettes requiring credentials.
+Useful security resources:
+rOpenSci community call “Security for R” (recording, slides, etc. see in particular the list of resources);
Welcome! 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. For statistical software review, refer to the project webpage and resources.
+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.
+We hope that you’ll find the guide useful and clear, and welcome your suggestions in the issue tracker of the book. Happy R packaging!
+The rOpenSci editorial team.
+This book is a living document. You can view updates to our best practices and policies via the release notes.
+You can cite this book using its Zenodo metadata and DOI.
Em Markowitz (NOAA) · Sam Albers · Toph Allen · Kaique dos S. Alves · Brooke Anderson · Alison Appling · Denisse Fierro Arcos · Zebulun Arendsee · Taylor Arnold · Al-Ahmadgaid B. Asaad · Dean Attali · Mara Averick · Suzan Baert · James Balamuta · Vikram Baliga · David Bapst · Joëlle Barido-Sottani · Allison Barner · Cale Basaraba · John Baumgartner · Marcus Beck · Gabriel Becker · Jason Becker · Salvador Jesus Fernandez Bejarano · Dom Bennett · Ken Benoit · Aaron Berdanier · Fred Boehm · Carl Boettiger · Will Bolton · Ben Bond-Lamberty · Anne-Sophie Bonnet-Lebrun · Alison Boyer · Abby Bratt · François Briatte · Eric Brown · Julien Brun · Jenny Bryan · Lukas Burk · Lorenzo Busetto · Maria Paula Caldas · Mario Gavidia Calderón · Carlos Cámara-Menoyo · Brad Cannell · Joaquin Cavieres · Kevin Cazelles · Scott Chamberlain · Cathy Chamberlin · Jennifer Chang · Pierre Chausse · Jorge Cimentada · Nicholas Clark · Chase Clark · Jon Clayden · Dena Jane Clink · Will Cornwell · Nic Crane · Enrico Crema · Verónica Cruz-Alonso · Ildiko Czeller · Tad Dallas · Kauê de Sousa · Christophe Dervieux · Amanda Dobbyn · Jasmine Dumas · Dewey Dunnington · Remko Duursma · Mark Edmondson · Paul Egeler · Evan Eskew · Harry Eslick · Alexander Fischer · Kim Fitter · Robert M Flight · Sydney Foks · Stephen Formel · Zachary Stephen Longiaru Foster · Auriel Fournier · Kaija Gahm · Zach Gajewski · Carl Ganz · Duncan Garmonsway · Jan Laurens Geffert · Sharla Gelfand · Monica Gerber · Duncan Gillespie · David Gohel · A. Cagri gokcek · Guadalupe Gonzalez · Rohit Goswami · Laura Graham · Charles Gray · Matthias Grenié · Corinna Gries · Hugo Gruson · Ernest Guevarra · W Kyle Hamilton · Ivan Hanigan · Jeffrey Hanson · Liz Hare · Jon Harmon · Rayna Harris · Ted Hart · Nujcharee Haswell · Verena Haunschmid · Stephanie Hazlitt · Andrew Heiss · Max Held · Anna Hepworth · Bea Hernandez · Jim Hester · Peter Hickey · Roel Hogervorst · Kelly Hondula · Allison Horst · Sean Hughes · James Hunter · Brandon Hurr · Ger Inberg · Christopher Jackson · Najko Jahn · Tamora D James · Veronica Jimenez-Jacinto · Mike Johnson · Will Jones · Max Joseph · Megha Joshi · Krunoslav Juraic · Soumya Kalra · Zhian N. Kamvar · Michael Kane · Andee Kaplan · Tinula Kariyawasam · Hazel Kavılı · Jonathan Keane · Christopher T. Kenny · Os Keyes · Eunseop Kim · Aaron A. King · Michael Koontz · Bianca Kramer · Will Landau · Sam Lapp · Erin LeDell · Thomas Leeper · Sam Levin · Lisa Levinson · Stephanie Locke · Marion Louveaux · Robin Lovelace · Julia Stewart Lowndes · Tim Lucas · Muralidhar, M.A. · Andrew MacDonald · Jesse Maegan · Mike Mahoney · Tristan Mahr · Yohann Mansiaux · Paula Andrea Martinez · Anthony Martinez · Joao Martins · Ben Marwick · Claire Mason · Miles McBain · Lucy D’Agostino McGowan · Amelia McNamara · Elaine McVey · Bryce Mecum · Nolwenn Le Meur · François Michonneau · Mario Miguel · Helen Miller · Beatriz Milz · Jessica Minnier · Priscilla Minotti · Nichole Monhait · Kelsey Montgomery · Ronny A. Hernández Mora · Paula Moraga · Natalia Morandeira · George Moroz · Ross Mounce · Athanasia Monika Mowinckel · Lincoln Mullen · Matt Mulvahill · Maria Victoria Munafó · David Neuzerling · Dillon Niederhut · Joel Nitta · Rory Nolan · Kari Norman · Jakub Nowosad · Matt Nunes · Daniel Nüst · Lauren O’Brien · Joseph O’Brien · Paul Oldham · Samantha Oliver · Dan Olner · Jeroen Ooms · Victor Ordu · Luis Osorio · Philipp Ottolinger · Mark Padgham · Marina Papadopoulou · Edzer Pebesma · Thomas Lin Pedersen · Antonio J. Pérez-Luque · Marcelo S. Perlin · Rafael Pilliard-Hellwig · Rodrigo Neto Pires · Lindsay Platt · Nicholas Potter · Joanne Potts · Josep Pueyo-Ros · Etienne Racine · Manuel Ramon · Nistara Randhawa · David Ranzolin · Quentin Read · Neal Richardson · tyler rinker · Emily Robinson · David Robinson · Alec Robitaille · Francisco Rodriguez-Sanchez · Sam Rogers · Julia Romanowska · Xavier Rotllan-Puig · Bob Rudis · Edgar Ruiz · Kent Russel · Michael Sachs · Sheila M. Saia · Chitra M Saraswati · Alicia Schep · Klaus Schliep · Clemens Schmid · Patrick Schratz · Collin Schwantes · Marco Sciaini · Eric Scott · Heidi Seibold · Julia Silge · Margaret Siple · Peter Slaughter · Mike Smith · Tuija Sonkkila · Øystein Sørensen · Jemma Stachelek · Christine Stawitz · Irene Steves · Kelly Street · Matt Strimas-Mackey · Alex Stringer · Michael Sumner · Chung-Kai Sun · Sarah Supp · Emi Tanaka · Jason Taylor · Filipe Teixeira · Andy Teucher · Jennifer Thompson · Joe Thorley · Nicholas Tierney · Tiffany Timbers · Tan Tran · Tim Trice · Utku Turk · Zoë Turner · Kyle Ueyama · Ted Underwood · Adithi R. Upadhya · Kevin Ushey · Josef Uyeda · Frans van Dunné · Mauricio Vargas · Remi Vergnon · Jake Wagner · Ben Ward · Elin Waring · Rachel Warnock · Leah Wasser · David Watkins · Lukas Weber · Marc Weber · Karissa Whiting · Stefan Widgren · Anna Willoughby · Saras Windecker · Luke Winslow · David Winter · Sebastian Wójcik · Witold Wolski · Kara Woo · Marvin N. Wright · Jacob Wujciak-Jens · Bruna Wundervald · Lauren Yamane · Emily Zabor · Taras Zakharko · Sherry Zhang · Hao Zhu · Chava Zibman · Naupaka Zimmerman · Jake Zwart · Felipe · santikka · kasselhingee · Bri · Flury · Vincent · eholmes · Pachá · Rich · Claudia · Jasmine · Zack · Lluís · becarioprecario · gaurav
+If you want to contribute to this book (suggestions, corrections) please refer to the GitHub repository in particular the contributing guidelines. 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, John Baumgartner, François Michonneau, Christophe Dervieux, Lorenzo Busetto, Ben Marwick, Nicholas Horton, Chris Kennedy, Mark Padgham, Jeroen Ooms, Sean Hughes, Jan Gorecki, Joseph Stachelek, Dean Attali, Julia Gustavsen, Nicholas Tierney, Rich FitzJohn, Tiffany Timbers, Hilmar Lapp, Miles McBain, Bryce Mecum, Jonathan Carroll, Carl Boettiger, Florian Privé, Stefanie Butland, Daniel Possenriede, Hadley Wickham, Mauro Lepore, Matthew Fidler, Luke McGuinness, Aaron Wolen, Indrajeet Patil, Kevin Wright, Will Landau, Hugo Gruson,, Hao Ye,, Sébastien Rochette,, Edward Wallace,, Alexander Fischer,, Maxime Jaunatre,, Thomas Zwagerman. Please tell us if we forgot to acknowledge your contribution!
+ + + +Replace the content of the current website with a index.html and 404.html files both containing:
<html>
+<head>
+<meta http-equiv="refresh" content="0;URL=https://docs.ropensci.org/<pkgname>/">
+</head>
+</html>You can setup the redirect from your main user gh-pages repository:
+https://github.com/<username>/<username>.github.io.<pkgname> containing 2 files: a index.html and 404.html file, which both redirect to the new location (see previous subsection).https://<username>.github.io/<pkgname>/index.html now redirects.Editors may make use of the e-mail template below in recruiting reviewers.
+
+Dear [REVIEWER]
+
+Hi, this is [EDITOR]. [FRIENDLY BANTER]. I'm writing to ask if you would be willing to review a package for rOpenSci. As you probably know, rOpenSci conducts peer review of R packages contributed to our collection in a manner similar to journals.
+
+The package, [PACKAGE] by [AUTHOR(S)], does [FUNCTION]. You can find it on GitHub here: [REPO LINK]. We conduct our open review process via GitHub as well, here: [ONBOARDING ISSUE]
+
+If you accept, note that we ask reviewers to complete reviews in three weeks. (We’ve found it takes a similar amount of time to review a package as an academic paper.)
+
+Our [reviewers guide] details what we look for in a package review, and includes links to example reviews. Our standards are detailed in our [packaging guide], and we provide a reviewer [template] for you to use. Please make sure you do not have a [conflict of interest](https://devguide.ropensci.org/policies.html#coi) preventing you from reviewing this package. If you have questions or feedback, feel free to ask me or post to the [rOpenSci forum].
+
+rOpenSci’s community is our best asset.
+We aim for reviews to be open, non-adversarial, and focused on improving software quality.
+Be respectful and kind!
+See our reviewers guide and [code of conduct](https://ropensci.org/code-of-conduct/) for more.
+
+[IF MENTORSHIP REQUESTED: You indicated in your form that you'd prefer mentorship for your first review.
+You are free to use me as a resource during this process, including asking questions by email and Slack (you will receive an invite to the rOpenSci Slack), and sharing draft reviews for feedback before posting.
+I'm also happy to have a brief videocall to walk through the process.
+Please let me know in your reply if you would like to schedule one.]
+
+Are you able to review? If you can not, suggestions for alternate reviewers are always helpful. If I don't hear from you within a week, I will assume you are unable to
+review at this time.
+
+Thank you for your time.
+
+Sincerely,
+
+[EDITOR]
+
+[reviewers guide]: https://devguide.ropensci.org/reviewerguide.html
+[packaging guide]: https://devguide.ropensci.org/building.html
+[template]: https://devguide.ropensci.org/reviewtemplate.html
+[rOpenSci forum]: https://discuss.ropensci.org/You can save this as an R Markdown file, or delete the YAML and save it as a Markdown file.
+---
+title: "review"
+output:
+ rmarkdown::md_document:
+ pandoc_args: [
+ "--wrap=none"
+ ]
+---
+
+## Package Review
+
+*Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide*
+
+- **Briefly describe any working relationship you have (had) with the package authors.**
+- [ ] As the reviewer I confirm that there are no [conflicts of interest](https://devguide.ropensci.org/policies.html#coi) for me to review this work (if you are unsure whether you are in conflict, please speak to your editor _before_ starting your review).
+
+#### Documentation
+
+The package includes all the following forms of documentation:
+
+- [ ] **A statement of need:** clearly stating problems the software is designed to solve and its target audience in README
+- [ ] **Installation instructions:** for the development version of package and any non-standard dependencies in README
+- [ ] **Vignette(s):** demonstrating major functionality that runs successfully locally
+- [ ] **Function Documentation:** for all exported functions
+- [ ] **Examples:** (that run successfully locally) for all exported functions
+- [ ] **Community guidelines:** including contribution guidelines in the README or CONTRIBUTING, and DESCRIPTION with `URL`, `BugReports` and `Maintainer` (which may be autogenerated via `Authors@R`).
+
+#### Functionality
+
+- [ ] **Installation:** Installation succeeds as documented.
+- [ ] **Functionality:** Any functional claims of the software have been confirmed.
+- [ ] **Performance:** Any performance claims of the software have been confirmed.
+- [ ] **Automated tests:** Unit tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.
+- [ ] **Packaging guidelines**: The package conforms to the rOpenSci packaging guidelines.
+
+Estimated hours spent reviewing:
+
+- [ ] Should the author(s) deem it appropriate, I agree to be acknowledged as a package reviewer ("rev" role) in the package DESCRIPTION file.
+
+---
+
+### Review Comments${missingFields[0]} field.`,
+ message: `The items being returned for this search do not include all the required fields. Please ensure that your index items include the ${missingFields[0]} field or use index-fields in your _quarto.yml file to specify the field names.`,
+ };
+ } else if (missingFields.length > 1) {
+ const missingFieldList = missingFields
+ .map((field) => {
+ return `${field}`;
+ })
+ .join(", ");
+
+ throw {
+ name: `Error: Search index is missing the following fields: ${missingFieldList}.`,
+ message: `The items being returned for this search do not include all the required fields. Please ensure that your index items includes the following fields: ${missingFieldList}, or use index-fields in your _quarto.yml file to specify the field names.`,
+ };
+ }
+ }
+}
+
+let lastQuery = null;
+function showCopyLink(query, options) {
+ const language = options.language;
+ lastQuery = query;
+ // Insert share icon
+ const inputSuffixEl = window.document.body.querySelector(
+ ".aa-Form .aa-InputWrapperSuffix"
+ );
+
+ if (inputSuffixEl) {
+ let copyButtonEl = window.document.body.querySelector(
+ ".aa-Form .aa-InputWrapperSuffix .aa-CopyButton"
+ );
+
+ if (copyButtonEl === null) {
+ copyButtonEl = window.document.createElement("button");
+ copyButtonEl.setAttribute("class", "aa-CopyButton");
+ copyButtonEl.setAttribute("type", "button");
+ copyButtonEl.setAttribute("title", language["search-copy-link-title"]);
+ copyButtonEl.onmousedown = (e) => {
+ e.preventDefault();
+ e.stopPropagation();
+ };
+
+ const linkIcon = "bi-clipboard";
+ const checkIcon = "bi-check2";
+
+ const shareIconEl = window.document.createElement("i");
+ shareIconEl.setAttribute("class", `bi ${linkIcon}`);
+ copyButtonEl.appendChild(shareIconEl);
+ inputSuffixEl.prepend(copyButtonEl);
+
+ const clipboard = new window.ClipboardJS(".aa-CopyButton", {
+ text: function (_trigger) {
+ const copyUrl = new URL(window.location);
+ copyUrl.searchParams.set(kQueryArg, lastQuery);
+ copyUrl.searchParams.set(kResultsArg, "1");
+ return copyUrl.toString();
+ },
+ });
+ clipboard.on("success", function (e) {
+ // Focus the input
+
+ // button target
+ const button = e.trigger;
+ const icon = button.querySelector("i.bi");
+
+ // flash "checked"
+ icon.classList.add(checkIcon);
+ icon.classList.remove(linkIcon);
+ setTimeout(function () {
+ icon.classList.remove(checkIcon);
+ icon.classList.add(linkIcon);
+ }, 1000);
+ });
+ }
+
+ // If there is a query, show the link icon
+ if (copyButtonEl) {
+ if (lastQuery && options["copy-button"]) {
+ copyButtonEl.style.display = "flex";
+ } else {
+ copyButtonEl.style.display = "none";
+ }
+ }
+ }
+}
+
+/* Search Index Handling */
+// create the index
+var fuseIndex = undefined;
+var shownWarning = false;
+
+// fuse index options
+const kFuseIndexOptions = {
+ keys: [
+ { name: "title", weight: 20 },
+ { name: "section", weight: 20 },
+ { name: "text", weight: 10 },
+ ],
+ ignoreLocation: true,
+ threshold: 0.1,
+};
+
+async function readSearchData() {
+ // Initialize the search index on demand
+ if (fuseIndex === undefined) {
+ if (window.location.protocol === "file:" && !shownWarning) {
+ window.alert(
+ "Search requires JavaScript features disabled when running in file://... URLs. In order to use search, please run this document in a web server."
+ );
+ shownWarning = true;
+ return;
+ }
+ const fuse = new window.Fuse([], kFuseIndexOptions);
+
+ // fetch the main search.json
+ const response = await fetch(offsetURL("search.json"));
+ if (response.status == 200) {
+ return response.json().then(function (searchDocs) {
+ searchDocs.forEach(function (searchDoc) {
+ fuse.add(searchDoc);
+ });
+ fuseIndex = fuse;
+ return fuseIndex;
+ });
+ } else {
+ return Promise.reject(
+ new Error(
+ "Unexpected status from search index request: " + response.status
+ )
+ );
+ }
+ }
+
+ return fuseIndex;
+}
+
+function inputElement() {
+ return window.document.body.querySelector(".aa-Form .aa-Input");
+}
+
+function focusSearchInput() {
+ setTimeout(() => {
+ const inputEl = inputElement();
+ if (inputEl) {
+ inputEl.focus();
+ }
+ }, 50);
+}
+
+/* Panels */
+const kItemTypeDoc = "document";
+const kItemTypeMore = "document-more";
+const kItemTypeItem = "document-item";
+const kItemTypeError = "error";
+
+function renderItem(
+ item,
+ createElement,
+ state,
+ setActiveItemId,
+ setContext,
+ refresh,
+ quartoSearchOptions
+) {
+ switch (item.type) {
+ case kItemTypeDoc:
+ return createDocumentCard(
+ createElement,
+ "file-richtext",
+ item.title,
+ item.section,
+ item.text,
+ item.href,
+ item.crumbs,
+ quartoSearchOptions
+ );
+ case kItemTypeMore:
+ return createMoreCard(
+ createElement,
+ item,
+ state,
+ setActiveItemId,
+ setContext,
+ refresh
+ );
+ case kItemTypeItem:
+ return createSectionCard(
+ createElement,
+ item.section,
+ item.text,
+ item.href
+ );
+ case kItemTypeError:
+ return createErrorCard(createElement, item.title, item.text);
+ default:
+ return undefined;
+ }
+}
+
+function createDocumentCard(
+ createElement,
+ icon,
+ title,
+ section,
+ text,
+ href,
+ crumbs,
+ quartoSearchOptions
+) {
+ const iconEl = createElement("i", {
+ class: `bi bi-${icon} search-result-icon`,
+ });
+ const titleEl = createElement("p", { class: "search-result-title" }, title);
+ const titleContents = [iconEl, titleEl];
+ const showParent = quartoSearchOptions["show-item-context"];
+ if (crumbs && showParent) {
+ let crumbsOut = undefined;
+ const crumbClz = ["search-result-crumbs"];
+ if (showParent === "root") {
+ crumbsOut = crumbs.length > 1 ? crumbs[0] : undefined;
+ } else if (showParent === "parent") {
+ crumbsOut = crumbs.length > 1 ? crumbs[crumbs.length - 2] : undefined;
+ } else {
+ crumbsOut = crumbs.length > 1 ? crumbs.join(" > ") : undefined;
+ crumbClz.push("search-result-crumbs-wrap");
+ }
+
+ const crumbEl = createElement(
+ "p",
+ { class: crumbClz.join(" ") },
+ crumbsOut
+ );
+ titleContents.push(crumbEl);
+ }
+
+ const titleContainerEl = createElement(
+ "div",
+ { class: "search-result-title-container" },
+ titleContents
+ );
+
+ const textEls = [];
+ if (section) {
+ const sectionEl = createElement(
+ "p",
+ { class: "search-result-section" },
+ section
+ );
+ textEls.push(sectionEl);
+ }
+ const descEl = createElement("p", {
+ class: "search-result-text",
+ dangerouslySetInnerHTML: {
+ __html: text,
+ },
+ });
+ textEls.push(descEl);
+
+ const textContainerEl = createElement(
+ "div",
+ { class: "search-result-text-container" },
+ textEls
+ );
+
+ const containerEl = createElement(
+ "div",
+ {
+ class: "search-result-container",
+ },
+ [titleContainerEl, textContainerEl]
+ );
+
+ const linkEl = createElement(
+ "a",
+ {
+ href: offsetURL(href),
+ class: "search-result-link",
+ },
+ containerEl
+ );
+
+ const classes = ["search-result-doc", "search-item"];
+ if (!section) {
+ classes.push("document-selectable");
+ }
+
+ return createElement(
+ "div",
+ {
+ class: classes.join(" "),
+ },
+ linkEl
+ );
+}
+
+function createMoreCard(
+ createElement,
+ item,
+ state,
+ setActiveItemId,
+ setContext,
+ refresh
+) {
+ const moreCardEl = createElement(
+ "div",
+ {
+ class: "search-result-more search-item",
+ onClick: (e) => {
+ // Handle expanding the sections by adding the expanded
+ // section to the list of expanded sections
+ toggleExpanded(item, state, setContext, setActiveItemId, refresh);
+ e.stopPropagation();
+ },
+ },
+ item.title
+ );
+
+ return moreCardEl;
+}
+
+function toggleExpanded(item, state, setContext, setActiveItemId, refresh) {
+ const expanded = state.context.expanded || [];
+ if (expanded.includes(item.target)) {
+ setContext({
+ expanded: expanded.filter((target) => target !== item.target),
+ });
+ } else {
+ setContext({ expanded: [...expanded, item.target] });
+ }
+
+ refresh();
+ setActiveItemId(item.__autocomplete_id);
+}
+
+function createSectionCard(createElement, section, text, href) {
+ const sectionEl = createSection(createElement, section, text, href);
+ return createElement(
+ "div",
+ {
+ class: "search-result-doc-section search-item",
+ },
+ sectionEl
+ );
+}
+
+function createSection(createElement, title, text, href) {
+ const descEl = createElement("p", {
+ class: "search-result-text",
+ dangerouslySetInnerHTML: {
+ __html: text,
+ },
+ });
+
+ const titleEl = createElement("p", { class: "search-result-section" }, title);
+ const linkEl = createElement(
+ "a",
+ {
+ href: offsetURL(href),
+ class: "search-result-link",
+ },
+ [titleEl, descEl]
+ );
+ return linkEl;
+}
+
+function createErrorCard(createElement, title, text) {
+ const descEl = createElement("p", {
+ class: "search-error-text",
+ dangerouslySetInnerHTML: {
+ __html: text,
+ },
+ });
+
+ const titleEl = createElement("p", {
+ class: "search-error-title",
+ dangerouslySetInnerHTML: {
+ __html: ` ${title}`,
+ },
+ });
+ const errorEl = createElement("div", { class: "search-error" }, [
+ titleEl,
+ descEl,
+ ]);
+ return errorEl;
+}
+
+function positionPanel(pos) {
+ const panelEl = window.document.querySelector(
+ "#quarto-search-results .aa-Panel"
+ );
+ const inputEl = window.document.querySelector(
+ "#quarto-search .aa-Autocomplete"
+ );
+
+ if (panelEl && inputEl) {
+ panelEl.style.top = `${Math.round(panelEl.offsetTop)}px`;
+ if (pos === "start") {
+ panelEl.style.left = `${Math.round(inputEl.left)}px`;
+ } else {
+ panelEl.style.right = `${Math.round(inputEl.offsetRight)}px`;
+ }
+ }
+}
+
+/* Highlighting */
+// highlighting functions
+function highlightMatch(query, text) {
+ if (text) {
+ const start = text.toLowerCase().indexOf(query.toLowerCase());
+ if (start !== -1) {
+ const startMark = "";
+ const endMark = "";
+
+ const end = start + query.length;
+ text =
+ text.slice(0, start) +
+ startMark +
+ text.slice(start, end) +
+ endMark +
+ text.slice(end);
+ const startInfo = clipStart(text, start);
+ const endInfo = clipEnd(
+ text,
+ startInfo.position + startMark.length + endMark.length
+ );
+ text =
+ startInfo.prefix +
+ text.slice(startInfo.position, endInfo.position) +
+ endInfo.suffix;
+
+ return text;
+ } else {
+ return text;
+ }
+ } else {
+ return text;
+ }
+}
+
+function clipStart(text, pos) {
+ const clipStart = pos - 50;
+ if (clipStart < 0) {
+ // This will just return the start of the string
+ return {
+ position: 0,
+ prefix: "",
+ };
+ } else {
+ // We're clipping before the start of the string, walk backwards to the first space.
+ const spacePos = findSpace(text, pos, -1);
+ return {
+ position: spacePos.position,
+ prefix: "",
+ };
+ }
+}
+
+function clipEnd(text, pos) {
+ const clipEnd = pos + 200;
+ if (clipEnd > text.length) {
+ return {
+ position: text.length,
+ suffix: "",
+ };
+ } else {
+ const spacePos = findSpace(text, clipEnd, 1);
+ return {
+ position: spacePos.position,
+ suffix: spacePos.clipped ? "…" : "",
+ };
+ }
+}
+
+function findSpace(text, start, step) {
+ let stepPos = start;
+ while (stepPos > -1 && stepPos < text.length) {
+ const char = text[stepPos];
+ if (char === " " || char === "," || char === ":") {
+ return {
+ position: step === 1 ? stepPos : stepPos - step,
+ clipped: stepPos > 1 && stepPos < text.length,
+ };
+ }
+ stepPos = stepPos + step;
+ }
+
+ return {
+ position: stepPos - step,
+ clipped: false,
+ };
+}
+
+// removes highlighting as implemented by the mark tag
+function clearHighlight(searchterm, el) {
+ const childNodes = el.childNodes;
+ for (let i = childNodes.length - 1; i >= 0; i--) {
+ const node = childNodes[i];
+ if (node.nodeType === Node.ELEMENT_NODE) {
+ if (
+ node.tagName === "MARK" &&
+ node.innerText.toLowerCase() === searchterm.toLowerCase()
+ ) {
+ el.replaceChild(document.createTextNode(node.innerText), node);
+ } else {
+ clearHighlight(searchterm, node);
+ }
+ }
+ }
+}
+
+function escapeRegExp(string) {
+ return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
+}
+
+// highlight matches
+function highlight(term, el) {
+ const termRegex = new RegExp(term, "ig");
+ const childNodes = el.childNodes;
+
+ // walk back to front avoid mutating elements in front of us
+ for (let i = childNodes.length - 1; i >= 0; i--) {
+ const node = childNodes[i];
+
+ if (node.nodeType === Node.TEXT_NODE) {
+ // Search text nodes for text to highlight
+ const text = node.nodeValue;
+
+ let startIndex = 0;
+ let matchIndex = text.search(termRegex);
+ if (matchIndex > -1) {
+ const markFragment = document.createDocumentFragment();
+ while (matchIndex > -1) {
+ const prefix = text.slice(startIndex, matchIndex);
+ markFragment.appendChild(document.createTextNode(prefix));
+
+ const mark = document.createElement("mark");
+ mark.appendChild(
+ document.createTextNode(
+ text.slice(matchIndex, matchIndex + term.length)
+ )
+ );
+ markFragment.appendChild(mark);
+
+ startIndex = matchIndex + term.length;
+ matchIndex = text.slice(startIndex).search(new RegExp(term, "ig"));
+ if (matchIndex > -1) {
+ matchIndex = startIndex + matchIndex;
+ }
+ }
+ if (startIndex < text.length) {
+ markFragment.appendChild(
+ document.createTextNode(text.slice(startIndex, text.length))
+ );
+ }
+
+ el.replaceChild(markFragment, node);
+ }
+ } else if (node.nodeType === Node.ELEMENT_NODE) {
+ // recurse through elements
+ highlight(term, node);
+ }
+ }
+}
+
+/* Link Handling */
+// get the offset from this page for a given site root relative url
+function offsetURL(url) {
+ var offset = getMeta("quarto:offset");
+ return offset ? offset + url : url;
+}
+
+// read a meta tag value
+function getMeta(metaName) {
+ var metas = window.document.getElementsByTagName("meta");
+ for (let i = 0; i < metas.length; i++) {
+ if (metas[i].getAttribute("name") === metaName) {
+ return metas[i].getAttribute("content");
+ }
+ }
+ return "";
+}
+
+function algoliaSearch(query, limit, algoliaOptions) {
+ const { getAlgoliaResults } = window["@algolia/autocomplete-preset-algolia"];
+
+ const applicationId = algoliaOptions["application-id"];
+ const searchOnlyApiKey = algoliaOptions["search-only-api-key"];
+ const indexName = algoliaOptions["index-name"];
+ const indexFields = algoliaOptions["index-fields"];
+ const searchClient = window.algoliasearch(applicationId, searchOnlyApiKey);
+ const searchParams = algoliaOptions["params"];
+ const searchAnalytics = !!algoliaOptions["analytics-events"];
+
+ return getAlgoliaResults({
+ searchClient,
+ queries: [
+ {
+ indexName: indexName,
+ query,
+ params: {
+ hitsPerPage: limit,
+ clickAnalytics: searchAnalytics,
+ ...searchParams,
+ },
+ },
+ ],
+ transformResponse: (response) => {
+ if (!indexFields) {
+ return response.hits.map((hit) => {
+ return hit.map((item) => {
+ return {
+ ...item,
+ text: highlightMatch(query, item.text),
+ };
+ });
+ });
+ } else {
+ const remappedHits = response.hits.map((hit) => {
+ return hit.map((item) => {
+ const newItem = { ...item };
+ ["href", "section", "title", "text", "crumbs"].forEach(
+ (keyName) => {
+ const mappedName = indexFields[keyName];
+ if (
+ mappedName &&
+ item[mappedName] !== undefined &&
+ mappedName !== keyName
+ ) {
+ newItem[keyName] = item[mappedName];
+ delete newItem[mappedName];
+ }
+ }
+ );
+ newItem.text = highlightMatch(query, newItem.text);
+ return newItem;
+ });
+ });
+ return remappedHits;
+ }
+ },
+ });
+}
+
+let subSearchTerm = undefined;
+let subSearchFuse = undefined;
+const kFuseMaxWait = 125;
+
+async function fuseSearch(query, fuse, fuseOptions) {
+ let index = fuse;
+ // Fuse.js using the Bitap algorithm for text matching which runs in
+ // O(nm) time (no matter the structure of the text). In our case this
+ // means that long search terms mixed with large index gets very slow
+ //
+ // This injects a subIndex that will be used once the terms get long enough
+ // Usually making this subindex is cheap since there will typically be
+ // a subset of results matching the existing query
+ if (subSearchFuse !== undefined && query.startsWith(subSearchTerm)) {
+ // Use the existing subSearchFuse
+ index = subSearchFuse;
+ } else if (subSearchFuse !== undefined) {
+ // The term changed, discard the existing fuse
+ subSearchFuse = undefined;
+ subSearchTerm = undefined;
+ }
+
+ // Search using the active fuse
+ const then = performance.now();
+ const resultsRaw = await index.search(query, fuseOptions);
+ const now = performance.now();
+
+ const results = resultsRaw.map((result) => {
+ const addParam = (url, name, value) => {
+ const anchorParts = url.split("#");
+ const baseUrl = anchorParts[0];
+ const sep = baseUrl.search("\\?") > 0 ? "&" : "?";
+ anchorParts[0] = baseUrl + sep + name + "=" + value;
+ return anchorParts.join("#");
+ };
+
+ return {
+ title: result.item.title,
+ section: result.item.section,
+ href: addParam(result.item.href, kQueryArg, query),
+ text: highlightMatch(query, result.item.text),
+ crumbs: result.item.crumbs,
+ };
+ });
+
+ // If we don't have a subfuse and the query is long enough, go ahead
+ // and create a subfuse to use for subsequent queries
+ if (
+ now - then > kFuseMaxWait &&
+ subSearchFuse === undefined &&
+ resultsRaw.length < fuseOptions.limit
+ ) {
+ subSearchTerm = query;
+ subSearchFuse = new window.Fuse([], kFuseIndexOptions);
+ resultsRaw.forEach((rr) => {
+ subSearchFuse.add(rr.item);
+ });
+ }
+ return results;
+}
diff --git a/sitemap.xml b/sitemap.xml
new file mode 100644
index 000000000..2506a4112
--- /dev/null
+++ b/sitemap.xml
@@ -0,0 +1,123 @@
+
++This concise guide presents the software peer review process for you as a package author. +
+pkgcheck function locally to confirm that the package is ready to be submitted. Alternatively, an even easier way to ensure a package is ready for submission is to use the pkgcheck GitHub Action to run pkgcheck as a GitHub Action, as described in our blog post.pkgcheck which your package is unable to pass, please explain reasons in your submission template.<!---variable--->). These are used by our ropensci-review-bot, and must be left in place, with values filled between the indicated start and end points, like this:<!---variable--->insert value here<!---end-variable>pkgcheck system, which will confirm whether or not a package is ready to be reviewed.ropensci-software-review branch.pkgcheck checks, authors can request a re-check with the command, @ropensci-review-bot check package.Our code of conduct is mandatory for everyone involved in our review process.
+ + ++Software Peer Review at rOpenSci is managed by a team of editors. We are piloting a system of a rotating Editor-in-Chief (EiC). +
++This chapter presents the responsabilities of the Editor-in-Chief, of any editor in charge of a submission, how to respond to an out-of-scope submission and how to manage a dev guide release. +
++If you’re a guest editor, thanks for helping! Please contact the editor who invited you to handle a submission for any question you might have. +
+++Always assume participants in the software review system (fellow editors, submitters, reviewers) are doing their best, and communicate gracefully accordingly, especially when inquiring why a thing is delayed.
+
In addition to handling packages (about 4 a year), editors weigh in on group editorial decisions, such as whether a package is in-scope, and determining updates to our policies. We generally do this through Slack, which we expect editors to be able to check regularly.
We also rotate Editor-in-Chief responsibilities (first-pass scope decisions and assigning editors) amongst the board about quarterly.
You do not have to keep track of other submissions, but if you do notice an issue with a package that is being handled by another editor, feel free to raise that issue directly with the other editor, or post the concern to editors-only channel on slack. Examples:
+@ropensci-review-bot assign @username as editor. This will also add tag 1/editor-checks to the issue.@ropensci-review-bot check package.pkgreviewr package created by associate editor Anna Krystalli. Please strive to finish the checks and start looking for reviewers within 5 working days.usethis and styler, and to online resources (sections of this guide, sections of the R packages book) to make your feedback easier to use. Example of editor’s checks.@ropensci-review-bot put on hold. You’ll get a reminder every 90 days (in the issue) to check in with the package author(s).@ropensci-review-bot seeking reviewers.@ropensci-review-bot assign @username as reviewer. add can also be used instead of assign, and to reviewers (plural) instead of as reviewer (single). The following is thus also valid: @ropensci-review-bot add @username to reviewers. One command should be issued for each reviewer. If needed later, remove reviewers with @ropensci-review-bot remove @username from reviewers.@ropensci-review-bot set due date for @username to YYYY-MM-DD.As a (guest) editor, use
+When these sources of information are not enough,
+You can use filters, sorting, and search to identify reviewers with particular experience:
+
Please check the reviewer’s most recent review and avoid anyone who has reviewed anyone in the past six months. Also, please check if a first-time reviewers have indicated that they require_mentorship. If so, please use the mentorship portion of the email template and be prepared to provide additional guidance.
Here are criteria to keep in mind when choosing a reviewer. You might need to piece this information together by searching CRAN and the potential reviewer’s GitHub page and general online presence (personal website, Twitter).
+Each submission should be reviewed by two package reviewers. Although it is fine for one of them to have less package development experience and more domain knowledge, the review should not be split in two. Both reviewers need to review the package comprehensively, though from their particular perspective. In general, at least one reviewer should have prior reviewing experience, and of course inviting one new reviewer expands our pool of reviewers.
+@ropensci-review-bot submit review <review-url> time <time in hours>. E.g. for the review https://github.com/ropensci/software-review/issues/329#issuecomment-809783937 the comment would be @ropensci-review-bot submit review https://github.com/ropensci/software-review/issues/329#issuecomment-809783937 time 4.5/awaiting-reviewer-response, and request that reviewers indicate approval with the reviewer approval template.@ropensci-review-bot approve <package-name>@ropensci/blog-editors for follow-up.ropensci-books GitHub organisation.The EiC serves for 3 months or a time agreed to by all members of the editorial board. The EiC is entitled to taking scope and overlap decisions as independently as possible (but can still request help/advice). In details, the EiC plays the following roles
+Watches all issues posted to the software-review repo (either subscribe to repo notifications on GitHub, or watch the #software-peer-review-feed channel on Slack).
Tags issue with 0/editorial-team-prep
Calls @ropensci-review-bot check srr on pre-submission enquiries for statistical software. See corresponding Stats Dev Guide chapter for details.
Assigns package submissions to other editors, including self, to handle. Mostly this just rotates among editors, unless the EiC thinks an editor is particularly suited to a package, or an editor declines handling the submission due to being too busy or because of conflicting interests.
+@ropensci-review-bot assign @username as editorRegularly (for instance weekly) monitors pace of review process thanks to devguider and reminds other editors to move packages along as needed.
On assuming EiC rotation, reviews status of current open reviews thanks to devguider and reminds editors to respond or update status as needed.
Responds to issues posted to the software-review-meta repo
Makes decisions on scope/overlap for pre-submission inquiries, referrals from JOSS or other publication partners, and submissions if they see an ambiguous case (This last case may also be done by handling editors (see below)). To initiate discussion, this is posted to the rOpenSci Slack editors-only channel along with a small summary of what the (pre-)submitted/referred submission is about, what doubts the EiC has i.e. digesting information a bit. If after one day or two the EiC feels they haven’t received enough answers, they can ping all editors.
+@ropensci-review-bot out-of-scope.Requests a new EiC when their rotation is up (set a calendar reminder ahead of your expected end date and ask for volunteers in the editors’ Slack channel)
devguider::devguide_eic_report()
+Install devguider and run devguider::devguide_eic_report(), open the HTML report in a browser.
Look over submissions in “presubmission” and “editorial-team-prep”. Check whether any action needs to be taken (polling editors, making a decision, putting the issue on hold, pinging the submitter for an update, finding and assigning an editor).
Rows in each section are colored by “urgency” from white (ignore) to yellow (not urgent) to red (most urgent).
Look over submissions in “seeking-reviewer(s)”. If the reviewer search has been going for unusually long (red color), check whether the submission is on hold, read the thread to gather context, and contact the editor in private to ask for more information / whether the submission fell through the cracks.
Look over submissions in “reviewer(s)-assigned”. If there are still missing reviews after an unusually long time (red color), check whether the submission is on hold, read the thread to gather context, and contact the editor in private to ask for more information / whether the submission fell through the cracks.
Look over submissions in “review(s)-in-awaiting-changes”. If some are still lacking an author response after an unusually long time (red color), check whether the submission is on hold, read the thread, and contact the editor in private to ask for more information / whether the submission fell through the cracks.
In some cases online documentation is sparse. Minimal README, no pkgdown website make assessment harder. In that case please ask for more details: even if the package is deemed out-of-scope, the package docs will have gotten better so we are fine asking for these efforts.
+Example text
+Hello <username> and many thanks for your submission.
+
+We are discussing whether the package is in scope and need a bit more information.
+
+Would you mind adding more details and context to the README?
+After reading it someone with little domain knowledge should have been informed about the aim, goals and functionality of the package.
+
+<optional>
+If a package has overlapping functionality with other packages, we require it to demonstrate in the documentation [how it is best in class](https://devguide.ropensci.org/policies.html#overlap). Could you add a more detailed comparison to the packages you mention in the README so we can evaluate?
+</optional>After discussion with other editors the EiC might invite a guest editor to handle a submission (e.g. if submission volume is large, if all editors have a conflict of interest, if specific expertise is needed, or as a trial prior to inviting a person to join the editorial board).
+When inviting a guest editor,
+If the person said yes (yay!),
+ropensci/editors team and to the ropensci organization,After the review process is finished (package approved, issue closed),
+ropensci/editors team (but not from the ropensci organization).Thank authors for their submission, explain the reasons for the decision, and direct them to other publication venues if relevant, and to the rOpenSci discussion forum. Use wording from Aims and scope in particular regarding the evolution of scope over time, and the overlap and differences between unconf/staff/software-review development.
+ +Reviewers might ask for feedback on e.g. the tone of their review. Beside pointing them at general guidance in this guide, asking editors / opening an issue when such guidance is lacking, here are some review examples that might be useful.
+slopes package, which ended up being fundamentally redesigned in response to the reviews. All reviews/reviewers were at all times entirely constructive, which seems to have played a major role in motivating the authors to embark on such a major overhaul. Comments such as, “this package does not …” or “has not …” were invariably followed by constructive suggestions for what could be done (there are, for example, several in one of the first reviews).If you are in charge of managing a release of the very book you are reading, use the book release guidance as an issue template to be posted in the dev guide issue tracker, and do not hesitate to ask questions to other editors.
+For very small amendments to the dev guide, no PR review is needed. For larger amendments, request review from at least a few editors (if none participated in the discussion related to the amendment, request a review from all of them on GitHub, and in the absence of any reaction merge after a week).
+Two weeks before a dev guide release, once the PR from dev to master and the release blog post are ready for review, all editors should be pinged by GitHub (“review request” on the PR from dev to master) and Slack, but the release doesn’t need all of them to explicitly approve the release.
+The blog post about a release will be reviewed by editors, and one of @ropensci/blog-editors.
Refer to the general rOpenSci blogging guidance, and the more specific guidance below.
+First example of such a post; second example.
+The blog post should mention all important items from the changelog organized in (sub)sections: e.g. a section about big change A, another one about big change B, and one about smaller changes lumped together. Mention the most important changes first.
+For each change made by an external contributor, thank them explicitly using the information from the changelog. E.g. [Matt Fidler](https://github.com/mattfidler/) amended our section on Console messages [ropensci/dev_guide#178](https://github.com/ropensci/dev_guide/pull/178)..
At the end of the post, mention upcoming changes by linking to open issues in the issue tracker, and invite readers to contribute to the dev guide by opening issues and participating in open discussions. Conclusion template:
+In this post we summarized the changes incorporated into our book ["rOpenSci Packages: Development, Maintenance, and Peer Review"](https://devguide.ropensci.org/) over the last X months.
+We are grateful for all contributions that made this release possible.
+We are already working on updates for our next version, such as ISSUE1, ISSUE2.
+Check out the [the issue tracker](https://github.com/ropensci/dev_guide/issues/) if you'd like to contribute.+Guidance for managing the editorial team. +
+Recruiting new editors and maintaining a sufficient and well-balanced editorial board is a responsibility of the Software Review Lead, with support and advice from the editorial board.
+Steps:
+Start a private channel for discussion (so that it does not have a history in the editors channel that future editors will join, which could be awkward).
Ping editors to be sure they get a notification as this is an important topic.
Wait for a majority of editors to chime in before inviting someone. Leave them one week to respond.
Candidates might start by being guest editors. When inviting them as guest editor, invite them as you would invite a guest editor for other reasons.
If a candidate is guest editor first, assess how the process went after the submission is tackled. Asked other editors for their advice again.
Send an email.
We would like to invite you to join the rOpenSci editorial board as a full member. [SPECIFIC REASONS FOR INVITATION (MENTION CONTRIBUTIONS TO ROPENSCI)].
+We think you would make a wonderful addition to the team.
+
+[IF GUEST EDITOR:You are familiar with the editor's role as you've been a guest editor]. We aim for editors to handle four packages per year ([IF GUEST EDITOR including the one one you just finished!]).
+We ask that editors make an informal commitment of serving for two years, and re-evaluate their participation after that.
+On a short-term basis, any editor can decline to handle a package or say, "I'm pretty busy, I can't handle a new package for a few weeks."
+
+In addition to handling packages, editors weigh in on group editorial decisions, such as whether a package is in-scope, and determining updates to our policies.
+We generally do this through Slack, which we expect editors to be able to check regularly.
+We have editorial board calls annually.
+We also rotate Editor-in-Chief responsibilities (first-pass scope decisions and assigning editors) amongst the board about quarterly.
+You'll have the opportunity to enter this rotation once you have been on the board for some time, usually at least six months.
+Some of us also take on bigger projects to improve the peer-review process, though this is entirely optional.
+
+We hope that you'll join the board!
+It's an exciting time for peer-review at rOpenSci.
+
+Please give this some thought, ask us any questions you have, and let us know whether you can join us.
+
+Best,
+[EDITOR], on behalf of the rOpenSci Editorial BoardInform rOpenSci community manager so that
+If they haven’t already done so as guest editors, request that the new editor turn on two-factor authentication (2FA) for GitHub.
Invite editors to the rOpenSci GitHub organization as member, as a member of the editors team and the data-pkg-editors or stats-board sub-team, as appropriate. This will give them appropriate permissions and allow them to get team-specific notifications.
Editors need access to the AirTable database of software review.
Editors need access to the private editors channel in rOpenSci Slack workspace (and to the Slack workspace in general if they didn’t previously, in that case ask rOpenSci community manager).
Post a welcome message in the channel, pinging all editors.
In the Slack workspace they need to be added to the editors team so that @editors will ping them too.
We add editors’ names to
+Add editors to https://github.com/orgs/ropensci/teams/editors/members
Thank them for their work!
Remove them from the editors-only channel and the editors Slack team.
Remove them from https://github.com/orgs/ropensci/teams/editors/members and sub-team.
Inform rOpenSci community manager or some other staff emember so that they might be moved to alumni team members on the website.
Remove their access to the Airtable workspace.
Remove them from
++This chapter contains a general intro to our software peer review system for packages, reasons to submit a package, reasons to volunteer as a reviewer, why our reviews are open, and acknowledgements of actors of the system. +
++Our system has recently been expanded to statistical software peer-review. +
++If you use our standards/checklists etc. when reviewing software elsewhere, do tell the recipients (e.g. journal editors, students, internal code review) that they came from rOpenSci, and tell us in our public forum, or privately by email. +
+rOpenSci’s suite of packages is partly contributed by staff members and partly contributed by community members, which means the suite stems from a great diversity of skills and experience of developers. How to ensure quality for the whole set? That’s where software peer review comes into play: packages contributed by the community undergo a transparent, constructive, non adversarial and open review process. For that process relying mostly on volunteer work, associate editors manage the incoming flow and ensure progress of submissions; authors create, submit and improve their package; reviewers, two per submission, examine the software code and user experience. This blog post written by rOpenSci editors is a good introduction to rOpenSci software peer review Other blog posts about review itself and reviewed packages can be find via the “software-peer-review” tag on rOpenSci blog.
+You can recognize rOpenSci packages that have been peer-reviewed via a green “peer-reviewed” badge in their README, linking to their reviews (cf this example); and via a blue comment icon near their description on rOpenSci packages page, also linking to the reviews.
+Technically, we make the most of GitHub infrastructure: each package review process is an issue in the ropensci/software-review GitHub repository. For instance, click here to read the review thread of the ropenaq package: the process is an ongoing conversation until acceptance of the package, with two external reviews as important milestones. Furthermore, we use GitHub features such as the use of issue templates (as submission templates), and labelling which we use to track progress of submissions (from editor checks to approval).
ropensci-books GitHub organisation for books to be listed at books.ropensci.org.Our reviewing threads are public. Authors, reviewers, and editors all know each other’s identities. The broader community can view or even participate in the conversation as it happens. This provides an incentive to be thorough and provide non-adversarial, constructive reviews. Both authors and reviewers report that they enjoy and learn more from this open and direct exchange. It also has the benefit of building a community. Participants have the opportunity to meaningfully network with new peers, and new collaborations have emerged via ideas spawned during the review process.
+We are aware that open systems can have drawbacks. For instance, in traditional academic review, double-blind peer review can increase representation of female authors, suggesting bias in non-blind reviews. It is also possible reviewers are less critical in open review. However, we posit that the openness of the review conversation provides a check on review quality and bias; it’s harder to inject unsupported or subjective comments in public and without the cover of anonymity. Ultimately, we believe that having direct and public communication between authors and reviewers improves quality and fairness of reviews.
+Furthermore, authors and reviewers have the ability to contact privately the editors if they have any doubt or question.
+docs.ropensci.org docs website that you can link from DESCRIPTION.rOpenSci’s Software Peer Review process is run by:
+We are grateful to the following individuals who have offered up their time and expertise to review packages submitted to rOpenSci.
+Em Markowitz (NOAA) · Sam Albers · Toph Allen · Kaique dos S. Alves · Brooke Anderson · Alison Appling · Denisse Fierro Arcos · Zebulun Arendsee · Taylor Arnold · Al-Ahmadgaid B. Asaad · Dean Attali · Mara Averick · Suzan Baert · James Balamuta · Vikram Baliga · David Bapst · Joëlle Barido-Sottani · Allison Barner · Cale Basaraba · John Baumgartner · Marcus Beck · Gabriel Becker · Jason Becker · Salvador Jesus Fernandez Bejarano · Dom Bennett · Ken Benoit · Aaron Berdanier · Fred Boehm · Carl Boettiger · Will Bolton · Ben Bond-Lamberty · Anne-Sophie Bonnet-Lebrun · Alison Boyer · Abby Bratt · François Briatte · Eric Brown · Julien Brun · Jenny Bryan · Lukas Burk · Lorenzo Busetto · Maria Paula Caldas · Mario Gavidia Calderón · Carlos Cámara-Menoyo · Brad Cannell · Joaquin Cavieres · Kevin Cazelles · Scott Chamberlain · Cathy Chamberlin · Jennifer Chang · Pierre Chausse · Jorge Cimentada · Nicholas Clark · Chase Clark · Jon Clayden · Dena Jane Clink · Will Cornwell · Nic Crane · Enrico Crema · Verónica Cruz-Alonso · Ildiko Czeller · Tad Dallas · Kauê de Sousa · Christophe Dervieux · Amanda Dobbyn · Jasmine Dumas · Dewey Dunnington · Remko Duursma · Mark Edmondson · Paul Egeler · Evan Eskew · Harry Eslick · Alexander Fischer · Kim Fitter · Robert M Flight · Sydney Foks · Stephen Formel · Zachary Stephen Longiaru Foster · Auriel Fournier · Kaija Gahm · Zach Gajewski · Carl Ganz · Duncan Garmonsway · Jan Laurens Geffert · Sharla Gelfand · Monica Gerber · Duncan Gillespie · David Gohel · A. Cagri gokcek · Guadalupe Gonzalez · Rohit Goswami · Laura Graham · Charles Gray · Matthias Grenié · Corinna Gries · Hugo Gruson · Ernest Guevarra · W Kyle Hamilton · Ivan Hanigan · Jeffrey Hanson · Liz Hare · Jon Harmon · Rayna Harris · Ted Hart · Nujcharee Haswell · Verena Haunschmid · Stephanie Hazlitt · Andrew Heiss · Max Held · Anna Hepworth · Bea Hernandez · Jim Hester · Peter Hickey · Roel Hogervorst · Kelly Hondula · Allison Horst · Sean Hughes · James Hunter · Brandon Hurr · Ger Inberg · Christopher Jackson · Najko Jahn · Tamora D James · Veronica Jimenez-Jacinto · Mike Johnson · Will Jones · Max Joseph · Megha Joshi · Krunoslav Juraic · Soumya Kalra · Zhian N. Kamvar · Michael Kane · Andee Kaplan · Tinula Kariyawasam · Hazel Kavılı · Jonathan Keane · Christopher T. Kenny · Os Keyes · Eunseop Kim · Aaron A. King · Michael Koontz · Bianca Kramer · Will Landau · Sam Lapp · Erin LeDell · Thomas Leeper · Sam Levin · Lisa Levinson · Stephanie Locke · Marion Louveaux · Robin Lovelace · Julia Stewart Lowndes · Tim Lucas · Muralidhar, M.A. · Andrew MacDonald · Jesse Maegan · Mike Mahoney · Tristan Mahr · Yohann Mansiaux · Paula Andrea Martinez · Anthony Martinez · Joao Martins · Ben Marwick · Claire Mason · Miles McBain · Lucy D’Agostino McGowan · Amelia McNamara · Elaine McVey · Bryce Mecum · Nolwenn Le Meur · François Michonneau · Mario Miguel · Helen Miller · Beatriz Milz · Jessica Minnier · Priscilla Minotti · Nichole Monhait · Kelsey Montgomery · Ronny A. Hernández Mora · Paula Moraga · Natalia Morandeira · George Moroz · Ross Mounce · Athanasia Monika Mowinckel · Lincoln Mullen · Matt Mulvahill · Maria Victoria Munafó · David Neuzerling · Dillon Niederhut · Joel Nitta · Rory Nolan · Kari Norman · Jakub Nowosad · Matt Nunes · Daniel Nüst · Lauren O’Brien · Joseph O’Brien · Paul Oldham · Samantha Oliver · Dan Olner · Jeroen Ooms · Victor Ordu · Luis Osorio · Philipp Ottolinger · Mark Padgham · Marina Papadopoulou · Edzer Pebesma · Thomas Lin Pedersen · Antonio J. Pérez-Luque · Marcelo S. Perlin · Rafael Pilliard-Hellwig · Rodrigo Neto Pires · Lindsay Platt · Nicholas Potter · Joanne Potts · Josep Pueyo-Ros · Etienne Racine · Manuel Ramon · Nistara Randhawa · David Ranzolin · Quentin Read · Neal Richardson · tyler rinker · Emily Robinson · David Robinson · Alec Robitaille · Francisco Rodriguez-Sanchez · Sam Rogers · Julia Romanowska · Xavier Rotllan-Puig · Bob Rudis · Edgar Ruiz · Kent Russel · Michael Sachs · Sheila M. Saia · Chitra M Saraswati · Alicia Schep · Klaus Schliep · Clemens Schmid · Patrick Schratz · Collin Schwantes · Marco Sciaini · Eric Scott · Heidi Seibold · Julia Silge · Margaret Siple · Peter Slaughter · Mike Smith · Tuija Sonkkila · Øystein Sørensen · Jemma Stachelek · Christine Stawitz · Irene Steves · Kelly Street · Matt Strimas-Mackey · Alex Stringer · Michael Sumner · Chung-Kai Sun · Sarah Supp · Emi Tanaka · Jason Taylor · Filipe Teixeira · Andy Teucher · Jennifer Thompson · Joe Thorley · Nicholas Tierney · Tiffany Timbers · Tan Tran · Tim Trice · Utku Turk · Zoë Turner · Kyle Ueyama · Ted Underwood · Adithi R. Upadhya · Kevin Ushey · Josef Uyeda · Frans van Dunné · Mauricio Vargas · Remi Vergnon · Jake Wagner · Ben Ward · Elin Waring · Rachel Warnock · Leah Wasser · David Watkins · Lukas Weber · Marc Weber · Karissa Whiting · Stefan Widgren · Anna Willoughby · Saras Windecker · Luke Winslow · David Winter · Sebastian Wójcik · Witold Wolski · Kara Woo · Marvin N. Wright · Jacob Wujciak-Jens · Bruna Wundervald · Lauren Yamane · Emily Zabor · Taras Zakharko · Sherry Zhang · Hao Zhu · Chava Zibman · Naupaka Zimmerman · Jake Zwart · Felipe · santikka · kasselhingee · Bri · Flury · Vincent · eholmes · Pachá · Rich · Claudia · Jasmine · Zack · Lluís · becarioprecario · gaurav
+We are also grateful to the following individuals who have served as guest editors.
+ + + ++This chapter contains the policies of rOpenSci Software Peer Review. +
++In particular, you’ll read our policies regarding software peer review itself: the review submission process including our conflict of interest policies, and the aims and scope of the Software Peer Review system. This chapter also features our policies regarding package ownership and maintenance. +
++Last but not least, you’ll find the code of conduct of rOpenSci Software Peer Review. +
+Following criteria are meant to be a guide for what constitutes a conflict of interest for an editor or reviewer. The potential editor or reviewer has a conflict of interest if:
+In the case where none of the associate editors can serve as editor, an external guest editor will be recruited.
+rOpenSci aims to support packages that enable reproducible research and managing the data lifecycle for scientists. Packages submitted to rOpenSci should fit into one or more of the categories outlined either below. Statistical software may also be submitted for peer review, for which we have a separate set of guidelines and standards. The categories below are for general, and not statistical, software, while the remainder of this chapter applies to both kinds of software. If you are unsure whether your package fits into one of the general or statistical categories, please open an issue as a pre-submission inquiry (Examples).
+As this is a living document, these categories may change through time and not all previously onboarded packages would be in-scope today. For instance, data visualization packages are no longer in-scope. While we strive to be consistent, we evaluate packages on a case-by-case basis and may make exceptions.
+Note that not all rOpenSci projects and packages are in-scope or go through peer review. Projects developed by staff or at conferences may be experimental, exploratory, address core infrastructure priorities and thus not fall into these categories. Look for the peer-review badge - see below - to identify peer-reviewed packages in the rOpenSci repository.
+
data retrieval: Packages for accessing and downloading data from online sources with scientific applications. Our definition of scientific applications is broad, including data storage services, journals, and other remote servers, as many data sources may be of interest to researchers. However, retrieval packages should be focused on data sources / topics, rather than services. For example a general client for Amazon Web Services data storage would not be in-scope. (Examples: rotl, gutenbergr)
data extraction: Packages that aid in retrieving data from unstructured sources such as text, images and PDFs, as well as parsing scientific data types and outputs from scientific equipment. Statistical/ML libraries for modeling or prediction are typically not included in this category, nor are code parsers. Trained models that act as utilities (e.g., for optical character recognition), may qualify. (Examples: tabulizer for extracting tables from PDF documents, genbankr for parsing files from GenBank, treeio for phylogentic reading in phylogentic tree files, lightr for parsing files from spectroscopic instruments))
data munging: Packages for processing data from formats above. This area does not include broad data manipulations tools such as reshape2 or tidyr, or tools for extracting data from R code itself. Rather, it focuses on tools for handling data in specific scientific formats generated from scientific workflows or exported from scientific instruments. (Examples: plateR for reading in data structured as plate maps for scientific instruments, or phonfieldwork for processing annotated audio files for phonics research)
data deposition: Packages that support deposition of data into research repositories, including data formatting and metadata generation. (Example: EML)
data validation and testing: Tools that enable automated validation and checking of data quality and completeness as part of scientific workflows. (Example: assertr)
workflow automation: Tools that automate and link together workflows, such as build systems and tools to manage continuous integration. Does not include general tools for literate programming. (e.g., R markdown extensions not under the previous topics). (Example: drake)
version control: Tools that facilitate the use of version control in scientific workflows. Note that this does not include all tools that interact with online version control services (e.g., GitHub), unless they fit into another category. (Example: git2rdata)
citation management and bibliometrics: Tools that facilitate managing references, such as for writing manuscripts, creating CVs or otherwise attributing scientific contributions, or accessing, manipulating or otherwise working with bibliometric data. (Example: RefManageR)
scientific software wrappers: Packages that wrap non-R utility programs used for scientific research. These programs must be specific to research fields, not general computing utilities. Wrappers must be non-trivial, in that there must be significant added value above simple system() calls or bindings, whether in parsing inputs and outputs, data handling, etc. Improved installation process, or extension of compatibility to more platforms, may constitute added value if installation is complex. This does not include wrappers of other R packages or C/C++ libraries that can be included in R packages. It also does not include packages that are clients for web APIs, which must fall into one of the other categories. We strongly encourage wrapping open-source and open-licensed utilities - exceptions will be evaluated case-by-case, considering whether open-source options exist. (Examples: babette, nlrx)
field and laboratory reproducibility tools: Packages that improve reproducibility of real-world workflows through standardization and automation of field and lab protocols, such as sample tracking and tagging, form and data sheet generation, interfacing with laboratory equipment or information systems, and executing experimental designs. (Example: baRcodeR)
database software bindings: Bindings and wrappers for generic database APIs (Example: rrlite)
In addition, we have some specialty topics with a slightly broader scope.
+geospatial data: We accept packages focused on accessing geospatial data, manipulating geospatial data, and converting between geospatial data formats. (Examples: osmplotr, tidync).
translation: As part of our work in multilingual publishing, we have a special interest in packages that facilitate the translation and publication of scientific and programming resources into multiple (human) languages so they are accessible to larger and more diverse audiences. These could include interfaces to automated translation programs, frameworks for managing documentation in multiple languages, or programs accessing specialized linguistic resources. This is a new and experimental scope, so please open a pre-submission inquiry if you are interested in submitting a package in this category.
Packages should be general in the sense that they should solve a problem as broadly as possible while maintaining a coherent user interface and code base. For instance, if several data sources use an identical API, we prefer a package that provides access to all the data sources, rather than just one.
+Packages that include interactive tools to facilitate researcher workflows (e.g., shiny apps) must have a mechanism to make the interactive workflow reproducible, such as code generation or a scriptable API.
+For packages that are not in the scope of rOpenSci, we encourage submitting them to CRAN, BioConductor, as well as other R package development initiatives (e.g., cloudyr), and software journals such as JOSS, JSS, or the R journal, depending on the current scopes of those journals.
+Note that the packages developed internally by rOpenSci, through our events or through collaborations are not all in-scope for our Software Peer Review process.
+rOpenSci encourages competition among packages, forking and re-implementation as they improve options of users overall. However, as we want packages in the rOpenSci suite to be our top recommendations for the tasks they perform, we aim to avoid duplication of functionality of existing R packages in any repo without significant improvements. An R package that replicates the functionality of an existing R package may be considered for inclusion in the rOpenSci suite if it significantly improves on alternatives in any repository (RO, CRAN, BioC) by being:
+These factors should be considered as a whole to determine if the package is a significant improvement. A new package would not meet this standard only by following our package guidelines while others do not, unless this leads to a significant difference in the areas above.
+We recommend that packages highlight differences from and improvements over overlapping packages in their README and/or vignettes.
+We encourage developers whose packages are not accepted due to overlap to still consider submittal to other repositories or journals.
+Authors of contributed packages essentially maintain the same ownership they had prior to their package joining the rOpenSci suite. Package authors will continue to maintain and develop their software after acceptance into rOpenSci. Unless explicitly added as collaborators, the rOpenSci team will not interfere much with day to day operations. However, this team may intervene with critical bug fixes, or address urgent issues if package authors do not respond in a timely manner (see the section about maintainer responsiveness).
+If package maintainers do not respond in a timely manner to requests for package fixes from CRAN or from us, we will remind the maintainer a number of times, but after 3 months (or shorter time frame, depending on how critical the fix is) we will make the changes ourselves.
+The above is a bit vague, so the following are a few areas of consideration.
+foo is imported by one or more packages on CRAN, and foo is broken, and thus would break its reverse dependencies.bar may not have reverse dependencies on CRAN, but is widely used, thus quickly fixing problems is of greater importance.hello is not on CRAN, or on CRAN, but has no reverse dependencies.world needs some fixes. The maintainer has responded but is simply very busy with a new job, or other reason, and will attend to soon.We urge package maintainers to make sure they are receiving GitHub notifications, as well as making sure emails from rOpenSci staff and CRAN maintainers are not going to their spam box. Authors of onboarded packages will be invited to the rOpenSci Slack to chat with the rOpenSci team and the greater rOpenSci community. Anyone can also discuss with the rOpenSci community on the rOpenSci discussion forum.
+Should authors abandon the maintenance of an actively used package in our suite, we will consider petitioning CRAN to transfer package maintainer status to rOpenSci.
+rOpenSci strives to develop and promote high quality research software. To ensure that your software meets our criteria, we review all of our submissions as part of the Software Peer Review process, and even after acceptance will continue to step in with improvements and bug fixes.
+Despite our best efforts to support contributed software, errors are the responsibility of individual maintainers. Buggy, unmaintained software may be removed from our suite at any time.
+In the unlikely scenario that a contributor of a package requests removal of their package from the suite, we retain the right to maintain a version of the package in our suite for archival purposes.
+rOpenSci packages and other tools are used for a variety of purposes, but our focus is on tools for research. We expect that tools will enable ethical use by research practitioners, who are obligated to adhere to ethical codes such Declaration of Helsinki and The Belmont Report. Researchers bear responsibility for their use of software, but software developers must consider the ethical use of their products, and developers themselves adhere to ethical codes for computer professionals such as those expressed by IEEE and ACM. rOpenSci contributors often play both the role of both researcher and developer.
+We ask that software developers place themselves in researchers’ role and consider the requirements of an ethical workflow using authors’ software. Given the variation and degree of flux of ethical approaches for Internet-based analyses, judgement calls rather than recipes are required. The Ethical Guidelines of The Association of Internet Researchers provides a robust framework and we encourage authors, editors, and reviewers to use this in evaluating their work. In general, adherence to legal or regulatory minimum requirements may not be sufficient, though these (e.g., GDPR), may be relevant. Package authors should direct users to relevant resources for the ethical use of the software.
+Some packages, due to the nature of data they handle, may be determined by editors to require enhanced scrutiny. For these, editors may require additional (or reduced) functionality, and robust documentation, defaults, and warnings to direct users to relevant ethical practices. The following topics may merit enhanced scrutiny:
+Vulnerable populations: Authors of packages and workflows that deal with information related to vulnerable populations bear responsibility to protect them from likely harms.
Personally identifiable or sensitive data: The release of personally identifiable or sensitive data is potentially harmful. This includes “reasonably re-identifiable” data - which a motivated individual could trace back to the owner or creator even if the data are anonymized. This includes both cases where identifiers (e.g., name, date of birth) are available as part of data, and also if unique pseudonyms/screen names are linked with full-text posts, through which one can link back individuals through cross-reference with other data sets.
While the best response to ethical concerns will be context-specific, these general guidelines should be followed by packages where the challenges above arise:
+Packages should adhere to data source’s terms of use, as expressed in website Terms and Conditions, “robots.txt” files, privacy policies, and other relevant restrictions, and link to them prominently in package documentation. Packages should provide or document functionality to adhere to such restrictions (e.g., scrape from only allowed endpoints, use appropriate rate limiting in code, examples, or vignettes). Note that while Terms and Conditions, Privacy Policies, etc., may not provide sufficient bounds on ethical usage, they can provide an outer bound.
A key tool in addressing the risks posed in studying vulnerable populations or using personally identifiable data is informed consent. Package authors should support users’ acquisition of informed consent when relevant. This may include providing links to data source’s preferred method of acquiring consent, contact information of data providers (e.g. forum moderators), documentation of informed consent protocols, or getting pre-approval for general uses of a package.
+Note that consent is not implicitly granted just because data are accessible. Accessible data are not necessarily public, as different persons and contexts have different normative expectations of privacy (see work by Social Data Lab).
+Packages accessing personally identifiable information should take special care to follow [security best practices][Package Development Security Best Practices] (e.g., exclusive use of secure internet protocols, strong mechanisms for storing credentials, etc.).
Packages that access or handle personally identifiable or sensitive data should enable, document, and demonstrate workflows for de-identification, secure storage, other best practices to minimize risk of harm.
As standards for data privacy and research continue to evolve, we welcome input from authors on considerations specific to their software and supplemental documentation such as approval from university ethics review boards. These may be attached to issue threads of package submissions or pre-submission inquiries, or conveyed directly to editors if needed. General suggestions may be filed as issues in this book’s repository.
+The following resources may be helpful for researchers, package authors, editors and reviewers in addressing ethical questions related to privacy and research software.
+rOpenSci’s community is our best asset. Whether you’re a regular contributor or a newcomer, we care about making this a safe place for you and we’ve got your back. We have a Code of Conduct that applies to all people participating in the rOpenSci community, including rOpenSci staff and leadership and to all modes of interaction online or in person. The Code of Conduct is maintained on the rOpenSci website.
+ + ++Thanks for accepting to review a package for rOpenSci! This chapter consists of our guidelines to prepare, submit and follow up on your review. +
++You might contact the editor in charge of the submission for any question you might have about the process or your review. +
++Please strive to complete your review within 3 weeks of accepting a review request. We will aim to remind reviewers of upcoming and past due dates. Editors may assign additional or alternate reviewers if a review is excessively late. +
++rOpenSci’s community is our best asset. We aim for reviews to be open, non-adversarial, and focused on improving software quality. Be respectful and kind! See our reviewers guide and code of conduct for more. +
++If you use our standards/checklists etc. when reviewing software elsewhere, do tell the recipients (e.g. journal editors, students, internal code review) that they came from rOpenSci, and tell us in our public forum, or privately by email. +
+Thank you for your desire to participate in rOpenSci software peer-review as a reviewer!
+Please fill our volunteering form.
+If you see a current submission that is particularly relevant to your interests please email info@ropensci.org, including the name of the package, the URL to the submission issue and the name of the assigned editor. However, keep in mind that reviewer invitations are kept at the editor’s discretion, and the editor might well have already emailed people. Please do not volunteer for all issues, and do not volunteer via GitHub interface.
For other ways to contribute, refer to rOpenSci contributing guide.
+Reviews should be based on the latest GitHub version on the default branch, unless otherwise indicated by package authors. All submissions trigger a detailed report on package structure and functionality, generated by our pkgcheck package. If the package has changed substantially since the last checks, you may request a re-check with the command @ropensci-review-bot check package. Note that when installing the package to review it, you should make sure you have all dependencies available (for instance run pak::pak()).
To review a package, please begin by copying our review template (or our review template in Spanish) and using it as a high-level checklist. In addition to checking off the minimum criteria, we ask that you provide general comments addressing the following:
+Please be respectful and kind to the authors in your reviews. Our code of conduct is mandatory for everyone involved in our review process. We expect you to submit your review within 3 weeks, depending on the deadline set by the editor. Please contact the editor directly or in the submission thread to inform them about possible delays.
+We encourage you to use automated tools to facilitate your reviewing. These include:
+@ropensci-review-bot.devtools::check() and devtools::test() on the package to find any errors that may be missed on the author’s system.skip_on_cran() tests that do real API requests vs. skipping all tests on one operating system).pkgdown website is not necessarily up-to-date, and we recommend to inspect the package’s documentation locally by running pkgdown::build_site().Reviewers may also re-generate package check results from @ropensci-review-bot at any time by issuing the single comment in a review issue: @ropensci-review-bot check package.
If you interact with the package authors and talked about the review outside a review thread (in chats, DMs, in-person, issues in the project repository), please make sure that your review captures and/or links to elements from these conversations that are relevant to the process.
+First-time reviewers may find it helpful to read (about) some previous reviews. In general you can find submission threads of onboarded packages here. Here are a few chosen examples of reviews (note that your reviews do not need to be as long as these examples):
+bowerbird pre-review comment, review 1, review 2.
rusda review (from before we had a review template)
You can read blog posts written by reviewers about their experiences via this link. In particular, in this blog post by Mara Averick read about the “naive user” role a reviewer can take to provide useful feedback even without being experts of the package’s topic or implementation, by asking themselves “What did I think this thing would do? Does it do it? What are things that scare me off?”. In another blog post Verena Haunschmid explains how she alternated between using the package and checking its code.
+As both a former reviewer and package author Adam Sparks wrote this “[write] a good critique of the package structure and best coding practices. If you know how to do something better, tell me. It’s easy to miss documentation opportunities as a developer, as a reviewer, you have a different view. You’re a user that can give feedback. What’s not clear in the package? How can it be made more clear? If you’re using it for the first time, is it easy? Do you know another R package that maybe I should be using? Or is there one I’m using that perhaps I shouldn’t be? If you can contribute to the package, offer.”
+If working in RStudio, you can streamline your review workflow by using the pkgreviewr package created by associated editor Anna Krystalli. Say you accepted to review the refnet package, you’d write
remotes::install_github("ropensci-org/pkgreviewr")
+library(pkgreviewr)
+pkgreview_create(pkg_repo = "embruna/refnet",
+ review_parent = "~/Documents/workflows/rOpenSci/reviews/")and
+refnet package will be cloned.We encourage you to ask questions and provide feedback on the review process on our forum.
+Authors should respond within 2 weeks with their changes to the package in response to your review. At this stage, we ask that you respond as to whether the changes sufficiently address any issues raised in your review. We encourage ongoing discussion between package authors and reviewers, and you may ask editors to clarify issues in the review thread as well.
+You’ll use the approval template.
+ + +