Contributing

Overview

RStudio Project: This section explains how to use RStudio Project to work on this project.

Quarto: This section explains how to use Quarto to work on this project.

Dependency Management: This section explains how this project manages package dependencies using renv.

Code: This section explains how to add code snippets.

Images: This section e explains how to add images.

References: This section explains how to add references.

Variables: This section explains how to use variables.

Fontawesome Icons: This section explains how to add icons.

RStudio Project

We recommend working in RStudio and open the RStudio Project.

  • Double-click on the project file version-control-book.Rproj within your computer’s file system (for example, macOS Finder).

In the Terminal, run:

open version-control-book.Rproj

This will open the RStudio Project in RStudio.

Click here to view the full version-control-book.Rproj file of this project. 
version-control-book.Rproj
Version: 1.0

RestoreWorkspace: No
SaveWorkspace: No
AlwaysSaveHistory: No

EnableCodeIndexing: Yes
UseSpacesForTab: Yes
NumSpacesForTab: 2
Encoding: UTF-8

RnwWeave: Sweave
LaTeX: pdfLaTeX

BuildType: Makefile

Quarto

This book is made with Quarto.

Local development

Setup

  1. Read the Get Started chapter of the Quarto documentation, which includes details on installation.

Preparation

  1. Read this guide on how to contribute.
  2. Familiarize yourself with Quarto Books.

Local preview

quarto preview

Add a new chapter

  1. Create a new Quarto document inside the /chapters/ folder
  2. Add the new chapter to _quarto.yml. Don’t forget to specify the full path (including /chapters/)
_quarto.yml (excerpt)
chapters:
  - index.qmd
1  - chapters/YOUR-NEW-CHAPTER.qmd
  - another-chapter.qmd
1
Replace YOUR-NEW-CHAPTER with a concise filename.
Click here to view the full _quarto.yml file of this project. 
_quarto.yml
project:
  # project options (https://quarto.org/docs/reference/projects/options.html):
  type: book
  output-dir: _book
  execute-dir: project
  # pre-render: make download-images
  # preview (https://quarto.org/docs/reference/projects/options.html#preview):
  preview: 
    port: 3333
    host: 127.0.0.1
    browser: true
    watch-inputs: true
    navigate: true

book:
  title: "The Version Control Book"
  subtitle: "Track, organize and share your work: An introduction to Git for research"
  date: today
  doi: 10.25592/uhhfdm.14148
  search: true
  repo-url: https://github.com/lnnrtwttkhn/version-control-book/
  repo-branch: main
  repo-actions: [edit, issue, source]
  # downloads: [pdf, epub]
  favicon: static/logo.svg
  twitter-card: false
  site-url: https://lennartwittkuhn.com/version-control-book
  chapters:
    - index.qmd
    - contents.qmd
    - misc/objectives.qmd
    - chapters/intro-version-control.qmd
    - chapters/command-line.qmd
    - chapters/installation.qmd
    - chapters/setup.qmd
    - chapters/first-steps-git.qmd
    - chapters/git-essentials.qmd
    - chapters/branches.qmd
    - chapters/remotes-intro.qmd
    - chapters/github-advanced.qmd
    - chapters/tags-and-releases.qmd
    # - chapters/project-management.qmd
    - chapters/issues.qmd
    - chapters/gui.qmd
    - chapters/rewriting-history.qmd
    - misc/exercises.qmd
    - misc/cheatsheet.qmd
    - misc/courses.qmd
    - misc/references.qmd
    - misc/acknowledgements.qmd
    - misc/contributing.qmd
  page-navigation: true
  back-to-top-navigation: true
  # side navigation (https://quarto.org/docs/websites/website-navigation.html#side-navigation):
  sidebar:
    id: sidebar
    title: "{{< var project.title >}}"
    logo: static/logo.svg
    search: true
    tools:
      - icon: globe
        href: https://lennartwittkuhn.com/version-control-book
      - icon: bug
        href: https://github.com/lnnrtwttkhn/version-control-book/issues
    style: floating
    type: light
    border: false
    alignment: center
    collapse-level: 2
    pinned: true
  page-footer:
    left: |
      &copy; {{< var project.duration >}} [The {{< var project.title >}} Team]({{< var project.contributors >}})
    center:
      - text: "Acknowledgements"
        href: misc/acknowledgements.qmd
    right: |
      License: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
    border: false
    background: light

format:
  html:
    theme: [default, custom.scss]
    monofont: Fira Mono
    from: markdown+emoji
    link-external-newwindow: true
    toc: true
    toc-depth: 3
    toc-title: "Contents"
    number-sections: true
    anchor-sections: true
    # layout (https://quarto.org/docs/reference/formats/html.html#layout):
    fig-cap-location: bottom
    page-layout: full
    title-block-style: default
    # code (https://quarto.org/docs/reference/formats/html.html#code):
    code-fold: false
    code-overflow: wrap
    code-line-numbers: false
    code-copy: true
    code-link: false
    code-annotations: below
    code-tools: false
    highlight-style: monokai
    # references:
    bibliography: references.bib
    csl: chicago-author-date-note.csl
    citations-hover: true
    citation-location: document
    citeproc: true
    # footnotes:
    footnotes-hover: true
    # includes:
    include-after-body: plausible.html
    include-in-header: github-buttons.html
    published-title: "Last updated"

metadata-files:
  - _metadata.yml

Dependency Management

We use renv for project-local dependency management. For details on renv, see the renv documentation.

Using renv for the first time

After you open the Rstudio Project, you will (hopefully) see a similar output in the RStudio console:

# Bootstrapping renv 0.17.3 --------------------------------------------------
* Downloading renv 0.17.3 ... OK (downloaded binary)
* Installing renv 0.17.3 ... Done!
* Successfully installed and loaded renv 0.17.3.
* Project '~/version-control-book' loaded. [renv 0.17.3]
* This project contains a lockfile, but none of the recorded packages are installed.
* Use `renv::restore()` to restore the project library.

