chapters/contributing.qmd

# Contributing {.unlisted .unnumbered}

```{r}
#| label: setup
#| include: false

source("../R/_common.R")
```

If you plan to do anything beyond fixing a typo, the best thing you can do is to [open an issue](https://github.com/aml4td/website/issues) and discuss changes before you spend a lot of time doing them. 

If you don't have a lot of experience with git or GitHub, take a look at the wonderful [_Happy Git and GitHub for the useR_](https://happygitwithr.com/). 

If you want to contribute, some general advice is: 

 - Only check in the source files (qmd, yml, bib, pre-made image files, etc). Don't commit the rendered files. 
 - Keep the changes small in scope. If the overall change is larger, make a sequence of small pull requests. 
 - The edits cannot include exact code that is under another license (i.e., don't just copy/paste from R sources, etc.)
 - Respect the existing code formatting/linting (as heterogeneous as it is). 
 - Stick to using R for computations.  
 - Don't update software versions unless you have to. If you need to update or add something, use [renv](https://rstudio.github.io/renv/) (described below) to codify the software requirements.  
 - The [usethis](https://usethis.r-lib.org/) package has excellent tools for creating, updating, and managing pull requests. You should consider utilizing those features. 

A merged PR will make you appear in the contributor list (see below). It will, however, be considered a donation of your work to this project. You are still bound by the conditions of the license, meaning that you are **not considered an author, copyright holder, or owner** of the content once it has been merged in.

You will mostly work with the `*.qmd` files in the `chapters` directory. 

Here is a list of the elements in the repo: 

```
├── DESCRIPTION          # Set package dependencies
├── _cache               # Location of cached chunks  
├── _extensions          # Created by quarto
├── _freeze              # Created by quarto
├── _publish.yml         # Publishing details
├── _quarto.yml          # Most options
├── website.Rproj        # Rstudio IDE file
├── chapters             # qmd content files
├── delimited            # csv versions of the data
├── docs                 # Created by quarto
├── figures              # Location for created image files 
├── includes             # tex, bib, and html files to include
├── index.qmd            # Initial quarto file
├── license.*            # License information
├── premade              # Premade diagrams and other files
├── renv                 # Version control for R packages
├── renv.lock            # Version control for R packages
├── R                    # Ancillary R files
├── RData                # WIP RData results
├── README.*             # Information
└── tests                # testthat files to check some results
```

## Software

Regarding R packages, the repository has a DESCRIPTION file as if it were an R package. This lets us specify precisely what packages and their versions should be installed. The packages listed in the imports field contain packages for modeling/analysis and packages used to make the website/book. 
Some basic system requirements are likely needed to install packages: Fortran, gdal, and others. 

The main requirements are as follows.

### Quarto

Quarto is an open-source scientific and technical publishing system. [Quarto](https://quarto.org/docs/get-started/) version `r system("quarto --version", intern = TRUE)` is used to compile the website. 

We also use a few Quarto extensions. These should be installed from the project's root directory via:

```
quarto add quarto-ext/fontawesome
quarto add quarto-ext/shinylive
quarto add quarto-ext/fancy-text
quarto add leovan/quarto-pseudocode
```

### R and renv

`r R.version.string` is what we are currently using. We suggest using [rig](https://github.com/r-lib/rig) to manage R versions. There are several IDEs that you can use. We've used RStudio (>= 2023.6.1.524). 

The current strategy is to use the [renv](https://rstudio.github.io/renv/) (>= version `r utils::packageVersion("renv")`) package to make this project more isolated, portable and reproducible. 

To get package dependencies installed...

<details>

When you open the `website.Rproj` file, the renv package should be automatically installed/updated (if neded). For example: 

```
# Bootstrapping renv 1.0.3 ---------------------------------------------------
- Downloading renv ... OK
- Installing renv  ... OK

The following package(s) will be installed:
- BiocManager [1.30.22]
These packages will be installed into "~/content/aml4td/renv/library/R-4.3/x86_64-apple-darwin20".
```

if you try to compile the book, you probably get and error: 

```
- One or more packages recorded in the lockfile are not installed.
- Use `renv::status()` for more details.
```

You can get more information using `renv::status()` but you can get them installed by first running `renv::activate()`. As an example: 

```
> renv::activate()

Restarting R session...

- Project '~/content/aml4td' loaded. [renv 1.0.3]
- One or more packages recorded in the lockfile are not installed.
- Use `renv::status()` for more details.
```

Since we have package versions recorded in the lockfile, we can installed them using `renv::restore()`. Here is an example of that output: 

```
> renv::restore() 
The following package(s) will be updated:

# Bioconductor ---------------------------------------------------------------
- mixOmics         [* -> mixOmicsTeam/mixOmics]

# CRAN -----------------------------------------------------------------------
- BiocManager      [1.30.22 -> 1.30.21.1]
- lattice          [0.21-9 -> 0.21-8]
- Matrix           [1.6-1.1 -> 1.6-0]
- nlme             [3.1-163 -> 3.1-162]
- rpart            [4.1.21 -> 4.1.19]
- survival         [3.5-7 -> 3.5-5]
- abind            [* -> 1.4-5]

<snip>

- zip              [* -> 2.2.0]
- zoo              [* -> 1.8-12]

# GitHub ---------------------------------------------------------------------
- BiocParallel     [* -> Bioconductor/BiocParallel@devel]
- BiocVersion      [* -> Bioconductor/BiocVersion@devel]
- modeldatatoo     [* -> tidymodels/modeldatatoo@HEAD]
- parsnip          [* -> tidymodels/parsnip@HEAD]
- usethis          [* -> r-lib/usethis@HEAD]

# RSPM -----------------------------------------------------------------------
- bslib            [* -> 0.5.1]
- fansi            [* -> 1.0.5]
- fontawesome      [* -> 0.5.2]
- ggplot2          [* -> 3.4.4]
- htmltools        [* -> 0.5.6.1]
- withr            [* -> 2.5.1]

Do you want to proceed? [Y/n]: y

# Downloading packages -------------------------------------------------------
- Downloading BiocManager from CRAN ...         OK [569 Kb in 0.19s]
- Downloading nlme from CRAN ...                OK [828.7 Kb in 0.19s]
- Downloading BH from CRAN ...                  OK [12.7 Mb in 0.4s]
- Downloading BiocVersion from GitHub ...       OK [826 bytes in 0.37s]

<snip>

```

Depending on whether you have to install packages from source, you may need to install some system dependencies and try again (I had to install `libgit2` the last time I did this). 

Once you have everything installed, we recommend installing the underlying torch computational libraries. You can do this by loading the torch package A download will automatically begin if you need one. 

</details>


## Contributor List

```{r}
#| label: contrib-list
#| include: false
use_tidy_contrib <- function (repo_spec = NULL, from = NULL, to = NULL) {
  require("usethis")
  require("rlang")
  repo_spec <- repo_spec %||% usethis:::target_repo_spec()
  parsed_repo_spec <- usethis:::parse_repo_url(repo_spec)
  repo_spec <- parsed_repo_spec$repo_spec
  if (!is.null(parsed_repo_spec$host)) {
    withr::local_envvar(c(GITHUB_API_URL = parsed_repo_spec$host))
  }
  if (is.null(to)) {
    to <- as.character(Sys.Date())
  }
  from_timestamp <- usethis:::as_timestamp(repo_spec, x = from) %||%
    "2008-01-01"
  to_timestamp <- usethis:::as_timestamp(repo_spec, x = to)
  res <-
    gh::gh(
      "/repos/{owner}/{repo}/issues",
      owner = usethis:::spec_owner(repo_spec),
      repo = usethis:::spec_repo(repo_spec),
      since = from_timestamp,
      state = "all",
      filter = "all",
      .limit = Inf
    )
  creation_time <- function(x) {
    as.POSIXct(purrr::map_chr(x, "created_at"))
  }
  res <- res[creation_time(res) >= as.POSIXct(from_timestamp)]
  if (!is.null(to_timestamp)) {
    res <- res[creation_time(res) <= as.POSIXct(to_timestamp)]
  }
  contributors <- sort(unique(purrr::map_chr(res, c("user", "login"))))
  
  contributors <- contributors[!(contributors %in% c("topepo", "kjell-stattenacity"))]
  
  contrib_link <- glue::glue("[&#x0040;{contributors}](https://github.com/{contributors})")
  contrib_markup <- glue::glue_collapse(contrib_link, sep = ", ", last = ", and ") +
    glue::glue(".")
  contrib_markup
}

contribs <- try(use_tidy_contrib(), silent = TRUE)
if (inherits(contribs, "try-error")) {
  contribs <- "[&#x0040;amy-palmer](https://github.com/amy-palmer), [&#x0040;bmreiniger](https://github.com/bmreiniger), [&#x0040;coatless](https://github.com/coatless), [&#x0040;krz](https://github.com/krz), [&#x0040;syclik](https://github.com/syclik), and [&#x0040;tomsing1](https://github.com/tomsing1)."
}
```

The would like to thank those who have made a contribution to the project: `r contribs`