Merge remote-tracking branch 'ci/main'

Author: jonhoo

.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,8 +10,10 @@ updates:
       interval: daily
     ignore:
       - dependency-name: "*"
-        # patch and minor updates don't matter for libraries
-        # remove this ignore rule if your package has binaries
+        # 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 to ensure that the binaries are
+        # built with the exact set of dependencies and those are up to date.
         update-types:
           - "version-update:semver-patch"
           - "version-update:semver-minor"

.github/workflows/check.yml

@@ -1,7 +1,24 @@
+# This workflow runs whenever a PR is opened or updated, or a commit is pushed to main. It runs
+# several checks:
+# - fmt: checks that the code is formatted according to rustfmt
+# - clippy: checks that the code does not contain any clippy warnings
+# - doc: checks that the code can be documented without errors
+# - hack: check combinations of feature flags
+# - msrv: check that the msrv specified in the crate is correct
+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:
+# 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
 name: check
 jobs:
   fmt:
@@ -12,96 +29,85 @@ jobs:
         with:
           submodules: true
       - name: Install stable
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@stable
         with:
-          profile: minimal
-          toolchain: stable
           components: rustfmt
       - name: cargo fmt --check
-        uses: actions-rs/cargo@v1
-        with:
-          command: fmt
-          args: --check
+        run: cargo fmt --check
   clippy:
     runs-on: ubuntu-latest
     name: ${{ matrix.toolchain }} / clippy
+    permissions:
+      contents: read
+      checks: write
     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@v4
         with:
           submodules: true
       - name: Install ${{ matrix.toolchain }}
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
-          profile: minimal
           toolchain: ${{ matrix.toolchain }}
-          default: true
           components: clippy
       - name: cargo clippy
-        uses: actions-rs/clippy-check@v1
+        uses: giraffate/clippy-action@v1
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          reporter: 'github-pr-check'
+          github_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:
       - uses: actions/checkout@v4
         with:
           submodules: true
       - name: Install nightly
-        uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: nightly
-          default: true
+        uses: dtolnay/rust-toolchain@nightly
       - name: cargo doc
-        uses: actions-rs/cargo@v1
-        with:
-          command: doc
-          args: --no-deps --all-features
+        run: cargo doc --no-deps --all-features
         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:
       - uses: actions/checkout@v4
         with:
           submodules: true
       - name: Install stable
-        uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
+        uses: dtolnay/rust-toolchain@stable
       - 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
-        uses: actions-rs/cargo@v1
-        with:
-          command: hack
-          args: --feature-powerset check --lib --tests
+        run: cargo hack --feature-powerset check
   msrv:
+    # check that we can build using the minimal rust version that is specified 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
     strategy:
       matrix:
-        msrv: [1.66.0] # for jobserver
+        msrv: ["1.66.0"] # for jobserver
     name: ubuntu / ${{ matrix.msrv }}
     steps:
       - uses: actions/checkout@v4
         with:
           submodules: true
-      - name: Install ${{ matrix.toolchain }}
-        uses: actions-rs/toolchain@v1
+      - name: Install ${{ matrix.msrv }}
+        uses: dtolnay/rust-toolchain@master
         with:
-          profile: minimal
           toolchain: ${{ matrix.msrv }}
-          default: true
       - name: cargo +${{ matrix.msrv }} check
-        uses: actions-rs/cargo@v1
-        with:
-          command: check
+        run: cargo check

.github/workflows/scheduled.yml

@@ -1,9 +1,17 @@
+# 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. See check.yml for
+# information about how the concurrency cancellation and workflow triggering works
+permissions:
+  contents: read
 on:
   push:
     branches: [main]
   pull_request:
   schedule:
     - cron:  '7 7 * * *'
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
 name: rolling
 jobs:
   # https://twitter.com/mycoliza/status/1571295690063753218
@@ -15,50 +23,36 @@ jobs:
         with:
           submodules: true
       - name: Install nightly
-        uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: nightly
-          default: true
+        uses: dtolnay/rust-toolchain@nightly
       - name: cargo generate-lockfile
         if: hashFiles('Cargo.lock') == ''
-        uses: actions-rs/cargo@v1
-        with:
-          command: generate-lockfile
+        run: cargo generate-lockfile
       - name: cargo test --locked
-        uses: actions-rs/cargo@v1
-        with:
-          command: test
-          args: --locked --all-features --all-targets
+        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. This is subject to the standard
+    # Cargo semver rules (i.e cargo does not update to a new major version unless explicitly told
+    # to).
     runs-on: ubuntu-latest
     name: ubuntu / beta / updated
-    # There's no point running this if no Cargo.lock was checked in in the
-    # first place, since we'd just redo what happened in the regular test job.
-    # Unfortunately, hashFiles only works in if on steps, so we reepeat it.
-    # if: hashFiles('Cargo.lock') != ''
+    # There's no point running this if no Cargo.lock was checked in in the first place, since we'd
+    # just redo what happened in the regular test job. Unfortunately, hashFiles only works in if on
+    # steps, so we repeat it.
     steps:
       - uses: actions/checkout@v4
         with:
           submodules: true
       - name: Install beta
         if: hashFiles('Cargo.lock') != ''
-        uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: beta
-          default: true
+        uses: dtolnay/rust-toolchain@beta
       - name: cargo update
         if: hashFiles('Cargo.lock') != ''
-        uses: actions-rs/cargo@v1
-        with:
-          command: update
+        run: cargo update
       - name: cargo test
         if: hashFiles('Cargo.lock') != ''
-        uses: actions-rs/cargo@v1
-        with:
-          command: test
-          args: --locked --all-features --all-targets
+        run: cargo test --locked --all-features --all-targets
         env:
           RUSTFLAGS: -D deprecated