docs: Add documentation based on the youtube video

Co-authored-by: Oleksiy Kovyrin <oleksiy@kovyrin.net>

.github/DOCS.md

@@ -0,0 +1,23 @@
+# Github config and workflows
+
+In this folder there is configuration for codecoverage, dependabot, and ci
+workflows that check the library more deeply than the default configurations.
+
+This folder can be or was merged using a --allow-unrelated-histories merge
+strategy from <https://github.com/jonhoo/rust-ci-conf/> which provides a
+reasonably sensible base for writing your own ci on. By using this strategy
+the history of the CI repo is included in your repo, and future updates to
+the CI can be merged later.
+
+To perform this merge run:
+
+```shell
+git remote add ci https://github.com/jonhoo/rust-ci-conf.git
+git fetch ci
+git merge --allow-unrelated-histories ci/main
+```
+
+An overview of the files in this project is available at:
+<https://www.youtube.com/watch?v=xUH-4y92jPg&t=491s>, which contains some
+rationale for decisions and runs through an example of solving minimal version
+and OpenSSL issues.

.github/codecov.yml

@@ -18,4 +18,4 @@ ignore:
 # Make comments less noisy
 comment:
   layout: "files"
-  require_changes: yes
+  require_changes: true

.github/dependabot.yml

@@ -10,7 +10,8 @@ updates:
       interval: daily
     ignore:
       - dependency-name: "*"
-        # patch and minor updates don't matter for libraries
+        # patch and minor updates don't matter for libraries as consumers of this library build
+        # with their own lockfile, rather than the version specified in this library's lockfile
         # remove this ignore rule if your package has binaries
         update-types:
           - "version-update:semver-patch"

.github/workflows/check.yml

@@ -1,10 +1,15 @@
 permissions:
   contents: read
+# This configuration allows maintainers of this repo to create a branch and pull request based on
+# the new branch. Restricting the push trigger to the main branch ensures that the PR only gets
+# built once.
 on:
   push:
     branches: [main]
   pull_request:
-# Spend CI time only on latest ref: https://github.com/jonhoo/rust-ci-conf/pull/5
+# If new code is pushed to a PR branch, then cancel in progress workflows for that PR.
+# Ensures that we don't waste CI time, and returns results quicker
+# https://github.com/jonhoo/rust-ci-conf/pull/5
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
@@ -32,6 +37,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        # Get early warning of new lints which are regularly introduced in beta channels.
         toolchain: [stable, beta]
     steps:
       - uses: actions/checkout@v3
@@ -47,6 +53,9 @@ jobs:
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
   doc:
+    # run docs generation on nightly rather than stable. This enables features like
+    # https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html
+    # which allows an API be documented as only available in some specific platforms.
     runs-on: ubuntu-latest
     name: nightly / doc
     steps:
@@ -60,6 +69,8 @@ jobs:
         env:
           RUSTDOCFLAGS: --cfg docsrs
   hack:
+    # cargo-hack checks combinations of feature flags to ensure that features are all additive
+    # which is required for feature unification
     runs-on: ubuntu-latest
     name: ubuntu / stable / features
     steps:
@@ -71,9 +82,11 @@ jobs:
       - name: cargo install cargo-hack
         uses: taiki-e/install-action@cargo-hack
       # intentionally no target specifier; see https://github.com/jonhoo/rust-ci-conf/pull/4
+      # --feature-powerset runs for every combination of features
       - name: cargo hack
         run: cargo hack --feature-powerset check
   msrv:
+    # determine the minimal rust version that is supported by this crate
     runs-on: ubuntu-latest
     # we use a matrix here just because env can't be used in job names
     # https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability

.github/workflows/nostd.yml

@@ -1,10 +1,14 @@
+# This workflow checks whether the library is able to run without the std library (e.g. embedded).
+# This entire file should be removed if this crate does not support no-std
 permissions:
   contents: read
 on:
   push:
     branches: [main]
   pull_request:
-# Spend CI time only on latest ref: https://github.com/jonhoo/rust-ci-conf/pull/5
+# If new code is pushed to a PR branch, then cancel in progress workflows for that PR.
+# Ensures that we don't waste CI time, and returns results quicker
+# https://github.com/jonhoo/rust-ci-conf/pull/5
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true

.github/workflows/safety.yml

