[BUG] Add non standard directories and files to a .gitignore

[lshep]

We try to have the minimum basic package structure. It seems like in creation at least a dev folder with various templates/functions gets created. This should not be in a cloned copy of the repo and users would be asked to remove / .gitignore when submitting to Bioconductor. When these directories get created can it automatically be added to a .gitignore for a user. I'm not sure if there are other directories and files but noticed it in a recent submission.

[lcolladotor]

Hi Lori,

Thanks for the issue!

I brought this up at https://community-bioc.slack.com/archives/C6MVC96AZ/p1604600559030500 and while there was a discussion, I don't think that we reached a conclusion.

I'll ping that Slack channel again to resume the discussion. The answer might be different for say:

.github/workflows/something.yml
dev/*.R
something.Rproj

although well, Aaron Lun made the point that if it's under .Rbuildignore, it's likely ok to have the (small) files there.

Best,
Leo

[LiNk-NY]

FWIW, here is an example where this was done quite nicely:
https://stat.ethz.ch/pipermail/bioc-devel/2021-April/017937.html ->
https://github.com/jianhong/HMMtBroadPeak/tree/staging

One benefit is a cleaner git history where commits that only change the GHA file are on a different branch.

For folders like dev, those seem to be for developer use and could go in a separate branch or as local files since
these are generated from code.

[lshep]

Again from a Bioconductor review point of view too we don't know what files are related to what without looking. So whether or not they are harmless small files, I still came across a non standard directory that I had to take the time to investigate and ask to remove since they are developers files only. I am more stringent still on configuration files as well because as there is more and more discussion about investigating other options for the build system, we don't know how additional files or configuration files could potentially interfere with anything we are investigating. Having a branch that users have all this on, but a clean branch with no extras and just the minimum for Bioconductor still doesn't seem necessarily unreasonable.

[lcolladotor]

GHA on another branch

Thanks Marcel! I didn't know you could have the .github/workflow/something.yml file in another branch. That's good to know =) Although well, I don't think that it really affects Bioconductor if the git history includes commits for these configuration files. That is, the files are tiny and don't make the repos bigger, plus it doesn't trigger new builds in the BBS (unlike the SPB used by the submission system).

Now, if Bioconductor is thinking about switching to using GitHub Actions (GHA) and dropping the BBS, then that'd be a different story I guess. At that point, then using a GHA workflow in a package would only make sense before it gets accepted by Bioconductor. Anyway, I don't think that this is where you were going in your earlier comment.

"pure" git main branches?

Lori, I think that you are basically saying that Bioconductor would like clean/pure main branches in the repos without a .Rbuildignore file. That is, main branches where only the package code is present and nothing has to be ignored by R CMD build or Bioconductor Core / Reviewers.

.Rbuildignore: how about code for deleting the ignored files?

Yet, I think that this "pure" main branch situation is not ideal. I understand that Bioconductor doesn't want files that can be interfering with the build system, and well, maybe another solution is to go through the .Rbuildignore and delete files listed there as part of the Bioconductor builds. That is, clone the git repo on the main branch, find files in .Rbuildignore, delete them, then run R CMD build, etc. This is a similar suggestion to what Aaron Lun @LTLA and Kasper D Hansen @kasperdanielhansen said about .Rbuildignore at https://community-bioc.slack.com/archives/C6MVC96AZ/p1604610165052800, although instead of providing the package tarball we would keep the repos (aka, we keep the advantages Vince Carey mentioned at https://community-bioc.slack.com/archives/C6MVC96AZ/p1604662660055200).

The code for deleting files that are part of .Rbuildignore could be a little R helper function in say BiocCheck or some other main BioC package. The scenario that Martin Morgan mentioned at https://community-bioc.slack.com/archives/C6MVC96AZ/p1604606893040200 where he wants to clone a repo and do things to it (or simply check it out), would involve this extra step of using this helper function to delete .Rbuildignore files.

The "pure" git main branch

If Bioconductor goes down the path of a "pure" git main branch on repos, so only R package files, then we'll have to drop many things or argue why X, or Y exception is ok. Here's just a list of some files I know of and/or use myself:

• .Rproj: not having one on the git repos for BioC (aka, using .gitignore) is ok if you are working alone. But as soon as I work with others, then it becomes a tad painful to make sure everyone has the same config.
• data-raw/*.R is created by usethis::use_data_raw() which promotes documenting how you created the data files in a given R package.
• .github/*: for GitHub Actions but also for other GitHub related things, like the CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, ISSUE_TEMPLATE/issue_template.md files. The GHA workflow can live in another branch as Marcel pointed out, but I'm not so sure about the other files.
• codecov.yml: for covr
• README.md and README.Rmd for describing the git repo and for the pkgdown documentation websites
• pkgdown.yml: for using pkgdown to build our own documentation websites which have some advantages over the BioC landing pages
• travis.yml: used before GitHub actions for using Travis CI. And well, basically other yml or config files for using other CI solutions.
• inst/scripts/*.R and inst/extdata/*.csv files for ExperimentHub and AnnotationHub. These files are promoted by Bioconductor. That is, it's an example of non-R package files that have been approved by BioC. Surely, we could have them in another branch if we wanted to.
• dev/*.R which is an idea I implemented in biocthis based on golem by Colin Fay @ColinFay which uses that idea too. It's similar in spirit to data-raw by usethis from Jenny Bryan @jennybc but for package development. I very frequently re-run code from dev/04_update.R because well, that's what I wrote that script for. If I had it in another branch, then I would need to have 2 local clones of the repo or manually copy-paste code or something like that. I could also move dev to be inside inst/ if Bioconductor would prefer that setup. Though well, I don't that it would help the situation of "what are these custom files?" that Lori described.
• analysis is a directory we used with David Zhang @dzhang32 at https://github.com/LieberInstitute/megadepth/tree/master/analysis which contained some code we ran for the paper and a small image.

I do agree with Bioconductor that any files that are part of .Rbuildignore should be small, to avoid burdening the BioC system with large files.

Closing comments

I'm aware that we have different positions and I understand that Bioconductor does a lot of work already. I understand that Bioconductor reviewers and the core don't want to deal with any extra files, which well, I hope that .Rbuildignore enables some solutions. From my point of view, I'd like to use all the new things that others are building that can help make my experience building and/or maintaining my packages smoother and/or more reproducible.

I'm curious to see what the BioC core and/or the TAB will decide on this as Vince @vjcitn mentioned https://community-bioc.slack.com/archives/C6MVC96AZ/p1621476360003400. If you want me to, I'd be happy to present my point of view at such a meeting.

Anyways, I just want to thank you Lori, Marcel and the BioC core and reviewer teams for all that you do. Thanks!!

[lwaldron]

IMO there should be a clear cost:benefit rationale (accounting for costs to contributors, including those without advanced git skills), along with a clearly defined recommended workflow, to justify asking contributors to move convenience tools such as @lcolladotor outlines from the main branch. Otherwise it's hard to understand why things not noted by R CMD CHECK (because they're in .Rbuildignore) should be of concern to Bioconductor, if they have no impact on users of the software. If the cost:benefit analysis does favor elimination of convenience configurations and decorations, perhaps it would make more sense for Bioconductor to use a dedicated devel branch. That would come with its own challenges and might reduce the frequency with which contributors merge to devel and push upstream as opposed to relying on continuous integration on GitHub, but I think it would feel less controlling and easier to understand. I'd have to see the proposed workflows in each scenario to give an opinion on which I think would be the least burden for the most contributors.

[lcolladotor]

It's been nearly 2 years since this conversation started. Maybe we can talk about it at BioC2023? Or maybe the BioC core has an updated policy on this?

[vjcitn]

We should definitely continue this discussion. I have been trying to understand a least-resistance path to having a minimal package image in the main (soon to be named 'devel') branch at git.bioconductor.org, and an "extras" branch in github that has pkgdown and github actions support. It isn't totally straightforward for me because I am still somewhat in the woods with respect to remotes and branches and merges. .Rbuildignore plays a role, and it might be sufficient to just set that file up properly. I have long been under the impression that you can put whatever you like in /inst and thus I would anticipate the /dev and /analysis folders mentioned by @lcolladotor migrating to /inst.

I will try to articulate my approach to 'extras' in an example in the very near future. It has no official status and I would hope that the cloud working group (with its attention to github actions) and the core devs can come to a consensus, let's say during work on 3.18. If it can happen more rapidly, so much the better.

A document articulating the goals of expanding the content permitted or endorsed for Bioconductor packages, reasons for restrictions, and paths towards relaxing these restrictions (which may involve evolution of the operation of the BBS) would be most welcome, and a request for comments period can be opened to help us get input from the developer community. Here is a start on such a document. It is world-commentable, if you want to edit it just make a request.

[vjcitn]

So two submissions that use the 'extras' branch for actions and pkgdown are https://vjcitn.github.io/BiocHail/ and https://vjcitn.github.io/scviR/ ... it is not clear that scviR will build on windows owing to python jax infrastructure. BiocHail action is still running for the first time.

[vjcitn]

An example noted above (BiocHail) seems to give the lie to my attempt. I do not understand how to manage divergent branches. extras should have docs/ and .github, main should not.