This guide https://ropensci.org/technotes/2017/01/05/package-evolution/ by @sckott

The high-level principles in the reviewers' guide could probably stand to be updated, to reflect some of the themes that have made their way into the packaging guide in low-level standards, such as:

• Documentation should use the principle of multiple points of entry
• Functions and arguments naming should be chosen work together to form a common, logical programming API that is easy to read, and autocomplete.
  • (The following may be low-level, and are partially in the packaging guide, but should somehow be linked to the above)
  • Function names should follow a consistent scheme using prefixes, verbs, and objects.
  • Argument naming and order should be consistent across functions that use similar inputs. Data being operated on should generally be the first argument(s), with options and parameters following.

poke @annakrystalli (see it's on my TODO list now 🎊 )

When?

When it looks like the website? Cf #1 Or even before?
What about the progress of the contents before actively promoting?

How

• Blog post /tech note with a few highlights (saying where to find the old content, explaining the structure logic, indicating how to contribute, mentioning things that can apply to any R package developer e.g. Scott's chapter about package evolution).

• Tweets spread out in time with "gems" "from our gitbook about package development"?

cc @stefaniebutland

Leadership? Staff? Editorial team?

• GitHub topics

• Making a membership organization public

• Pinning a repo (after approval, important to remind authors they can still show off their repo!)

Not only in a survey, but also informally ask authors/reviewers/guest editors what was unclear to them.

In https://ropensci.github.io/dev_guide/onboardingintro.html, "rOpenSci’s suite of packages" links to our website https://ropensci.org/packages/, whereas elsewhere (can't recall), packages links to our GitHub https://github.com/ropensci.

CI abbrev shows up here https://ropensci.github.io/dev_guide/ci.html#whichci in between uses of full name in that same chapter section

Add the guidance to add them to https://github.com/r-hub/sysreqsdb

At codemeta.json creation (for the repo) the editor/author should check that dependencies written in SystemRequirements are captured.

Not urgent, but in the end the book should look like the website.

We might as well do this now to avoid having two sets of docs. Would it also make sense to deprecate onboarding-meta and put all discussion in this repo?

• mention the tag corresponding to onboarding blog posts on the website

A bit like https://www.tidyverse.org/contribute/ it'd be linked from our contributing.md template, and we could point people to it when they want to get more involved. cc @stefaniebutland

• Mention the discuss forum (a contribution can be asking questions, and helping to answer them)

• How to identify issues that are good for contributors? https://github.com/LucyMcGowan/contributr + a direct GitHub link https://github.com/search?q=user%3Aropensci+user%3Aropenscilabs+label%3ABeginner+state%3Aopen&type=Issues -- this should be linked to telling authors to use the "Beginner" label in the chapter about collaboration.

• Contributing links to use cases is a form of contribution. Where and how to submit them? So that they end up in the newsletter, and maybe in package repo READMEs?

• Add a few resources to learn package development (including the guide itself!) https://discuss.ropensci.org/t/recommend-resources-for-developing-my-first-r-package/578 because people who want to get involved might not know where to learn stuff to be able to contribute more.

e.g., https://github.com/ropensci/lingtypology/blob/master/NEWS

I would personally want everyone to break their release notes into sections so readers can quickly see, “oh, theres bug fixes”, or “oh, a new function”, etc. rather than having to sift through everything to get to sections of news they’re interested in

Thoughts? Can we add to our guide that we want users to break news into sections?

Cf comment by @daattali in ropensci-archive/packaging_guide#11 (comment)

https://github.com/ropensci/policies

need link to reference for "double-blind peer review can increase representation of female authors" in https://ropensci.github.io/dev_guide/onboardingintro.html#whyopen

Packaging guide proposal:

Package functions importing data should not import data to the global environment, but return objects (required). Assignments to the global environment are to be avoided in general.

It might be good to also develop some documentation on contributing to this guide?

That could just live in the README or in a contributing.md. Either way, some things to cover:

• PRs for new editors with perhaps direct pushes at a later stage
• clarify the tools used to maintain the gitbook
• outline build and commit procedure (a code walkthrough?)
• specify any dependencies (ie when I tried to bookdown::serve_build(), it failed because I didn't have package airtabler installed. This is not on cran so a link to the repo or a code snippet: r devtools::install_github("bergant/airtabler") would be useful.
• anything else that arises?

From a survey's respondent "Better understand what can be ignored from goodpractice reports"

Related to ropensci/roregistry#7

If topic labels in onboarding issues are meant to be used for reviewer matching, then they could disappear once we have more detailed data about potential reviewers, and once we have good package categories. We will need much more "topic" issue labels that what would be doable to have anyway.

Or are they used for browsing the issues? By whom?

I'm not sure we need other labels than the ones indicating progress of the (pre)-submission (including legacy, out of scope, and meta for old meta issues).

If this dev guide is to be a "landing page" for onboarding, its first chapter could include a live dashboard of issues, using JS to pull the status of issues from GH.

It's possible there should be a separate landing page which has just a few links to the book, the main repo issues, and maybe the sign up link, and maybe our packages page.

Should we if a package is using an alternative set (e.g., life cycle)

e.g., here’s a case of someone using a lifecycle badge https://github.com/nbenn/infx#infx in onboarding

I think we should make them change to repostatus since we’re going to use badges to categorize our pkgs

Via @noamross ropensci/software-review-meta#53

We've had some really good ones recently, and I think we want to make sure all of them use the review template. The rtika review is great from my perspective because it has substantial feedback on both technical and documentation sides. The NLMR one is also probably good example.

when it's a bit more in shape, e.g. with working unit tests, and with the blog post stuff moved to a branch.

Currently we recommend the use of goodpractice in the reviewing guide

If we start having goodpractice reports from Travis hooked to the submission, do we expect reviewers to run goodpractice::gp? Moreover, isn't it already a duplication of efforts since we post goodpractice results in the submission thread?

I understand that we want reviewers to use e.g. devtools::check because of different OS/locale/etc. but does this apply to goodpractice? It takes a while to run and here might be useless?

cf e.g. ropensci/software-review#216

Also a non urgent idea, use the collage from my Cape Town talk (the faces of onboarding) as an illustration somewhere?

Use tips from and add links to rOpenSci blog posts written by reviewers and when it's written also use and link @noamross' post on how to review

Cf comment by @karthik in ropensci-archive/packaging_guide#11 (comment)

And mention https://cran.r-project.org/web/packages/Rd2roxygen/index.html h/t @noamross to ease conversion

https://ropensci.github.io/dev_guide/releasing.html

https://ropensci.github.io/dev_guide/grooming.html

Survey respondent "Set clear expectations on review timelines"

Cf also ropensci/software-review-meta#36

• The packaging guide had an order of importance for things but I'm moving parts of it to dedicated chapters.

• in general in the book make a good difference between nice-to-have and necessary

• And if we add necessary things that were not necessary in the past, think well of how to implement the new guidelines.

http://pkgdown.r-lib.org/reference/build_home.html?q=authors#yaml-config-authors (so if one lists rOpenSci as fnd, one can add its logo!)

From a survey respondent "Since editors rely on goodpractice diagnostics to recommend
improvements, it could be a requirement for authors to run this
before submission and fix issues ahead of time"

Policies chapter needs a grey box "about" statement https://ropensci.github.io/dev_guide/policies.html

The builds pass on travis.org but I receive build fail emails from travis.com -- how will Travis transfer affect deployments created with tic setup @krlmlr?