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

Hi,

On 3/14/25 5:42 AM, Llu?s Revilla wrote:

Hi!

Before moving to git (and shortly after), Bioconductor used to support
these kind of files.

Can you point to where in the documentation these files were supported?

One can still find repositories with these files on code.bioconductor.org.

As these files are optional and might not even be described by
guidelines they do not bother new developers (or Bioconductor core).
Sure, they can be distracting if someone goes to read the source code
on the repository but so can a README and multiple vignettes.
One needs to familiarize itself with Bioconductor policies and
guidelines to see something as required, encouraged, optional or
forbidden.

Regarding "It is of interest to minimize the number of files not
relevant to BBS operations." The .Rbuildignore exists so that R
machinery doesn't have to deal with extra files to build and check
packages. Isn't that enough for BBS operations?

Our current guidelines were developed as a result of issues with extraneous
files and to minimize the amount of bloat in packages. The .Rbuildignore
file is not enough as packages sometimes do all sorts of unexpected things
that we have to fix.

I heard that Bioconductor is considering using the r-universe
infrastructure to build packages. If it ends up using it I think this
is even a less important concern as these files are allowed there (and
I would say even encouraged).

But if this is contentious, the CAB could summarize how the community
at large feels about adding those files to the repository.
Or as next month is the joint CAB-TAB joint meeting, it might be a
good moment to talk about this.

Best,

Llu?s

PS: .Rprofile is a standard .R file, I'm not sure which relation it
has with a specific IDE. But even IDE's specific files might be a
choice of the maintainers of the package to enable and encourage
community participation within some standards.

I meant to write .Rproj

On Tue, 11 Mar 2025 at 17:12, Marcel Ramos P?rez
<marcel.ramosperez45 at login.cuny.edu> wrote:

Hi Leo!

As Martha responded, there is no issue with having a README.Rmd in the
package folder.
(The section is not so clear and could use some revision)
Note that some authors maintain a README.md file without an Rmd.
For some of my packages, I re-use the vignette to generate the README.md
file.

But the bigger question is here "how much of the development environment
do we want to
allow in the package files?" It is not so clear where to draw this line.

IMO, having all the supporting developer files may help for didactic
purposes but for the
purposes of package functionality, they have little bearing. If one
starts to add
all sorts of files, they would be distracting and possibly overwhelming
to new
developers. As may often happen, developers (myself included) forget to
remove old
files from their packages allowing the cruft to accumulate. It is of
interest to minimize the
number of files not relevant to BBS operations.

I agree, an error for the .Rprofile file is a bit too strict and could
be flagged with a NOTE.
Though this may not be so relevant for Positron users :)

Best regards,

Marcel


On 3/11/25 10:00 AM, Leonardo Collado Torres wrote:

* This email originates from a sender outside of CUNY. Verify the sender before replying or clicking on links and attachments. *

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://urldefense.com/v3/__https://contributions.bioconductor.org/readme.html?q=readme*readme__;Iw!!LRXxDv2l!Q_N-tSpOLq_jYv9eiaqg8ADaED9WXdcKZptW6ptp0VaLJaEj_h06XkG_zkGmu6GCqCSgEVAiwLDeMa1XMV-ofA_t2Zo$ .
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://urldefense.com/v3/__https://r-pkgs.org/other-markdown.html*readme.rmd-and-readme.md__;Iw!!LRXxDv2l!Q_N-tSpOLq_jYv9eiaqg8ADaED9WXdcKZptW6ptp0VaLJaEj_h06XkG_zkGmu6GCqCSgEVAiwLDeMa1XMV-oT1xpgL8$ .

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://urldefense.com/v3/__https://lcolladotor.github.io/biocthis/reference/use_bioc_pkg_templates.html__;!!LRXxDv2l!Q_N-tSpOLq_jYv9eiaqg8ADaED9WXdcKZptW6ptp0VaLJaEj_h06XkG_zkGmu6GCqCSgEVAiwLDeMa1XMV-oA2u6Uo4$ :
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, likedevtools::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://urldefense.com/v3/__https://contributions.bioconductor.org/general.html?q=unnec*undesirable-files__;Iw!!LRXxDv2l!Q_N-tSpOLq_jYv9eiaqg8ADaED9WXdcKZptW6ptp0VaLJaEj_h06XkG_zkGmu6GCqCSgEVAiwLDeMa1XMV-oQbLf9-k$
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
searchinghttps://urldefense.com/v3/__https://github.com/Bioconductor/BiocCheck__;!!LRXxDv2l!Q_N-tSpOLq_jYv9eiaqg8ADaED9WXdcKZptW6ptp0VaLJaEj_h06XkG_zkGmu6GCqCSgEVAiwLDeMa1XMV-ozcncjiQ$  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://urldefense.com/v3/__https://github.com/Bioconductor/BiocCheck/blob/3e6bc8d50cbb34a8f1eeb13611ffefceed7461b0/R/BiocCheckGitClone.R*L2__;Iw!!LRXxDv2l!Q_N-tSpOLq_jYv9eiaqg8ADaED9WXdcKZptW6ptp0VaLJaEj_h06XkG_zkGmu6GCqCSgEVAiwLDeMa1XMV-ovxrWpLs$
which sadly does lead to en ERROR as noted at
https://urldefense.com/v3/__https://www.bioconductor.org/packages/release/bioc/vignettes/BiocCheck/inst/doc/BiocCheck.html*bad-file-check__;Iw!!LRXxDv2l!Q_N-tSpOLq_jYv9eiaqg8ADaED9WXdcKZptW6ptp0VaLJaEj_h06XkG_zkGmu6GCqCSgEVAiwLDeMa1XMV-oG3n79eQ$
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://urldefense.com/v3/__https://github.com/lcolladotor/biocthis/issues/21__;!!LRXxDv2l!Q_N-tSpOLq_jYv9eiaqg8ADaED9WXdcKZptW6ptp0VaLJaEj_h06XkG_zkGmu6GCqCSgEVAiwLDeMa1XMV-oWuxf7xw$

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 at gmail.com