Packaging guide home and scope

[maelle]

I think my questions are intertwined enough to be posted in a single issue.

Does the packaging guide apply to all rOpenSci packages or only onboarded ones?

I'm asking because of #22 + my wish to have a common set of issue labels to make it easier to identify problematic stale issues in a dashboard.

If the guide applies only to onboarded packages, then the .github and issue labels discussions might have to take place somewhere else?

Where should the packaging guide live?

One of us @ropensci/editors suggested to transform onboarding documents into a bookdown. If the packaging guide (including Github) applies to all packages, maybe it could have its own repo. And the bookdown for onboarding, if created, would be a guide of steps for the different roles and of our policies, with a link to the packaging guide and a link to the automatic tools (e.g. pkgreviewr).

Should it be called packaging guide?

It also already includes Github good practice such as releases. It might be because of my non-native-speakerness but to me packaging sounds like putting things into a package, before being done, so doesn't really apply to the nurturing and maintenance of a package. Is this document "Guide for rOpenSci package developpers and maintainers"?

[sckott]

1. In theory applies to all pkgs, but it's probably a bit harder to motivate to change pkgs that have been around a while - things like changing issue labels I think would be no problem to do across ropensci - and I think .github files too we could probably convince everyone to use
2. I agree to do a bookdown
3. good question. i'm up for a different name, can't think of any right now though

[maelle]

The packaging guide was mentioned twice in Jim Hester's talk at rstudio::conf

[noamross]

I think the packaging guide AND the reviewers guide AND the editors guide should all be in a common gitbook. So it could be named something like "rOpenSci Packages: Development, Maintenance, and Peer Review." It can have high-level sections like "Package Standards", "Peer Review Process", "Checklists and Templates" for different components. It can have its own repo, and the documentation in the onboarding repo should be minimized to a small set of things in the README including links to pages in the gitbook, and the .github directory templates. Templates that are expected to be copy-pasted should be code blocks in the reference section of the book. My logic here is that one gitbook, with well-named sections in the sidebar, should make it easy to navigate all of the relevant information.

[karthik]

I love the idea of calling it something like "Guide for rOpenSci package developpers and maintainers". Or what Noam suggested above.

[karthik]

And Noam articulated everything I agree with.

[maelle]

Just a note that for tools such as @annakrystalli's pkgreviewr it'll be important to have templates as separate files (that can be automatically rendered in the bookdown as code blocks).

[maelle]

I started a bookdown at https://github.com/ropenscilabs/dev_guide/ (rendered version https://ropenscilabs.github.io/dev_guide/ ) and will close this issue, discussion related to that bookdown could move to the bookdown repo.