This output tells you that (1) renv was automatically installed and loaded, (2) the renv environment for the project was loaded, and (3) that none of packages recorded in the renv lockfile are installed.

The renv lockfile captures the state of the package library of the project at some point in time. It is defining the version of renv used when generating the lockfile, the version of used in that project, the R repositories that were active when the lockfile was created and the package records defining each package, their version, and their installation source. For details on the anatomy of renv.lock, see this section in the renv documentation.

Click here to view the full renv.lock file of this project. 
renv.lock
{
  "R": {
    "Version": "4.4.1",
    "Repositories": [
      {
        "Name": "CRAN",
        "URL": "https://cran.rstudio.com"
      }
    ]
  },
  "Packages": {
    "R6": {
      "Package": "R6",
      "Version": "2.5.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R"
      ],
      "Hash": "470851b6d5d0ac559e9d01bb352b4021"
    },
    "Rcpp": {
      "Package": "Rcpp",
      "Version": "1.0.13",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "methods",
        "utils"
      ],
      "Hash": "f27411eb6d9c3dada5edd444b8416675"
    },
    "askpass": {
      "Package": "askpass",
      "Version": "1.2.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "sys"
      ],
      "Hash": "c39f4155b3ceb1a9a2799d700fbd4b6a"
    },
    "base64enc": {
      "Package": "base64enc",
      "Version": "0.1-3",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R"
      ],
      "Hash": "543776ae6848fde2f48ff3816d0628bc"
    },
    "bib2df": {
      "Package": "bib2df",
      "Version": "1.1.2.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "dplyr",
        "httr",
        "humaniformat",
        "stringr"
      ],
      "Hash": "f73a15a851cb13310bd6765c0ec97b60"
    },
    "bslib": {
      "Package": "bslib",
      "Version": "0.8.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "base64enc",
        "cachem",
        "fastmap",
        "grDevices",
        "htmltools",
        "jquerylib",
        "jsonlite",
        "lifecycle",
        "memoise",
        "mime",
        "rlang",
        "sass"
      ],
      "Hash": "b299c6741ca9746fb227debcb0f9fb6c"
    },
    "cachem": {
      "Package": "cachem",
      "Version": "1.1.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "fastmap",
        "rlang"
      ],
      "Hash": "cd9a672193789068eb5a2aad65a0dedf"
    },
    "cli": {
      "Package": "cli",
      "Version": "3.6.3",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "utils"
      ],
      "Hash": "b21916dd77a27642b447374a5d30ecf3"
    },
    "cpp11": {
      "Package": "cpp11",
      "Version": "0.5.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R"
      ],
      "Hash": "91570bba75d0c9d3f1040c835cee8fba"
    },
    "curl": {
      "Package": "curl",
      "Version": "5.2.3",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R"
      ],
      "Hash": "d91263322a58af798f6cf3b13fd56dde"
    },
    "data.table": {
      "Package": "data.table",
      "Version": "1.16.2",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "methods"
      ],
      "Hash": "2e00b378fc3be69c865120d9f313039a"
    },
    "digest": {
      "Package": "digest",
      "Version": "0.6.37",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "utils"
      ],
      "Hash": "33698c4b3127fc9f506654607fb73676"
    },
    "dplyr": {
      "Package": "dplyr",
      "Version": "1.1.4",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "R6",
        "cli",
        "generics",
        "glue",
        "lifecycle",
        "magrittr",
        "methods",
        "pillar",
        "rlang",
        "tibble",
        "tidyselect",
        "utils",
        "vctrs"
      ],
      "Hash": "fedd9d00c2944ff00a0e2696ccf048ec"
    },
    "evaluate": {
      "Package": "evaluate",
      "Version": "1.0.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R"
      ],
      "Hash": "3fd29944b231036ad67c3edb32e02201"
    },
    "fansi": {
      "Package": "fansi",
      "Version": "1.0.6",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "grDevices",
        "utils"
      ],
      "Hash": "962174cf2aeb5b9eea581522286a911f"
    },
    "fastmap": {
      "Package": "fastmap",
      "Version": "1.2.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Hash": "aa5e1cd11c2d15497494c5292d7ffcc8"
    },
    "fontawesome": {
      "Package": "fontawesome",
      "Version": "0.5.2",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "htmltools",
        "rlang"
      ],
      "Hash": "c2efdd5f0bcd1ea861c2d4e2a883a67d"
    },
    "fs": {
      "Package": "fs",
      "Version": "1.6.4",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "methods"
      ],
      "Hash": "15aeb8c27f5ea5161f9f6a641fafd93a"
    },
    "generics": {
      "Package": "generics",
      "Version": "0.1.3",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "methods"
      ],
      "Hash": "15e9634c0fcd294799e9b2e929ed1b86"
    },
    "glue": {
      "Package": "glue",
      "Version": "1.8.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "methods"
      ],
      "Hash": "5899f1eaa825580172bb56c08266f37c"
    },
    "here": {
      "Package": "here",
      "Version": "1.0.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "rprojroot"
      ],
      "Hash": "24b224366f9c2e7534d2344d10d59211"
    },
    "highr": {
      "Package": "highr",
      "Version": "0.11",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "xfun"
      ],
      "Hash": "d65ba49117ca223614f71b60d85b8ab7"
    },
    "htmltools": {
      "Package": "htmltools",
      "Version": "0.5.8.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "base64enc",
        "digest",
        "fastmap",
        "grDevices",
        "rlang",
        "utils"
      ],
      "Hash": "81d371a9cc60640e74e4ab6ac46dcedc"
    },
    "httr": {
      "Package": "httr",
      "Version": "1.4.7",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "R6",
        "curl",
        "jsonlite",
        "mime",
        "openssl"
      ],
      "Hash": "ac107251d9d9fd72f0ca8049988f1d7f"
    },
    "humaniformat": {
      "Package": "humaniformat",
      "Version": "0.6.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "Rcpp",
        "methods"
      ],
      "Hash": "d521cf9db39ca79250a00029661fb7cd"
    },
    "jquerylib": {
      "Package": "jquerylib",
      "Version": "0.1.4",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "htmltools"
      ],
      "Hash": "5aab57a3bd297eee1c1d862735972182"
    },
    "jsonlite": {
      "Package": "jsonlite",
      "Version": "1.8.9",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "methods"
      ],
      "Hash": "4e993b65c2c3ffbffce7bb3e2c6f832b"
    },
    "knitr": {
      "Package": "knitr",
      "Version": "1.48",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "evaluate",
        "highr",
        "methods",
        "tools",
        "xfun",
        "yaml"
      ],
      "Hash": "acf380f300c721da9fde7df115a5f86f"
    },
    "lifecycle": {
      "Package": "lifecycle",
      "Version": "1.0.4",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "cli",
        "glue",
        "rlang"
      ],
      "Hash": "b8552d117e1b808b09a832f589b79035"
    },
    "magrittr": {
      "Package": "magrittr",
      "Version": "2.0.3",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R"
      ],
      "Hash": "7ce2733a9826b3aeb1775d56fd305472"
    },
    "memoise": {
      "Package": "memoise",
      "Version": "2.0.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "cachem",
        "rlang"
      ],
      "Hash": "e2817ccf4a065c5d9d7f2cfbe7c1d78c"
    },
    "mime": {
      "Package": "mime",
      "Version": "0.12",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "tools"
      ],
      "Hash": "18e9c28c1d3ca1560ce30658b22ce104"
    },
    "openssl": {
      "Package": "openssl",
      "Version": "2.2.2",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "askpass"
      ],
      "Hash": "d413e0fef796c9401a4419485f709ca1"
    },
    "pillar": {
      "Package": "pillar",
      "Version": "1.9.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "cli",
        "fansi",
        "glue",
        "lifecycle",
        "rlang",
        "utf8",
        "utils",
        "vctrs"
      ],
      "Hash": "15da5a8412f317beeee6175fbc76f4bb"
    },
    "pkgconfig": {
      "Package": "pkgconfig",
      "Version": "2.0.3",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "utils"
      ],
      "Hash": "01f28d4278f15c76cddbea05899c5d6f"
    },
    "purrr": {
      "Package": "purrr",
      "Version": "1.0.2",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "cli",
        "lifecycle",
        "magrittr",
        "rlang",
        "vctrs"
      ],
      "Hash": "1cba04a4e9414bdefc9dcaa99649a8dc"
    },
    "rappdirs": {
      "Package": "rappdirs",
      "Version": "0.3.3",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R"
      ],
      "Hash": "5e3c5dc0b071b21fa128676560dbe94d"
    },
    "renv": {
      "Package": "renv",
      "Version": "1.0.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "utils"
      ],
      "Hash": "c321cd99d56443dbffd1c9e673c0c1a2"
    },
    "rlang": {
      "Package": "rlang",
      "Version": "1.1.4",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "utils"
      ],
      "Hash": "3eec01f8b1dee337674b2e34ab1f9bc1"
    },
    "rmarkdown": {
      "Package": "rmarkdown",
      "Version": "2.28",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "bslib",
        "evaluate",
        "fontawesome",
        "htmltools",
        "jquerylib",
        "jsonlite",
        "knitr",
        "methods",
        "tinytex",
        "tools",
        "utils",
        "xfun",
        "yaml"
      ],
      "Hash": "062470668513dcda416927085ee9bdc7"
    },
    "rprojroot": {
      "Package": "rprojroot",
      "Version": "2.0.4",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R"
      ],
      "Hash": "4c8415e0ec1e29f3f4f6fc108bef0144"
    },
    "sass": {
      "Package": "sass",
      "Version": "0.4.9",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R6",
        "fs",
        "htmltools",
        "rappdirs",
        "rlang"
      ],
      "Hash": "d53dbfddf695303ea4ad66f86e99b95d"
    },
    "stringi": {
      "Package": "stringi",
      "Version": "1.8.4",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "stats",
        "tools",
        "utils"
      ],
      "Hash": "39e1144fd75428983dc3f63aa53dfa91"
    },
    "stringr": {
      "Package": "stringr",
      "Version": "1.5.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "cli",
        "glue",
        "lifecycle",
        "magrittr",
        "rlang",
        "stringi",
        "vctrs"
      ],
      "Hash": "960e2ae9e09656611e0b8214ad543207"
    },
    "sys": {
      "Package": "sys",
      "Version": "3.4.3",
      "Source": "Repository",
      "Repository": "CRAN",
      "Hash": "de342ebfebdbf40477d0758d05426646"
    },
    "tibble": {
      "Package": "tibble",
      "Version": "3.2.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "fansi",
        "lifecycle",
        "magrittr",
        "methods",
        "pillar",
        "pkgconfig",
        "rlang",
        "utils",
        "vctrs"
      ],
      "Hash": "a84e2cc86d07289b3b6f5069df7a004c"
    },
    "tidyr": {
      "Package": "tidyr",
      "Version": "1.3.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "cli",
        "cpp11",
        "dplyr",
        "glue",
        "lifecycle",
        "magrittr",
        "purrr",
        "rlang",
        "stringr",
        "tibble",
        "tidyselect",
        "utils",
        "vctrs"
      ],
      "Hash": "915fb7ce036c22a6a33b5a8adb712eb1"
    },
    "tidyselect": {
      "Package": "tidyselect",
      "Version": "1.2.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "cli",
        "glue",
        "lifecycle",
        "rlang",
        "vctrs",
        "withr"
      ],
      "Hash": "829f27b9c4919c16b593794a6344d6c0"
    },
    "tinytex": {
      "Package": "tinytex",
      "Version": "0.53",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "xfun"
      ],
      "Hash": "9db859e8aabbb474293dde3097839420"
    },
    "utf8": {
      "Package": "utf8",
      "Version": "1.2.4",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R"
      ],
      "Hash": "62b65c52671e6665f803ff02954446e9"
    },
    "vctrs": {
      "Package": "vctrs",
      "Version": "0.6.5",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "cli",
        "glue",
        "lifecycle",
        "rlang"
      ],
      "Hash": "c03fa420630029418f7e6da3667aac4a"
    },
    "withr": {
      "Package": "withr",
      "Version": "3.0.1",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "grDevices",
        "graphics"
      ],
      "Hash": "07909200e8bbe90426fbfeb73e1e27aa"
    },
    "xfun": {
      "Package": "xfun",
      "Version": "0.48",
      "Source": "Repository",
      "Repository": "CRAN",
      "Requirements": [
        "R",
        "grDevices",
        "stats",
        "tools"
      ],
      "Hash": "89e455b87c84e227eb7f60a1b4e5fe1f"
    },
    "yaml": {
      "Package": "yaml",
      "Version": "2.3.10",
      "Source": "Repository",
      "Repository": "RSPM",
      "Hash": "51dab85c6c98e50a18d7551e9d49f76c"
    }
  }
}

