check documentation

[ThierryO]

• roxygen2version up to date
• NAMESPACE generated by roxygen2
• Rd files generated by roxygen2
• NAMESPACE up to date
• Rd files up to date
• pkgdown set
• require README.md
• README.Rmd (if present) was rendered to README.md
• require NEWS.md, no NEWS.Rmd
• NEWS.md contains an entry for the current version
• NEWS.md uses a standardised format.
• Make sure the package contains a vignette*

Items marked with * can be ignored when motivated.

[ElsLommelen]

It seems to me that a vignette is often much more important for users of a package than NEWS and CONTRIBUTION files etc., certainly when considering users that try a package for the first time. So I'm surprised that a vignette is not required, whereas NEWS, CONTRIBUTION and CODE OF CONDUCT files are required. I don't deny that NEWS etc. become increasingly important once the package is fully developed and has regular users, but to me it seems that the focus should first (before a first release) be on documentation of the functions and a vignette. They allow new users to discover your package. (If possible, also minimum standards for function documentation seem useful for me...)

[ThierryO]

I agree that a vignette is more important than the other files. However, you don't start a package by writing a vignette. Whereas the other files you mention can be a simple copy-paste operation. Hence my choice for making the vignette optional and the others mandatory.

I'm thinking about creating something like checklist::start_package() to generate an empty package that follows the INBO guidelines.

During this talk at UseR!2020, Noam Ross oppers to define different quality labels for package.

• bronze: the package meets all the minimal requirements
• silver: the package meets all the minimal requirements + an extra set of requirements
• gold: the package meets all the requirements

We could set e.g. require a vignette for a silver package, but not for a bronze package.

[ElsLommelen]

The ability to start from a template would indeed help a lot. At the moment it requires a lot of time to find out how everything should be added (and the out-dated cheatsheet on package development is not really helpful for that), and write the content as there is no standard yet...
At the moment it takes as much time to add all this than to add a vignette, which makes me choose for the vignette to start with (after functions are written).

I suppose starting a package without any requirements will always stay an option? Certainly when collaborating with novices in package development, I like starting without any CI checks (for them, I already try to meet local checks as good as possible) and gradually make them aware of the use of certain types of requirements before enforcing it with CI (these error messages can be quite intimidating for someone who tries to collaborate in package development for the first time, I think). In this case, the aim is to add CI and meet the requirements after the development and internal testing phase. (And by this time it is certainly possible to add a vignette...)

[ThierryO]

You can start without CI, but I strongly recommend against that. You risk of having to rewrite a lot of code in order to comply with the strict rules. Applying the rules from start and educating people from start is IMHO less frustating.

My idea to not enforce the vignette is that you can pass all the checks even with a rudementary package (e.g. just a single function).