Merge branch 'Bioconductor:devel' into master

Author: lshep

_bookdown.yml

@@ -39,7 +39,7 @@ rmd_files: ["index.Rmd",
            "volunteer-to-review.Rmd",
            "appendix.Rmd",
            "devel-branch.Rmd",
-           "long-tests.Rmd",
+           "advanced-build-options.Rmd",
            "web-query.Rmd",
            "c-and-fortran.Rmd",
            "mavericks.Rmd",

long-tests.Rmd advanced-build-options.Rmdlong-tests.Rmd renamed to advanced-build-options.Rmd

@@ -1,6 +1,25 @@
-# Long Tests
+# Advanced Build Options
 
-## What are they
+An optional `.BBSoptions` file at the package root can alter the default
+build behavior, such as excluding a package from unsupported platform or
+including a package in an optional build.
+
+## Skipping builds on unsupported platforms
+
+In the `.BBSoptions` file, add the line `UnsupportedPlatforms:` with the
+platform--`win`, `win64`, or `mac`--or the name of a build node. For example
+
+    UnsupportedPlatforms: win64, kjohnson3
+
+## Optional builds: long tests and GPU builds
+
+Two optional builds are available to software packages: long tests and GPU
+builds. Maintainers can opt their packages in to these builds using the
+`.BBSoptions` file.
+
+### Long tests
+
+#### What are they
 
 Code in the `tests` subdirectory of all Bioconductor software
 packages is run by `R CMD check` on a daily basis as part of
@@ -12,7 +31,7 @@ Package developers who wish to implement `tests` that will be too long
 to run in the context of the nightly builds can set up "long tests" in
 their package and add the package to the Bioconductor _Long Tests builds_.
 
-## Setup
+#### Setup
 
 4 steps:
 
@@ -39,7 +58,7 @@ Note that we also run the _Long Tests builds_ for the current release
 branch once a week (every Saturday). The latest report for these builds
 is [here][release-LongTests-report].
 
-## "Short tests" vs "long tests"
+#### "Short tests" vs "long tests"
 
 The _Long Tests_ setup forces developers to split the testing code
 in their package between "short tests" and "long tests". The former go in
@@ -54,8 +73,25 @@ prevent a package from propagating after a version bump. In other words,
 even if a package is included in the _Long Tests builds_, propagation
 is still determined by the results of the nightly builds.
 
+### GPU builds
+
+If a package needs a GPU to properly build it should be added to the
+[GPU builds][devel-GPU-report], which build and check packages on GPU machines.
+In the `.BBSoptions` file, maintainers should set `GPU_reliance` term to
+`required`:
+
+    ```
+    GPU_reliance: required
+    ```
+
+If a package supports GPUs if available, maintainers may opt in to the build
+by setting the `GPU_reliance` term set to `optional:
+
+    ```
+    GPU_reliance: optional
+    ```
+
 ## Need help?
 
 Ask on the [bioc-devel][bioc-devel-mail] mailing list if you have questions or
-need help with the _Long Tests builds_.
-
+need help.

documentation.Rmd

@@ -62,10 +62,13 @@ All packages are required to have at least one Rmd, qmd, or Rnw vignette.
 Vignettes go in the `vignettes/` directory of the package. Vignettes are often
 used as standalone documents, so best practices are to include an informative
 title, the primary author of the vignette, the last modification date of the
-vignette, and a link to the package landing page. We encourage the use of
-`r BiocStyle::Biocpkg("BiocStyle")` with `html_document` as the rendering
-function. For example, in an R Markdown vignette one can use the following
-specification in the yaml front matter:
+vignette, and a link to the package landing page.
+
+### RMarkdown vignettes
+
+We encourage the use of `r BiocStyle::Biocpkg("BiocStyle")` with the
+`html_document` rendering function. For example, in an R Markdown vignette one
+can use the following specification in the yaml front matter:
 
 ```yaml
 output:
@@ -91,6 +94,31 @@ vignette: >
   %\VignetteEncoding{UTF-8}
 ```
 
+### Quarto vignettes
+
+More recently, `quarto` vignettes have been introduced as a new format for
+vignettes. Quarto vignettes are similar to R Markdown but offer more advanced
+features, flexibility, and multi-language support. The yaml front matter for a
+Quarto vignette is similar to R Markdown, but it uses `quarto::html` as the
+rendering function. For example, in a Quarto vignette one can use the following
+specification in the yaml front matter:
+
+```yaml
+vignette: >
+  %\VignetteEngine{quarto::html}
+  %\VignetteIndexEntry{1. Quick Start: An Introduction}
+  %\VignetteEncoding{UTF-8}
+```
+
+In addition to the yaml front matter, vignette authors must ensure that the
+`quarto` command line tool is listed as a `SystemRequirements` in the
+`DESCRIPTION` file, as well as, indicate that the `VignetteBuilder` is set to
+`quarto` in the `DESCRIPTION` file:
+
+```r
+VignetteBuilder: quarto
+```
+
 Some best practices and requirements for writing _Bioconductor_ vignettes are
 detailed in the following sections.
 

git-version-control.Rmd

@@ -832,7 +832,7 @@ git branch and in the current release branch (e.g., `RELEASE_3_14`).
    Bump the version of the package by editing the `Version` field in the
    `DESCRIPTION` and commit the change __in a separate commit__. This allows to
    only `cherry-pick` the bug correction and avoid version number conflicts with
-   the Bioconductor branches when/if the bug fixes are ported to release. 
+   the Bioconductor branches when/if the bug fixes are ported to release.
 
         ## after version bump
         git add DESCRIPTION
@@ -1073,13 +1073,13 @@ You also must remove them from the git tree (the repository history), or else
 your repository will remain large.
 
 There are a few ways to remove large files from a git history. Here, we'll
-outline two options: 1) `git filter-repo`, and 2) the BFG repo cleaner. 
+outline two options: 1) `git filter-repo`, and 2) the BFG repo cleaner.
 These steps should be run on your local copy and (if necessary) pushed to your
 own github repository.
 
 #### Removing Large Files from History with filter-repo
 
-As of 2023, the recommended way is to first locate any large files, and 
+As of 2023, the recommended way is to first locate any large files, and
 then remove them with `git filter-repo`.
 
 1. Identify large files using [this git rev-list script](
@@ -1099,38 +1099,60 @@ history, in order of file size. Use this to identify the names of files to remov
 
 2. Remove them with [filter-repo](https://github.com/newren/git-filter-repo).
 
-This is a separate tool that you'll have to install 
+This is a separate tool that you'll have to install
 (with *e.g.* `pip3 install git-filter-repo`). Then, you can rewrite your repository
-history to remove files like this, where `<file-glob>` identifies your files:
+history to remove files. Here are a few examples:
+
+*   To remove a specific file:
+
+```
+git filter-repo --path path/to/your/large_file --invert-paths
+```
+
+*   To remove a folder:
 
 ```
-git filter-repo --path-glob '<file-glob>' --invert-paths
+git filter-repo --path path/to/your/folder/ --invert-paths
 ```
 
-For example, to remove all `.RData` files, you could use:
+*   To remove all files of a certain type (e.g. `.RData`):
 
 ```
 git filter-repo --path-glob '*.RData' --invert-paths
 ```
 
-This command may reset your remotes. Check with `git remote` and
+*   To remove all files larger than a certain size (e.g. 50MB):
+
+```
+git filter-repo --strip-blobs-bigger-than 50M
+```
+
+3. Final steps.
+
+This command may reset your remotes. Check with `git remote -v` and
 if needed, you can add remotes back in using something like this:
 
 ```
 git remote add origin [email protected]:<username>/<repo_name>
 git push --set-upstream origin devel --force
 ```
 
-Finally, we have to push with `--mirror` to reset the remote.
+Finally, we have to push with `--mirror` to reset the remote. This will update
+your remote repository on GitHub.
 
 ```
 git push --force --mirror
 ```
 
-Now, just notify everyone that they'll have to re-clone the new repository, since 
+Now, just notify everyone that they'll have to re-clone the new repository, since
 history has been rewritten, so existing clones will no longer be compatible
 with this repo.
 
+If you need to update the Bioconductor repository, you will need to contact the
+Bioconductor Core Team to sync your repository with the version on Bioconductor,
+as force pushes which alter the git timeline are not possible for maintainers on
+the Bioconductor git server.
+
 #### Removing Large Files from History with BFG repo cleaner
 
 Another option is to use BFG. The steps below assume `origin` is a user-maintained github
@@ -1466,6 +1488,6 @@ please send an email to <[email protected]>.
 
 [resolve duplicate commits][]
 
-[Pull requests][] 
+[Pull requests][]
 
-[Open github issues][Open github issue] 
+[Open github issues][Open github issue]

index.Rmd

@@ -93,6 +93,7 @@ knitr::write_bib(c(
 [Create a new GitHub repo]: https://help.github.com/articles/create-a-repo/
 [detect duplicate commits]: https://github.com/Bioconductor/bioc_git_transition/blob/master/misc/detect_duplicate_commits.py
 [devel-LongTests-report]: https://bioconductor.org/checkResults/devel/bioc-longtests-LATEST/
+[devel-GPU-report]: https://bioconductor.org/checkResults/devel/bioc-gpu-LATEST/
 [devel-software-build-report]: https://bioconductor.org/checkResults/devel/bioc-LATEST/
 ['devel' version]: #use-devel
 [docker]: https://bioconductor.org/help/docker/
@@ -109,7 +110,7 @@ knitr::write_bib(c(
 [git-and-github-learning-resources]: https://help.github.com/articles/git-and-github-learning-resources/
 [git-scm]: https://git-scm.com/
 [guidelines]: #develop-overview
-[long tests]: #long-tests
+[advanced-build-options]: #advanced-build-options
 [Maintain a _Bioconductor_-only repository]: #maintain-bioc-only
 [Maintain GitHub and _Bioconductor_ repositories]: #maintain-github-bioc
 [Makevars files]: http://cran.r-project.org/doc/manuals/R-exts.html#Using-Makevars
@@ -130,6 +131,7 @@ knitr::write_bib(c(
 [release-schedule]: https://bioconductor.org/developers/release-schedule/
 [release-biocviews]: http://bioconductor.org/packages/release/BiocViews.html
 [release-LongTests-report]: https://bioconductor.org/checkResults/release/bioc-longtests-LATEST/
+[release-GPU-report]: https://bioconductor.org/checkResults/release/bioc-gpu-LATEST/
 [release-software-build-report]: https://bioconductor.org/checkResults/release/bioc-LATEST/
 [Removing collaborator]: https://help.github.com/articles/removing-a-collaborator-from-a-personal-repository/
 [Resolving a merge conflict using command line]: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/