Restoring renv

If renv is activated but it recognized that (not all of) the packages listed in the renv.lock file are installed, renv will suggest to restore the project library using renv::restore():

* This project contains a lockfile, but none of the recorded packages are installed.
* Use `renv::restore()` to restore the project library.
renv::restore()

This will generate a list of files that will be updated.

Click here to view an example output of the renv::restore() command. 
The following package(s) will be updated:

# CRAN ===============================
- R6            [* -> 2.5.1]
- base64enc     [* -> 0.1-3]
- bslib         [* -> 0.5.0]
- cachem        [* -> 1.0.8]
- cli           [* -> 3.6.1]
- data.table    [* -> 1.14.8]
- digest        [* -> 0.6.31]
- ellipsis      [* -> 0.3.2]
- evaluate      [* -> 0.21]
- fastmap       [* -> 1.1.1]
- fontawesome   [* -> 0.5.1]
- fs            [* -> 1.6.2]
- glue          [* -> 1.6.2]
- here          [* -> 1.0.1]
- highr         [* -> 0.10]
- htmltools     [* -> 0.5.5]
- jquerylib     [* -> 0.1.4]
- jsonlite      [* -> 1.8.5]
- knitr         [* -> 1.43]
- lifecycle     [* -> 1.0.3]
- magrittr      [* -> 2.0.3]
- memoise       [* -> 2.0.1]
- mime          [* -> 0.12]
- rappdirs      [* -> 0.3.3]
- rlang         [* -> 1.1.1]
- rmarkdown     [* -> 2.22]
- rprojroot     [* -> 2.0.3]
- sass          [* -> 0.4.6]
- stringi       [* -> 1.7.12]
- stringr       [* -> 1.5.0]
- tinytex       [* -> 0.45]
- vctrs         [* -> 0.6.3]
- xfun          [* -> 0.39]
- yaml          [* -> 2.3.7]

