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

Tue Mar 18 21:29:44 CET 2025

Hi,

Thanks for the replies.

I made a few updates to biocthis to match some requests from a recent
December 2024 package review:
https://github.com/Bioconductor/Contributions/issues/3503#issuecomment-2551233199.
The changes are described at
https://github.com/lcolladotor/biocthis/blob/devel/NEWS.md#biocthis-1172.
Overall:

* dev/ is now on the package .gitignore file
* BugReports will by default point to the GitHub issues URL rather
than the Bioconductor Support website, as was requested in that review
and noted at https://contributions.bioconductor.org/description.html#description-bugreport.
   - Originally it was the reverse since I wanted biocthis to point
people to use the Bioconductor Support website more often. But well,
technically bug reports are indeed better as GitHub issues. There's no
URL for "questions about this package" in which to point users to the
Bioconductor Support website. Note that the common practice (also
noted at https://contributions.bioconductor.org/description.html#description-url)
is to use "URL" for the source files. Though I think that you can
specify more than one URL. Hmm....
* a vignettes/.gitignore file is no longer created. However, I do
still recommend ignoring vignettes/*.html and vignettes/*.R files,
which is something usethis::use_vignette() also recommends. Aka, these
files are now ignored on the main .gitignore.
* I removed some code from the template vignette provided by biocthis
that was suggested to be removed in that same review as well as in
https://github.com/Bioconductor/Contributions/issues/3501#issuecomment-2408081535.

Some things I didn't change in biocthis are:

* I didn't change the behavior of the two README files given Marcel's
response earlier. Marcel also clarified this in the GitHub issue
thread for our package under BioC review.
* I also think that it's ok to have the pkgdown/extra.css file which
enables us to have Bioconductor colors in our pkgdown websites
https://github.com/lcolladotor/biocthis/blob/707c1ed015e12bd2b78e8b2f0feb60a41a00e4a5/R/use_bioc_pkgdown_css.R#L28-L30.
Aka, I didn't put pkgdown/ in the main package .gitignore file.
* Similarly I didn't add the codecov.yml file to a .gitignore. Aka,
via a usethis::use_git_ignore("codecov.yml") call before
https://github.com/lcolladotor/biocthis/blob/e895507fc5312e5f3e95eafeee0a03428471c363/inst/templates/03_core_files.R#L68.
You need this file to get code coverage information from GitHub
actions workflow steps such as
https://github.com/lcolladotor/biocthis/blob/e895507fc5312e5f3e95eafeee0a03428471c363/inst/templates/check-bioc.yml#L255.

Best,
Leo

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

On Sat, Mar 15, 2025 at 5:20 AM Lluís Revilla <lluis.revilla using gmail.com> wrote:
>
> Hi,
>
> On Fri, 14 Mar 2025 at 15:53, Marcel Ramos
> <marcel.ramosperez45 using login.cuny.edu> wrote:
> >
> > 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?
>
> I don't remember the release switching from svn.bioconductor.org to
> git.bioconductor.org (it was around 2018 I think) but here is a
> BiocCheck's manual page without forbidding these files from the
> release around that year:
> https://bioconductor.org/packages/3.5/bioc/vignettes/BiocCheck/inst/doc/BiocCheck.html
> I haven't gone through all versions but on version 3.10 the vignette
> forbids files such as .Rproj or .github.
> If this is not enough, here are some repositories showing that these
> files were included before they were forbidden.
>  Non R-related files (.github, travis.yml, ...):
> https://code.bioconductor.org/browse/rhdf5filters/,
> https://code.bioconductor.org/browse/methylKit/,
> Here many packages with .Rproj:
> https://code.bioconductor.org/search/search?q=f%3A%5C.Rproj%24
>
> >
> > 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.
>
> Maybe package maintainers should improve the packages instead of the
> core team of Bioconductor.
> On CRAN, it is common for them to send requests to change packages to
> adapt to new policies and checks.
> I think this would be beneficial to improve Bioconductor packages and
> free some time from the Bioconductor core team. It might also help to
> simplify the build system.
>
> >
> > 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 using 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 using gmail.com
> >
> > _______________________________________________
> > Bioc-devel using r-project.org mailing list
> > https://urldefense.com/v3/__https://stat.ethz.ch/mailman/listinfo/bioc-devel__;!!LRXxDv2l!Q_N-tSpOLq_jYv9eiaqg8ADaED9WXdcKZptW6ptp0VaLJaEj_h06XkG_zkGmu6GCqCSgEVAiwLDeMa1XMV-ohkEMrY0$
> >
> > --
> >
> > ____
> >
> > *Marcel Ramos, MPH*
> > Sr. Data Scientist
> >
> > CUNY Graduate School of Public Health & Health Policy
> > 55 W. 125th Street, Room 621| New York, NY 10027
> > marcel.ramos using sph.cuny.edu <mailto:marcel.ramos using sph.cuny.edu> | (646)
> > 364-9585
> > sph.cuny.edu <https://sph.cuny.edu >
> >
> >         [[alternative HTML version deleted]]
> >
> > _______________________________________________
> > Bioc-devel using r-project.org mailing list
> > https://urldefense.com/v3/__https://stat.ethz.ch/mailman/listinfo/bioc-devel__;!!LRXxDv2l!UQMRNwXFwFGNEssPVvEgipF409Wcb0z3o6nDuCfLrjCli7p_Y9hqYzFCC-FJ7TfRqMdZ7gmCWdJXBEd9Xx06Osxmr8eXTQ$
> >
> > ____
> >
> > Marcel Ramos, MPH
> > Sr. Data Scientist
> >
> > CUNY Graduate School of Public Health & Health Policy
> > 55 W. 125th Street, 6th Fl. | New York, NY 10027
> > marcel.ramos using sph.cuny.edu | (646) 364-9585
> > sph.cuny.edu
>
> _______________________________________________
> Bioc-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel