Merge branch 'Bioconductor:devel' into master

Author: lshep

_output.yml

@@ -1,4 +1,6 @@
 bookdown::bs4_book:
+  includes:
+    in_header: "includes/header.html"
   theme:
     primary: "#00758a"
     yellow: "#804600"

description-file.Rmd

@@ -67,10 +67,32 @@ The license field should preferably refer to a standard license (see
 standard specifications. <i class="fab fa-r-project"></i> ships with the
 following [standard licenses][R License]
 
-Be specific about any version that applies (e.g., `GPL-2`).
-Licenses restricting use, e.g., to academic or non-profit researchers, are not
-suitable for [_Bioconductor_][]. Core Bioconductor packages are typically
-licensed under `Artistic-2.0`.
+Be specific about any version that applies (e.g., `GPL-2`). Licenses restricting
+use, e.g., to academic or non-profit researchers, are not suitable for
+[_Bioconductor_][] as they limit accessibility, hinder integration with other
+open-source projects, and create barriers to collaboration and reproducibility.
+Examples of such restrictive licenses include (but are not limited to):
+
+* `CC BY-NC 4.0` (Attribution-NonCommercial 4.0 International)
+* `CC BY-NC-SA 4.0` (Attribution-NonCommercial-ShareAlike 4.0 International)
+* `CC BY-NC-ND 4.0` (Attribution-NonCommercial-NoDerivatives 4.0 International)
+* `ACM` (Association for Computing Machinery)
+
+These licenses restrict commercial use, modifications, or redistribution, making
+them incompatible with Bioconductor's goals of open and broad accessibility.
+
+<p><details>
+<summary> Click to see a list of licenses that restrict use </summary>
+
+```{r}
+license_db_path <- file.path(R.home("share"), "licenses", "license.db")
+license_db <- as.data.frame(read.dcf(license_db_path))
+subset(license_db, Restricts_use == "yes")
+```
+
+</details></p>
+
+Core Bioconductor packages are typically licensed under `Artistic-2.0`.
 
 To specify a non-standard license, include a file named `LICENSE` in your
 package (containing the full terms of your license) and use the string `file
@@ -120,7 +142,7 @@ guidelines:
   field of `GenomicAlignments`.
   It is unusual for more than three packages to be listed as `Depends:`.
 - `Suggests:` is for packages used in vignettes, examples, and in conditional
-  code.Commonly, annotation and experiment packages (e.g., `TxDb*`) used in
+  code. Commonly, annotation and experiment packages (e.g., `TxDb*`) used in
   vignette and example code are included in this field thus avoiding a costly
   download.  In the case where an external one-off function is required for
   package code, the package availability and usage can be done via:
@@ -172,7 +194,7 @@ package type (i.e., `Software`, `AnnotationData`, `ExperimentData`, or
 The field name "biocViews" is case-sensitive and must begin with a lower-case
 'b'. Please use a single line with biocViews seperated by commas
 
-(i.e,`biocViews: GeneTarget, SingleCell`). 
+(i.e,`biocViews: GeneTarget, SingleCell`).
 
 ## `BugReports` {#description-bugreport}
 

documentation.Rmd

@@ -25,21 +25,21 @@ it is always possible to extend existing classes.
 
 A vignette demonstrates how to accomplish non-trivial tasks embodying the core
 functionality of your package. There are two common types of vignettes.
-  
-* (Recommended) An *R markdown* vignette is similar to a *Sweave* vignette, but uses
-  [markdown](http://daringfireball.net/projects/markdown/) instead of $\LaTeX$
-  for structuring text sections and resulting in HTML output. The `r
-  BiocStyle::CRANpkg("knitr")` package can process most *Sweave* and all *R
+
+* (Recommended) An *R markdown* vignette is similar to a *Sweave* vignette, but
+  uses [markdown](http://daringfireball.net/projects/markdown/) instead of
+  $\LaTeX$ for structuring text sections and resulting in HTML output. The
+  `r BiocStyle::CRANpkg("knitr")` package can process most *Sweave* and all *R
   markdown* vignettes, producing pleasing output. Refer to [Writing package
-  vignettes][CRAN vigs] for technical details. See the `r
-  BiocStyle::Biocpkg("BiocStyle")` package for a convenient way to use common
+  vignettes][CRAN vigs] for technical details. See the
+  `r BiocStyle::Biocpkg("BiocStyle")` package for a convenient way to use common
   macros and a standard _Bioconductor_ style vignette.
 
 * A *Sweave* vignette is an `.Rnw` file that contains $\LaTeX$ and chunks of <i
   class="fab fa-r-project"></i> code. The  code chunk starts with a line
   `<<>>=`, and ends with `@`. Each chunk is evaluated during `R CMD build`,
   prior to $\LaTeX$ compilation to a PDF document.
-  
+
 A vignette provides reproducibility: the vignette produces the same results as
 copying the corresponding commands into an <i class="fab fa-r-project"></i>
 session. It is therefore **essential** that the vignette embed executed <i
@@ -103,7 +103,7 @@ Add an "Installation" section that show to users how to download and load the
 package from Bioconductor.
 
 These instructions and any installations instructions should be in an
-`eval=FALSE` code chunk. No where in the code (<i class="fab fa-r-project"></i>
+`eval=FALSE` code chunk. Nowhere in the code (<i class="fab fa-r-project"></i>
 code, man pages, vignettes, Rmd files) should someone try to install or download
 system dependencies, applications, packages, etc. Developers can provide
 instructions to follow in unevaluated code chunks, and should assume all
@@ -173,20 +173,34 @@ If this option is used it will also be preferable to use `donttest` instead of
 `dontrun`; `donttest` requires valid <i class="fab fa-r-project"></i> code while
 `dontrun` does not.
 
-## The `inst/script/` directory {#doc-inst-script}
+## The `inst/scripts/` directory {#doc-inst-scripts}
 
 The scripts in this directory can vary.
 
 Most importantly if data was included in the `inst/extdata/` directory, a
-related script must be present in this directory documenting very clearly how
-the data was generated and source information.
+related script must be present in this directory clearly documenting how the
+data was obtained and prepared.
+
+It should include any source URLs and information regarding filtering or
+pre-processing.
+
+It can be executable code, sudo code, or even a text description.
+
+Users should be able to download and roughly reproduce the data file or object
+in `inst/extdata/`.
+
+## The `data-raw` directory {#doc-data-raw}
 
-It should include source URLs and any key information regarding filtering or processing.
+Although the preferred location is `inst/scripts`, the `data-raw` directory may
+be used instead to store scripts that generated data files or objects. Note
+that one potential disadvantage of using the `data-raw` directory is that the
+scripts are not included in the package installation folder (for users to
+inspect).
 
-It can be executable code, sudo code, or a text description.
+For more details, see the `Data` chapter in Hadley Wickham's
+[R Packages][r-pkgs].
 
-Users should be able to download and be able to roughly reproduce the file or
-object that is present as data.
+[r-pkgs]: https://r-pkgs.org/data.html
 
 ## Other {#other-doc}
 

fortran-C-python.Rmd

@@ -26,9 +26,20 @@ working examples for many tasks: the [Rcpp Gallery][].
 
 ## Python {#python}
 
-The `r BiocStyle::Biocpkg("basilisk")` package is required to integrate python into R packages. While
-[reticulate][] is an alternative, the developer must make a strong argument why
-basilisk is not used.  
+The `r BiocStyle::Biocpkg("basilisk")` package uses `conda` to configure an
+appropriate Python environment on the user's machine. It is strongly
+recommended if the routine operation of a Bioconductor package relies on
+Python, as users should not be asked to manually install Python packages.
+
+The use of [reticulate][] for the R/Python interaction is left to the
+discretion of the developer.
+
+## CMake {#cmake}
+
+The `r BiocStyle::Biocpkg("biocmake")` package guarantees that a certain
+minimal version of CMake is available on the user machine, either by using an
+existing CMake installation or by installing its own from the official website.
+This should be used whenever a package relies on CMake during its build.
 
 ## Other {#third-party-code}
 

git-version-control.Rmd

@@ -510,16 +510,16 @@ repository for the package.
 1. The package with the changes should be available in your local _R_
    installation.
 
-## Scenarios for code update:
-
-- [Pull upstream changes][], e.g., introduced by the core team.
-- [Push to GitHub and _Bioconductor_][] repositories.
-- [Resolve merge conflicts][mergeconflict].
-- [Abandon changes][].
-- [Fix bugs in  devel and release][].
+## Scenarios for code update
+
+- [Pull upstream changes][] (e.g., introduced by the core team)
+- [Push to GitHub and _Bioconductor_][] repositories
+- [Resolve merge conflicts][mergeconflict]
+- [Abandon changes][]
+- [Fix bugs in  devel and release][]
+- [Bug fixes due to API changes][]
 - [Resolve duplicate commits][]
 
-
 ### Pull upstream changes
 
 __Goal:__ Your _Bioconductor_ repository has been updated by the core
@@ -894,6 +894,32 @@ git branch and in the current release branch (e.g., `RELEASE_3_14`).
 
 <iframe width="568" height="315" src="https://www.loom.com/embed/37525f9ddf434c91b11e8112db46818b" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
 
+### Bug fixes due to API changes {#bug-fixes-due-to-api-changes}
+
+Packages that make use of web APIs will need to be updated when there are
+significant API changes. This is a common occurrence with Bioconductor packages
+that use REST APIs, e.g., `UniProt.ws`, `AnVIL`, etc. To provide a smooth
+experience for users, it is important to update the package as soon as possible.
+
+#### Minor API changes
+
+The steps to apply bug fixes due to API changes are similar to the steps for
+fixing bugs in the `devel` and `release` branches. The main difference is that
+the bug may be due to minor API issues, certificate issues, API version issues,
+etc. The maintainer can readily update the R package to adapt to the new API.
+Note that the functionality of the package largely remains the same.
+
+#### Major API changes
+
+It may be possible that an organization's API changes are not backwards
+compatible and that they do not provide the same functionality for the existing
+Bioconductor package to remain functional. In such case, it is recommended to
+contact the organization that maintains the API to get more information about
+the changes and to request a backward compatible API, if possible. When API
+changes do not provide a similar functionality to that of the R package, the
+package maintainer may need to submit a new package that works with the new API
+and to deprecate the old package.
+
 ### Resolve Duplicate Commits
 
 __Goal:__ You want to get rid of the duplicate (or triplicate) commits

important-bioc-features.Rmd

@@ -112,6 +112,8 @@ searching in [biocViews][] for your data type.
   `r BiocStyle::Biocpkg("MultiAssayExperiment")` `::MultiAssayExperiment()`
 + Single cell data --
   `r BiocStyle::Biocpkg("SingleCellExperiment")` `::SingleCellExperiment()`
++ Spatial transcriptomics data --
+  `r BiocStyle::Biocpkg("SpatialExperiment")` `::SpatialExperiment()`
 + Mass spec data -- `r BiocStyle::Biocpkg("Spectra")` `::Spectra()`
 + File formats -- `r BiocStyle::Biocpkg("BiocIO")` `` ::`BiocFile-class` ``
 

includes/header.html

@@ -0,0 +1,8 @@
+<head>
+  <link rel="stylesheet"
+  href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css"
+  integrity="sha512-9usAa10IRO0HhonpyAIVpjrylPvoDwiPUiKdWk5t3PyolY1cOd4DSE0Ga+ri4AuTroPR5aQvXU9xC6qOPnzFeg=="
+  crossorigin="anonymous"
+  referrerpolicy="no-referrer"
+  />
+</head>

non-software-packages.Rmd

@@ -58,7 +58,7 @@ expected the majority of vignette code chunks are evaluated.
 * Write a package with the same name as the workflow. The workflow vignette
  written in Markdown, using the [rmarkdown][] package should be included in the
  vignette directory. You may include more than one vignette but please use
- useful identifying names. 
+ useful identifying names.
 
 * The package does not need man/ or R/ directories nor a data/ directory as
  ideally workflows make use of existing data in a Bioconductor repository or on
@@ -72,7 +72,7 @@ expected the majority of vignette code chunks are evaluated.
 
 * Submit the package to the [GitHub submission tracker][tracker] for a formal
   review. Please also indicate in the tracker issue that this package is a
-  workflow.  
+  workflow.
 
 * Workflows are git version controlled. Once the package is accepted it will be
   added to our git repository at git@git.bioconductor.org and instructions will
@@ -91,13 +91,13 @@ expected the majority of vignette code chunks are evaluated.
 		BiocStyle::html_document
 	```
 
-* The following should also be include
+* The following should also be included
 
       - author affiliations
       - a date representing when the workflow vignette has been modified
 
 * The first section should have some versioning information. The  R version,
-  Bioconductor version, and package version should be visible. 
+  Bioconductor version, and package version should be visible.
   The following is an example of how this could be achieved:
 
 <pre>
@@ -123,14 +123,14 @@ The following is taken as an example header from the variants workflow package:
     <code>
 &ndash; &ndash; &ndash;
 title&#58; Annotating Genomic Variants
-author&#58; 
+author&#58;
 &ndash;name&#58; Valerie Obenchain
   affiliation&#58; Fred Hutchinson Cancer Research Center, 1100 Fairview Ave. N., P.O. Box 19024, Seattle, WA, USA 98109&ndash;1024
 date&#58; 11 April 2018
 vignette&#58; &#62;
   &#37;&#92;VignetteIndexEntry&#123;Annotating Genomic Variants&#125;
   &#37;&#92;VignetteEngine&#123;knitr&#58;&#58;rmarkdown&#125;
-output&#58; 
+output&#58;
     BiocStyle&#58;&#58;html&#95;document
 &ndash; &ndash; &ndash;
 

package-data.Rmd

@@ -83,8 +83,9 @@ another package or the hubs as previously stated.
 
 However, if this is not applicable, raw data files should be included in the
 `inst/extdata` directory. Files of these type are often accessed utilizing
-`system.file()`. _Bioconductor_ requires documentation on these files in an
-`inst/script/` directory. See [data documentation](#doc-inst-script).
+`system.file()`. _Bioconductor_ requires documentation of these files in either
+`inst/scripts/` (preferred) or `data-raw` directory. See
+[inst/scripts](#doc-inst-scripts) and [data-raw](#doc-data-raw) documentation.
 
 ### Internal data
 

package-submission.Rmd

@@ -168,7 +168,7 @@ package maintenance responsibilities. Package authors are expected to:
   DESCRIPTION file. This field indicates a particular web page for submitting
   bug reports and questions.
 
-* Ensure the maintainer email in the DESCRIPTIONS stays accurate and
+* Ensure the maintainer email in the DESCRIPTION stays accurate and
   reachable. The maintainer email in the DESCRIPTION is the definitive contact
   _Bioconductor_ will use. It is important to keep this email up-to-date to
   ensure we can contact you if your package is failing or to notify you of any
@@ -257,7 +257,7 @@ use of existing data in a Bioconductor package. See development section on
 * The moderator will add your package as a repository to the
   git.bioconductor.org git server, copy the SSH keys from your github
   account to the [BiocCredentials application][] application and the issue labelled
-  `pre-review`.  
+  `pre-review`.
 
   ALL CHANGES TO YOUR PACKAGE must be pushed to the
   git.bioconductor.org repository created in this step. See the [New package