Do you want to proceed? [y/N]:

If you want to proceed with the update, type y and hit enter.

Adding / removing packages

Install packages:

1install.packages("PACKAGE_NAME")
2renv::install("PACKAGE_NAME")
1
Replace PACKAGE_NAME with the actual name of the package that you want to install.
2
Replace PACKAGE_NAME with the actual name of the package that you want to install.

Remove packages:

1remove.packages("PACKAGE_NAME")
2renv::remove("PACKAGE_NAME")
1
Replace PACKAGE_NAME with the actual name of the package that you want to remove.
2
Replace PACKAGE_NAME with the actual name of the package that you want to remove.

Call renv::snapshot() to save the new state of the project library to the renv.lock:

renv::snapshot()

Commit your changes

The renv.lock is checked into version control, so after you updated it, make a new commit:

git add renv.lock
1git commit -m "add package PACKAGE_NAME to renv"
1
Replace PACKAGE_NAME with the actual name of the package that you installed. Adapt the commit message as needed.

References

Cite a reference

References are stored in references.bib.

Click here to view the full references.bib file of this project. 
references.bib
@book{community2022,
    title = {The Turing Way: A handbook for reproducible, ethical and collaborative research},
    author = {{The Turing Way Community}},
    year = {2022},
    month = {07},
    date = {2022-07-27},
    publisher = {Zenodo},
    doi = {10.5281/zenodo.3233853},
    url = {https://zenodo.org/record/3233853},
    note = {License: \href{https://creativecommons.org/licenses/by/4.0/}{CC BY 4.0}. Source: \url{https://github.com/the-turing-way/the-turing-way}. Website: \url{https://the-turing-way.netlify.app/}}
}

@book{chacon2014,
    title = {Pro Git},
    author = {Chacon, Scott and Straub, Ben},
    year = {2014},
    date = {2014},
    publisher = {Apress},
    doi = {10.1007/978-1-4842-0076-6},
    url = {http://dx.doi.org/10.1007/978-1-4842-0076-6},
    note = {License: \href{https://creativecommons.org/licenses/by-nc/4.0/}{CC BY-NC}. Source: \url{https://github.com/progit/progit2}. Website: \url{https://git-scm.com/book/en/v2}}
}

@software{allaire2022,
    title = {Quarto},
    author = {Allaire, J.J. and Teague, Charles and Xie, Yihui and Dervieux, Christophe},
    year = {2022},
    month = {01},
    date = {2022-01-10},
    doi = {10.5281/zenodo.5960048},
    url = {https://github.com/quarto-dev/quarto-cli},
    version = {1.2},
    note = {License: \href{https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html}{GNU GPL v2}. \url{https://github.com/quarto-dev/quarto-web}. Website: \url{https://quarto.org/}}
}

@article{millman2018,
    title = {Teaching Computational Reproducibility for Neuroimaging},
    author = {Millman, K. Jarrod and Brett, Matthew and Barnowski, Ross and Poline, Jean-Baptiste},
    year = {2018},
    month = {10},
    date = {2018-10-22},
    journal = {Frontiers in Neuroscience},
    volume = {12},
    doi = {10.3389/fnins.2018.00727},
    url = {https://dx.doi.org/10.3389/fnins.2018.00727},
    note = {License: \href{https://creativecommons.org/licenses/by/4.0/}{CC BY 4.0}. Website: \url{http://dx.doi.org/10.3389/fnins.2018.00727}}
}

@article{milligan2014,
    title = {Introduction to the Bash Command Line},
    author = {Milligan, Ian and Baker, James},
    editor = {Crymble, Adam},
    year = {2014},
    month = {09},
    date = {2014-09-20},
    journal = {Programming Historian},
    number = {3},
    doi = {10.46430/phen0037},
    url = {https://dx.doi.org/10.46430/phen0037},
    langid = {en}
}

@misc{mcbain2019,
  author = {McBain, Miles},
  title = {Git for Scientists},
  year = {2019},
  url = {https://milesmcbain.github.io/git_4_sci/},
  note = {License: \href{http://creativecommons.org/licenses/by-sa/4.0/}{CC BY-SA 4.0}. Source: \url{https://github.com/MilesMcBain/git_4_sci/}. Website: \url{https://milesmcbain.github.io/git_4_sci/}}
}


@book{capes2023,
    title = {swcarpentry/shell-novice: Software Carpentry: the UNIX shell},
    author = {Capes, Gerard and {Bkmgit} and Deppen, Jacob and Devenyi, G. A. and Ball, Alexander James and Fowler-Wright, Piper and Visconti, Alessia and Dusenberry, Jeff and Vera, Jessica and Harrison, Randal Sean and Bilke, Andreas and Welch, Jessica Nicole and Thorp, Kelly and Hernandez, Alfredo and {Ashkan Mirzaee} and Winjum, Benjamin and Daley, Chris and Wright, Clay and {Colinmorris} and George, Dave and {Ephantus2017} and Myklebust, Erik and {Löffler}, Frank and {HariEpuri} and Wolff, Holger and {Kairsten Fay} and Reyes, Luna Luisa Sanchez and Politze, Marius and Belkin, Maxim and Porter, Nathaniel and {, Nkicg6} and Ziegner, Norman and Stevens, Sarah LR and McCartney, Sean and Njambi, Serah and {Ramisetti} and Borrego, Stacey and Brown, Andrew Christopher and Cryan, Ashley and {Mehrdadbn9} and {Md Intekhabul Hafiz} and {Niketagrawal} and Benson, Noah and McDivitt, Aaron and Budd, Aidan and Stahlke, Amanda and {Andra{\v{s}} T{\v{s}}it{\v{s}}kan} and Stewart, Andrew and Smith, Becky and Martlin, Catherine and {Knüpfer}, Christian and McKain, David and Wilby, David and Salmanidou, Dimitra and Turner, Dave and Scriven, Edan and Wallace, Edward and McAulay, Elizabeth and Roesch, Etienne and Solinsky, Frank and Lipari, Giordano and Starling, Hamish and Barrass, Iain and {Isil Poyraz Bilgin} and {JSheffield159} and Acris, James and Bradley, Jonathan and Juvonen, Matti and Napier, Kathryn and Ross, Kenton and Ernst, Kevin and Trombach, Lukas and Chorley, Martin and {, Melissa} and Lake, Mike and Renfro, Mike and Renfro, Mike and {NJ} and {, Natali} and McKinlay, Nathan and Soranzo, Nicola and {Rodríguez-Sánchez}, Pablo and Wiringa, Peter and Viktorin, Petr and Rigby, Richard and {, Rkm} and Elliott, Ryan S. and {Lelièvre}, Samuel and Lacalle, Santiago and Kumar, Sujai and Liang, Tong and Gatua, Winfred and Sun, Yi and {Cgmerrick} and {Daking4} and Patel, Deep and {Erich333} and {Karl-Holten} and {Kathymd} and {Laporpe} and {Naveendangeti} and {Nbehrnd} and {, Sophie} and {Tbert} and Couch, Tom and Shrestha, Ram Krishna and {Zzhang60} and {{"}Eli}},
    year = {2023},
    month = {05},
    date = {2023-05-02},
    publisher = {Zenodo},
    doi = {10.5281/ZENODO.595899},
    url = {https://zenodo.org/record/595899},
    note = {License: \href{https://creativecommons.org/licenses/by/4.0/}{CC BY 4.0}. Source: \url{https://github.com/swcarpentry/shell-novice}. Website: \url{https://swcarpentry.github.io/shell-novice/}}
}

@book{koziar2023,
    title = {swcarpentry/git-novice: Software Carpentry: Version Control with Git 2023-05},
    author = {Koziar, Katherine E. and {Madicken Munk} and Greene, Andrew and Rasel, Annajiat Alim and Bennett, Ed and Stevens, Sarah LR and Turnator, Ece and {Gorroño}, Jon Haitz Legarreta and Leinweber, Katrin and Nederbragt, Lex and {Lelièvre}, Samuel and {Vyas Ramasubramani} and Gitter, Anthony and Cassol, Daniela and Zhu, Judy and Soranzo, Nicola and Hejazi, Nima S and Deconinck, Wouter and {Laurentheirendt} and Clarke, Alison and Bressan, Camilla and Guan, Charles and Urizar, Cristina and Horsfall, Dave and {, David} and {, Deborah} and Lowther, Ed and {Fwoerister} and Bissey, {François} and {HaoZeke} and Kent, James and Holmes, Jessica and Huddleston, John and Lehtonen, Juho and Word, Karen and Lieret, Kilian and Modenese, Luca and Foscato, Marco and {Bjørnstad}, Marius and Matney, Mark and Juvonen, Matti and Belkin, Maxim and {Mingrui Yang} and Silantyeva, Olga and McCann, Patrick and Lanfear, Riley and Bartholomew, Sadie L. and Cox, Sam and Gruber, Scott and Jamieson, Stewart Christopher and Arabas, Sylwester and Russell, Tom and Koskela, Tuomas and {, Will} and Wolff, Benjamin and {, Catherinef37} and {Huijun ZHU} and {Kerimoff}},
    year = {2023},
    month = {05},
    date = {2023-05-08},
    publisher = {Zenodo},
    doi = {10.5281/ZENODO.7908089},
    url = {https://zenodo.org/record/7908089},
    note = {License: \href{https://creativecommons.org/licenses/by/4.0/}{CC BY 4.0}. Source: \url{https://github.com/swcarpentry/git-novice}. Website: \url{https://swcarpentry.github.io/git-novice/}.}
}

@article{bryan2018,
    title = {Excuse Me, Do You Have a Moment to Talk About Version Control?},
    author = {Bryan, Jennifer},
    year = {2018},
    month = {01},
    date = {2018-01-02},
    journal = {The American Statistician},
    pages = {20--27},
    volume = {72},
    number = {1},
    doi = {10.1080/00031305.2017.1399928},
    url = {http://dx.doi.org/10.1080/00031305.2017.1399928},
    langid = {en},
    note = {Website: \url{https://doi.org/10.1080/00031305.2017.1399928}.}
}

@article{ram2013,
    title = {Git can facilitate greater reproducibility and increased transparency in science},
    author = {Ram, Karthik},
    year = {2013},
    month = {02},
    date = {2013-02-28},
    journal = {Source Code for Biology and Medicine},
    volume = {8},
    number = {1},
    doi = {10.1186/1751-0473-8-7},
    url = {http://dx.doi.org/10.1186/1751-0473-8-7},
    langid = {en},
    note = {License: \href{https://creativecommons.org/licenses/by/2.0/}{CC BY 2.0}. Source: \url{https://github.com/karthik/smb_git}. Website: \url{https://doi.org/10.1186/1751-0473-8-7}}
}

@article{perez-riverol2016,
    title = {Ten Simple Rules for Taking Advantage of Git and GitHub},
    author = {Perez-Riverol, Yasset and Gatto, Laurent and Wang, Rui and Sachsenberg, Timo and Uszkoreit, Julian and Leprevost, Felipe da Veiga and Fufezan, Christian and Ternent, Tobias and Eglen, Stephen J. and Katz, Daniel S. and Pollard, Tom J. and Konovalov, Alexander and Flight, Robert M. and Blin, Kai and {Vizcaíno}, Juan Antonio},
    editor = {Markel, Scott},
    year = {2016},
    month = {07},
    date = {2016-07-14},
    journal = {PLOS Computational Biology},
    pages = {e1004947},
    volume = {12},
    number = {7},
    doi = {10.1371/journal.pcbi.1004947},
    url = {http://dx.doi.org/10.1371/journal.pcbi.1004947},
    langid = {en},
    note = {License: \href{https://creativecommons.org/licenses/by/4.0/}{CC BY 4.0}. Source: \url{https://github.com/ypriverol/github-paper}. Website: \url{https://doi.org/10.1371/journal.pcbi.1004947}}
}

@book{bryan2023,
  author = {Bryan, Jenny},
  title = {Happy Git and GitHub for the useR},
  year = {2023},
  publisher = {Jenny Bryan},
  url = {https://happygitwithr.com},
  note = {License: \href{https://creativecommons.org/licenses/by-nc/4.0/}{CC BY-NC 4.0}. Source: \url{https://github.com/jennybc/happy-git-with-r}. Website: \url{https://happygitwithr.com/}}
}

@article{lowndes2022,
    title = {Openscapes Champions Lesson Series},
    author = {Lowndes, Julia Stewart and Robinson, Erin},
    year = {2022},
    month = {12},
    date = {2022-12-06},
    doi = {10.5281/ZENODO.7407247},
    url = {https://zenodo.org/record/7407247},
    langid = {en},
    note = {License: \href{https://creativecommons.org/licenses/by/4.0/}{CC BY 4.0}. Source: \url{https://github.com/Openscapes/series}. Website: \url{https://openscapes.github.io/series/}}
}

@book{GitHub2023,
  author = {GitHub},
  title = {GitHub Docs},
  year = {2023},
  publisher = {GitHub},
  url = {https://docs.github.com/en},
  note = {License: \href{https://creativecommons.org/licenses/by-nc/4.0/}{CC BY-NC 4.0}. Source: \href{https://docs.github.com/en}{https://docs.github.com/en}}
}

@article{blischak2016,
    title = {A Quick Introduction to Version Control with Git and GitHub},
    author = {Blischak, John D. and Davenport, Emily R. and Wilson, Greg},
    editor = {Ouellette, Francis},
    year = {2016},
    month = {01},
    date = {2016-01-19},
    journal = {PLOS Computational Biology},
    pages = {e1004668},
    volume = {12},
    number = {1},
    doi = {10.1371/journal.pcbi.1004668},
    url = {http://dx.doi.org/10.1371/journal.pcbi.1004668},
    langid = {en},
    note = {License: \href{https://creativecommons.org/licenses/by/4.0/}{CC BY 4.0}. Source: \href{https://doi.org/10.1371/journal.pcbi.1004668}{https://doi.org/10.1371/journal.pcbi.1004668}}
}

@online{aimrsf2023,
  author = {{AI for Multiple Long-term Conditions Research Support Facility}},
  title = {Introduction to version control with git},
  year = {2023},
  month = {06},
  url = {https://www.youtube.com/watch?v=z9-qAGq78qE},
  note = {License: \href{https://creativecommons.org/licenses/by/4.0/}{CC BY 4.0}. Source: \url{https://github.com/aim-rsf/training/tree/main/version-control}}
}

@book{coderefinery2023,
  author = {coderefinery},
  title = {GitHub without the command line},
  year = {2023},
  publisher = {coderefinery},
  url = {https://coderefinery.github.io/github-without-command-line/},
  note = {License: \href{https://creativecommons.org/licenses/by-nc/4.0/}{CC BY-NC 4.0}. Source: \url{https://github.com/coderefinery/github-without-command-line/tree/master}. Website: \url{https://coderefinery.github.io/github-without-command-line/}}
}

@online{amin2023,
  author = {Amin, Abhay},
  title = {Naming conventions for Git Branches — a Cheatsheet},
  year = {2023},
  url = {https://medium.com/@abhay.pixolo/naming-conventions-for-git-branches-a-cheatsheet-8549feca2534},
  note = {License: \href{NA}{NA}. Source: \url{NA}. Website: \url{https://medium.com/@abhay.pixolo/naming-conventions-for-git-branches-a-cheatsheet-8549feca2534}}
}

Use the citation handle of the .bib-entry that you want to cite. For example use @chacon2014 to cite Chacon and Straub (2014). For details, see the chapter on “Citations & Footnotes” in the Quarto documentation. Add the specific references that you used to the bottom of the document. If the reference consists of multiple chapters and pages, try to specify the exact chapter or page.

Add a new reference

  1. Open references.qmd
  2. Switch to the Visual Quarto editor.
  3. Move the cursor into any place in the document.
  4. Click on Insert and select @ Citation ...
  5. If the reference has a DOI:
  6. Select From DOI
  7. Paste the DOI
  8. Select Insert
  9. This should add the new reference to references.bib.
  10. Move the citation key to the correct place

Add license information

We want to keep track of license information. If you add a new reference, please add the license information manually.

  1. Go to references.bib and find the reference.
  2. Inside the .bib-entry for the reference add a new field called note that includes the license information.
@book{
  note = {License: CC BY-NC}
}

For example, this is the references for Chacon and Straub (2014):

@book{chacon2014,
    title = {Pro Git},
    author = {Chacon, Scott and Straub, Ben},
    year = {2014},
    date = {2014},
    publisher = {Apress},
    doi = {10.1007/978-1-4842-0076-6},
    url = {http://dx.doi.org/10.1007/978-1-4842-0076-6},
    note = {License: CC BY-NC}
}

Code

Add code snippets

Add code snippets to a Quarto document like this:

```{bash}
git status
```
Disable code execution in all Quarto documents by default!

Place the following code in the YAML header of each Quarto document:

engine: knitr
execute:
  eval: false
Example: Click here for the YAML header of the current document. 
misc/contributing.qmd
```{r}
#| eval: true
#| include: false
library("magrittr")
library("data.table")
```
Click here to learn more.

Quarto enables the inclusion of executable code blocks in Markdown. This empowers users to create reproducible documents and reports, as the code needed for generating the output is embedded within the document and automatically executed during rendering.

However, in this guide, we usually only want to display code but not execute it! We therefore need to disable code execution in the YAML header of each Quarto document.

The YAML header in a Quarto document is used to specify important metadata and settings for the document. It is typically placed at the top of the document enclosed between three dashes (---) to separate it from the main content. The YAML header provides instructions to the Quarto rendering engine on how to process and present the document.

Reference external code

You can reference external code. For example, the following code block will:

description code
1 reference the _quarto.yml file #&#124; file: _quarto.yml
2 display the first five lines of code echo=c(1:5)
3 add code line numbers #&#124; code-line-numbers: true
4 add a filename to the code block filename="_quarto.yml" 
```{bash, filename="_quarto.yml", echo=c(1:5)}
#| file: _quarto.yml
#| code-line-numbers: true
```
Click here for the output of this example. 
_quarto.yml
project:
  # project options (https://quarto.org/docs/reference/projects/options.html):
  type: book
  output-dir: _book
  execute-dir: project

Add code annotations

Code blocks and executable code cells in Quarto can include line-based annotations. Line-based annotations provide a way to attach explanation to lines of code much like footnotes.

For example, this is a code annotation for the git status command:

```{bash}
git status
```
1. `git status` displays the state of the working directory and the staging area.

Images

Background

Images are stored in a NextCloud folder. They are downloaded into the /static folder using the command specified in the Makefile.

Installation

You need to install the following packages:

  1. GNU Wget
  2. GNU Make
  1. Prerequisite: Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  1. After you installed Homebrew, install GNU Wget
brew install wget

GNU Make should already be installed. Try by entering the following command into the Terminal:

make --version

TBA

TBA

Retrieve images

After you installed all the required software, run this command:

make static
Makefile
STATIC_URL=https://cloud.uni-hamburg.de/s/aD7NTNB9f4NDorT/download
STATIC_ARCHIVE=version-control-book.zip
STATIC_DIR=static/

all: render

.PHONY: preview
preview:
    quarto preview

.PHONY: render
render: clean static
    quarto render
    
.PHONY: deploy
deploy: clean static
    quarto publish gh-pages

# download and extract images:
.PHONY: static
static:
    curl $(STATIC_URL) -o $(STATIC_ARCHIVE)
    unzip -j -o $(STATIC_ARCHIVE) -d $(STATIC_DIR)
    rm -f $(STATIC_ARCHIVE)

.PHONY: clean
clean:
    rm -rf $(STATIC_DIR)* _book/
    
.PHONY: exercises
exercises:
    sh code/code-exercises.sh

Add a new image

  1. Become a collaborator on the UHH Cloud folder.
  2. Go to the UHH Cloud folder.
  3. Place the new image inside the folder. Please use - to separate word in the filename.
  4. Reference the image in the Quarto document relative to the root of the project directory:
![](static/NEW-IMAGE.png)

Download images in pre-render command

It’s also possible to include the make static as a project script in the pre-render script. This would re-execute make static before every render. For the moment, we disabled this option, but it can be enabled in _quarto.yml.

Variables

Quarto offers a number of ways to include dynamic variables within documents. Dynamic variables are useful for externalizing content that varies depending on context, or as an alternative to repeating a value in multiple places.

In this project, we use a project-level _variables.yml file to define variables. Variables can be either simple values or can include arbitrary Markdown content.

_variables.yml (excerpt)
  title: "Version Control Book"
  subtitle: "Track, organize and share your work: An introduction to Git for research"
Click here to view the full _variables.yml file of this project. 
_variables.yml
project:
  title: "Version Control Book"
  subtitle: "Track, organize and share your work: An introduction to Git for research"
  duration: "2023 -- 2024"
  email: "lennart.wittkuhn@tutanota.com"
  mailto: "mailto:{{< var project.email >}}"
  site: "https://lennartwittkuhn.com/version-control-book"
  remote: "https://github.com/lnnrtwttkhn/version-control-book"
  new-issue: "https://github.com/lnnrtwttkhn/version-control-book/issues/new"
  contributors: "https://github.com/lnnrtwttkhn/version-control-book?tab=readme-ov-file#contributors"
  doi: 10.25592/uhhfdm.14149
  doi-link: http://doi.org/10.25592/uhhfdm.14149
# https://quarto.org/docs/authoring/variables.html
links:
  email: mailto:lennart.wittkuhn@uni-hamburg.de
  issues: https://github.com/lnnrtwttkhn/version-control-book/issues
  site: https://lennartwittkuhn.com/version-control-book
  seminar: https://lennartwittkuhn.com/version-control-course-uhh-ws23/
  proposal: https://lennartwittkuhn.com/ddlitlab-proposal
  nextcloud: https://cloud.uni-hamburg.de/s/aD7NTNB9f4NDorT
  new_issues: https://github.com/lnnrtwttkhn/version-control-book/issues/new
  git: https://git-scm.com/
  github: https://github.com/
  gitlab: https://gitlab.com/
  bitbucket: https://bitbucket.org/
  codeberg: https://codeberg.org/
  github-education: https://github.com/edu/
  github-student-developer-pack: https://education.github.com/pack/
  markdown: https://www.markdownguide.org/
  quarto-workshop: https://lennartwittkuhn.com/quarto-workshop/
  gnu-bash: https://www.gnu.org/software/bash/
  power-shell: https://learn.microsoft.com/en-us/powershell/
  git-for-windows: https://gitforwindows.org/
  uhh: https://www.uni-hamburg.de/en.html
  uhh-gitlab: https://gitlab.rrz.uni-hamburg.de/users/sign_in
  mpib: https://www.mpib-berlin.mpg.de/en
  mpib-gitlab: https://www.mpib-berlin.mpg.de/en
quiz:
  intro: https://version-control-versioncontrol.formr.org
  cli: https://version-control-cli.formr.org
  installation: https://version-control-installation.formr.org
  basics: https://version-control-basics.formr.org
  branches: https://version-control-branches.formr.org
  github: https://version-control-github.formr.org
uhh-ws23:
  intro: https://lennartwittkuhn.com/version-control-course-uhh-ws23/sessions/session01.html
  cli: https://lennartwittkuhn.com/version-control-course-uhh-ws23/sessions/session02.html
  basics: https://lennartwittkuhn.com/version-control-course-uhh-ws23/sessions/session03.html
  branches: https://lennartwittkuhn.com/version-control-course-uhh-ws23/sessions/session08.html
  github: https://lennartwittkuhn.com/version-control-course-uhh-ws23/sessions/session09.html
  issues: https://lennartwittkuhn.com/version-control-course-uhh-ws23/sessions/session12.html
uhh-ss24:
  intro: https://lennartwittkuhn.com/version-control-course-uhh-ss24/sessions/session01.html
  cli: https://lennartwittkuhn.com/version-control-course-uhh-ss24/sessions/session02.html
language:
  dont:
    yes: "don't"
    no: "do not"
  folder:
    yes: "folder"
    no: "directory"
  documentation:
    yes: "documentation"
    no: "docs"

The var shortcode then allows to include references to those variables within any document in this project. For example, to include the link to the Nextcloud folder that stores static contents (images etc.) as a variable in a document, use {{< var links.nextcloud >}}.

For more details on variables, read the chapter on Variables in the Quarto documentation.

Fontawesome Icons

We use the Font Awesome Extension for Quarto to include Font Awesome icons.

This extension provides support including free icons provided by Font Awesome. Icons can be used in both HTML (via Font Awesome 6 Free) and PDF (via the fontawesome5 LaTeX package).

This extension includes support for only free Font Awesome icons.

To embed an icon, use the {{< fa >}} shortcode. For example, {{< fa thumbs-up >}} will result in . For details, see the project documentation on GitHub.

Style Guide

We have compiled a set of guidelines to keep a consistent style across all chapters of the book.

Summary

  1. Write one sentence per line
  2. Use consistent language

Write one sentence per line

Please write each sentence on a new line. Having each sentence on a new line will make no difference to how the text is displayed, there will still be paragraphs, but it will mean that any pull requests will be easier to check; the changes will be on a single line instead of somewhere in a paragraph. Consider the example below.

Today you are you, that is truer than true. There is no one alive who is youer than you. - Dr Seuss

A pull request on this correcting it to have a ‘.’ after Dr would show as a change to the whole paragraph. Contrast this with the next example which will be displayed online in the exact same way, but would see a change to a single line.

Today you are you, that is truer than true.
There is no one alive who is youer than you.
- Dr Seuss

Use consistent language

We try to use consistent language:

TRUE FALSE
don’t do not
folder directory
documentation docs

Acknowledgements & Attribution