[Bioc-devel] Readme in Rmd and md formats; .Rbuildignore'd files

[Leonardo Collado Torres]

Hi,

What's the issue with having a README.md and a README.Rmd file on the
Git repo for a Bioconductor package?

There's no such mention at
https://contributions.bioconductor.org/readme.html?q=readme#readme.
Also, a README.Rmd file can be included on the .Rbuildignore file
without any issues.

It feels weird to just include the README.md and not the README.Rmd.
That is, just including the rendered version makes it hard to update
later.

On the flip side, just including the README.Rmd version means that you
can't include the rendered version.

See other points in favor of both versions at
https://r-pkgs.org/other-markdown.html#readme.rmd-and-readme.md.

Is it a matter of automating a test in BiocCheck to make sure that
README.Rmd files are included in .Rbuildignore files? In case you are
concerned about R code being executed on your machines from those
README.Rmd files. Or auto-checking that any images used in the
README.md files are part of the .Rbuildignore files?


Anyways, I have known for a few years [1] that I think very
differently as I'm in favor of including files on Git repos that help
users & new developers and that can be excluded from packages source
tarballs thanks to .Rbuildignore. I overall feel that Bioc's push for
more strict control of which files are allowed is detrimental to both
users as well as new developers. Other examples are:

* the biocthis dev/ folder created by
https://lcolladotor.github.io/biocthis/reference/use_bioc_pkg_templates.html:
in particular the dev/04_update.R script is one that includes commands
new package developers typically forget to run after an update to
source files, like devtools::document() devtools::build_readme().
* the *.Rproj file which helps ensure some options are common across
the package author team (not all packages are made by 1 person!). This
one is listed at
https://contributions.bioconductor.org/general.html?q=unnec#undesirable-files
without much explanation.
* pkgdown and codecov yaml config files

If the above were just NOTEs on BiocCheck that are encouraged, but not
enforced during review, that would be one thing. Actually, from
searching https://github.com/Bioconductor/BiocCheck I don't see
anything about pkgdown or codecov yaml files, nor anything about
README.md and README.Rmd. I do see .Rproj mentioned at
https://github.com/Bioconductor/BiocCheck/blob/3e6bc8d50cbb34a8f1eeb13611ffefceed7461b0/R/BiocCheckGitClone.R#L2
which sadly does lead to en ERROR as noted at
https://www.bioconductor.org/packages/release/bioc/vignettes/BiocCheck/inst/doc/BiocCheck.html#bad-file-check
instead of a NOTE (I'd actually vote for fully allowing them, but a
NOTE would be ok to compromise on).

Best,
Leo

[1] https://github.com/lcolladotor/biocthis/issues/21

Leonardo Collado Torres, Ph. D.
Investigator, LIEBER INSTITUTE for BRAIN DEVELOPMENT
Assistant Professor, Department of Biostatistics
Johns Hopkins Bloomberg School of Public Health
855 N. Wolfe St., Room 382
Baltimore, MD 21205
lcolladotor.github.io
lcolladotor using gmail.com