@@ -1,10 +1,18 @@
+# This workflow runs checks for unsafe code. In crates that don't have any unsafe code, this can be
+# removed. Runs:
+# - miri - detects undefined behavior and memory leaks
+# - address santizer - detects memory errors
+# - leak sanitizer - detects memory leaks
+# - loom - Permutation testing for concurrent code https://crates.io/crates/loom
 permissions:
   contents: read
 on:
   push:
     branches: [main]
   pull_request:
-# Spend CI time only on latest ref: https://github.com/jonhoo/rust-ci-conf/pull/5
+# If new code is pushed to a PR branch, then cancel in progress workflows for that PR.
+# Ensures that we don't waste CI time, and returns results quicker
+# https://github.com/jonhoo/rust-ci-conf/pull/5
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true

.github/workflows/scheduled.yml

@@ -1,3 +1,5 @@
+# Run scheduled (rolling) jobs on a nightly basis, as your crate may break independently of any
+# given PR. E.g. updates to rust nightly and updates to this crates dependencies.
 permissions:
   contents: read
 on:
@@ -6,7 +8,9 @@ on:
   pull_request:
   schedule:
     - cron:  '7 7 * * *'
-# Spend CI time only on latest ref: https://github.com/jonhoo/rust-ci-conf/pull/5
+# If new code is pushed to a PR branch, then cancel in progress workflows for that PR.
+# Ensures that we don't waste CI time, and returns results quicker
+# https://github.com/jonhoo/rust-ci-conf/pull/5
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
@@ -29,6 +33,10 @@ jobs:
         run: cargo test --locked --all-features --all-targets
   # https://twitter.com/alcuadrado/status/1571291687837732873
   update:
+    # This action checks that updating the dependencies of this crate to the
+    # latest available that satisfy the versions in Cargo.toml does not break
+    # this crate. This is important as consumers of this crate will generally
+    # use the latest available crates.
     runs-on: ubuntu-latest
     name: ubuntu / beta / updated
     # There's no point running this if no Cargo.lock was checked in in the

.github/workflows/test.yml

@@ -4,7 +4,9 @@ on:
   push:
     branches: [main]
   pull_request:
-# Spend CI time only on latest ref: https://github.com/jonhoo/rust-ci-conf/pull/5
+# If new code is pushed to a PR branch, then cancel in progress workflows for that PR.
+# Ensures that we don't waste CI time, and returns results quicker
+# https://github.com/jonhoo/rust-ci-conf/pull/5
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
@@ -15,6 +17,8 @@ jobs:
     name: ubuntu / ${{ matrix.toolchain }}
     strategy:
       matrix:
+        # run on stable and beta to ensure that tests won't break on the next version of the rust
+        # toolchain
         toolchain: [stable, beta]
     steps:
       - uses: actions/checkout@v3
@@ -25,6 +29,7 @@ jobs:
         with:
           toolchain: ${{ matrix.toolchain }}
       - name: cargo generate-lockfile
+        # enable this ci template to run regardless of whether the lockfile is checked in or not
         if: hashFiles('Cargo.lock') == ''
         run: cargo generate-lockfile
       # https://twitter.com/jonhoo/status/1571290371124260865
@@ -34,6 +39,17 @@ jobs:
       - name: cargo test --doc
         run: cargo test --locked --all-features --doc
   minimal:
+    # This action chooses the oldest version of the dependencies to ensure that this crate is
+    # compatible with the minimal version that this crate and its dependencies require.
+    # This will pickup issues where this create relies on functionality that was introduced
+    # later than the actual version specified (e.g. when we choose just a major version, but a
+    # method was added after this version).
+    #
+    # This particular check can be difficult to get to succeed as often transitive dependencies
+    # may be incorrectly specified (e.g. a dependency specifies 1.0 but really requires 1.1.5).
+    # There is an alternative flag available -Zminimal-direct that uses the minimal versions for
+    # direct dependencies of this crate, while selecting the maximal versions for the transitive
+    # dependencies
     runs-on: ubuntu-latest
     name: ubuntu / stable / minimal-versions
     steps:
@@ -51,6 +67,7 @@ jobs:
       - name: cargo test
         run: cargo test --locked --all-features --all-targets
   os-check:
+    # run cargo test on mac and windows
     runs-on: ${{ matrix.os }}
     name: ${{ matrix.os }} / stable
     strategy:
@@ -69,6 +86,8 @@ jobs:
       - name: cargo test
         run: cargo test --locked --all-features --all-targets
   coverage:
+    # use llvm-cov to build and collect coverage and outputs in a format that is compatible with
+    # codecov.io
     runs-on: ubuntu-latest
     name: ubuntu / stable / coverage
     steps: