merge main

.cargo/mutants.toml

@@ -0,0 +1,38 @@
+# Controls tests with `cargo mutants`
+
+# Skip some relatively unimportant functions and traits for now.
+exclude_re = ["<impl Display"]
+
+# Include only files that are currently well-tested.
+examine_globs = [
+    "src/backup.rs",
+    "src/bandid.rs",
+    "src/blockdir.rs",
+    "src/blockhash.rs",
+    "src/bin/conserve.rs",
+    "src/change.rs",
+    "src/counters.rs",
+    "src/jsonio.rs",
+    "src/restore.rs",
+    "src/transport.rs",
+    "src/transport/local.rs",
+]
+
+# Skip S3 which is hard to test hermetically without AWS creds.
+#
+# Skip console and progress code which seems like a low priority
+# to test.
+#
+# stats.rs should be tested but is closely tied to formatting, and the
+# text format might change.
+#
+# I test for mutants on Unix so skip Windows code.
+# exclude_globs = [
+#     "metric_recorder.rs",
+#     "progress.rs",
+#     "src/progress/term.rs",
+#     "src/transport/s3.rs",
+#     "src/ui/termui.rs",
+#     "src/owner/windows.rs",
+#     "stats.rs",
+# ]

.codespell.dict

@@ -0,0 +1 @@
+assertino->assertion

.codespell.words

@@ -0,0 +1,2 @@
+crate
+ser

.codespellrc

@@ -0,0 +1,5 @@
+[codespell]
+ignore-words = .codespell.words
+skip = target,.git
+builtin = clear,rare,code
+dictionary = .codespell.dict

.devcontainer/Dockerfile

@@ -0,0 +1,9 @@
+# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.238.1/containers/rust/.devcontainer/base.Dockerfile
+
+# [Choice] Debian OS version (use bullseye on local arm64/Apple Silicon): buster, bullseye
+ARG VARIANT="buster"
+FROM mcr.microsoft.com/vscode/devcontainers/rust:0-${VARIANT}
+
+# [Optional] Uncomment this section to install additional packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>

.devcontainer/devcontainer.json

@@ -0,0 +1,53 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.238.1/containers/rust
+{
+  "name": "Rust",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      // Use the VARIANT arg to pick a Debian OS version: buster, bullseye
+      // Use bullseye when on local on arm64/Apple Silicon.
+      "VARIANT": "bullseye"
+    }
+  },
+  "runArgs": ["--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined"],
+
+  // Configure tool-specific properties.
+  "customizations": {
+    // Configure properties specific to VS Code.
+    "vscode": {
+      // Set *default* container specific settings.json values on container create.
+      "settings": {
+        "lldb.executable": "/usr/bin/lldb",
+        // VS Code don't watch files under ./target
+        "files.watcherExclude": {
+          "**/target/**": true
+        },
+        "rust-analyzer.checkOnSave.command": "clippy"
+      },
+
+      // Add the IDs of extensions you want installed when the container is created.
+      "extensions": [
+        "vadimcn.vscode-lldb",
+        "mutantdino.resourcemonitor",
+        "rust-lang.rust-analyzer",
+        "tamasfe.even-better-toml",
+        "serayuzgur.crates"
+      ]
+    }
+  },
+
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  // "forwardPorts": [],
+
+  // Use 'postCreateCommand' to run commands after the container is created.
+  // "postCreateCommand": "rustc --version",
+
+  // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+  "remoteUser": "vscode",
+  "features": {
+    "git": "os-provided",
+    "github-cli": "latest",
+    "ghcr.io/meaningful-ooo/devcontainer-features/fish:1": {}
+  }
+}

.github/workflows/install.yml

@@ -0,0 +1,19 @@
+on:
+  push:
+    paths:
+      - '.github/workflows/install.yml'
+  schedule:
+    - cron: "17 0 * * 1"
+
+jobs:
+  cargo-install:
+    strategy:
+      matrix:
+        locked: ["", "--locked"]
+        # TODO: Enable s3 when it's released
+        features: [""]
+    runs-on: ubuntu-latest
+    steps:
+      - name: cargo-install
+        run: |
+          cargo install cargo-mutants ${{ matrix.locked }} --features=${{ matrix.features }}

.github/workflows/rust.yml

@@ -1,6 +1,6 @@
 name: Rust
 
-on: [push, pull_request]
+on: [push]
 
 # see https://matklad.github.io/2021/09/04/fast-rust-builds.html
 env:
@@ -15,31 +15,68 @@ env:
 # TODO: Add -D warnings when that's clean on Windows.
 
 jobs:
-  build:
+  tests:
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: true
       matrix:
         os: [ubuntu-latest, windows-latest, macOS-latest]
+        features: ["", "s3"]
+        version: [stable, nightly, "1.73"]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.version }}
+          components: rustfmt
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ matrix.features }}
       - name: Show version
         run: |
           rustup show
           cargo --version
           rustc --version
-      - name: Cache Cargo
-        uses: actions/cache@v2
-        with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: cargo-${{ runner.os }}-${{ hashFiles('Cargo.lock') }}
-          restore-keys: |
-            cargo-${{ runner.os }}-
       - name: Build
-        run: cargo build --all-targets
-      - name: Run tests
-        run: cargo test -- --include-ignored
+        run:
+          cargo build --all-targets --no-default-features --features=${{
+          matrix.features }}
+      - name: Test
+        run:
+          cargo test --no-default-features --features=${{ matrix.features }} --
+          --include-ignored
+      # Clippy and rustfmt are excellent tools but are turned off here because it's too
+      # easy for PRs to fail due to irrelevant changes including Clippy flagging problems
+      # that it did not notice before.
+      # - name: clippy
+      #   run: cargo clippy --all-targets -- -d clippy::all
+      # - name: rustfmt
+      #   run: cargo fmt --all -- --check
+
+  cargo-mutants:
+    runs-on: ubuntu-latest
+    # Don't run expensive mutant tests until we know the build is clean.
+    needs: tests
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Install cargo-mutants
+        uses: baptiste0928/cargo-install@v2
+        with:
+          crate: cargo-mutants
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: stable
+          components: rustfmt
+      - name: Run mutant tests
+        # Can't use --all-features here because BLAKE2 SIMD needs unstable...
+        # Don't use the S3 features because they require AWS credentials for realistic
+        # testing.
+        run:
+          cargo mutants -j2 --no-shuffle -vV --cargo-arg --no-default-features
+      - name: Archive results
+        uses: actions/upload-artifact@v3
+        with:
+          name: mutation-report
+          path: mutants.out

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "markdownlint.config": {
+    "MD024": false // Allow multiple headers with the same content; exists in NEWS historically
+  }
+}

CONTRIBUTING.md

@@ -2,6 +2,9 @@
 
 Contributions are very welcome.
 
+If your change is nontrivial please talk to me in a bug about the approach
+before writing lots of code.
+
 By sending patches or pull requests, you consent for your code to be licensed
 under the existing Conserve licence, the GNU GPL v2.
 
@@ -10,12 +13,13 @@ under the existing Conserve licence, the GNU GPL v2.
 There are some bugs marked [good first issue][] if you'd like to contribute but
 don't have a particular feature or bug in mind.
 
-[good first issue]: https://github.com/sourcefrog/conserve/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+[good first issue]:
+  https://github.com/sourcefrog/conserve/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
 
 ## Communication
 
 Please feel free to comment on a bug if you're interested in working on it, or
-to send a draft pull request for feedback before it's ready to merge. 
+to send a draft pull request for feedback before it's ready to merge.
 
 ## Code style
 
@@ -27,25 +31,39 @@ it sets a direction.
 
 Code can be tested in any of five different places:
 
-* Public API tests, in `tests/api`. All core features should be exercised here,
-  although some edge cases that can't be reached through the public API could
-  be left for unit tests.
+- Public API tests, in `tests/api`. All core features should be exercised here,
+  although some edge cases that can't be reached through the public API could be
+  left for unit tests.
 
-* Black-box tests that run the Conserve CLI as a binary, in
-  `tests/cli`.  All the main uses of the CLI should be exercised here.
+- Black-box tests that run the Conserve CLI as a binary, in `tests/cli`. All the
+  main uses of the CLI should be exercised here.
 
-* Time-consuming tests, using proptest, in `tests/expensive`. These are
-  `#[ignore]` at the test level, and only run by `cargo test --
-  --include-ignored`, which is done on CI.
+- Time-consuming tests, using proptest, in `tests/expensive`. These are
+  `#[ignore]` at the test level, and only run by
+  `cargo test -- --include-ignored`, which is done on CI.
 
-* Doctests, especially for functions in the public API that are amenable to
+- Doctests, especially for functions in the public API that are amenable to
   small examples. These are somewhat slow to build so are used only in cases
   where an example is especially helpful in describing the API.
 
-* Individual functions, as unit tests within the implementation module. Prefer
+- Individual functions, as unit tests within the implementation module. Prefer
   this for things that are important to test, but not exposed or not easily
-  testable through the public API. Most things should be tested through the 
+  testable through the public API. Most things should be tested through the
   public API and not inside the implementation.
 
 If it's hard to work out how to test your change please feel free to put up a
 draft PR with no tests and just ask.
+
+### Archive snapshots
+
+There are some snapshots in `testdata/archive` of archives written by previous
+versions of Conserve, to test cross-version compatibility.
+
+A new snapshot should be added in every release that makes an archive format
+change, even changes that are expected to be very small or to be fully backwards
+and forwards compatible.
+
+Existing snapshots should generally never be changed.
+
+New features that depend on new archive fields should be tested against old
+archive snapshots to ensure they are handled gracefully.