Merge pull request #142 from tommilligan/rust-version

ci: add msrv to cargo toml, update mdbook version

3 files changed, 34 insertions, 10 deletions

diff --git a/Cargo.toml b/Cargo.toml
index 96873d5..acf33bc 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -2,6 +2,7 @@
 name = "mdbook-admonish"
 version = "1.13.0"
 edition = "2021"
+rust-version = "1.66.0"
 
 authors = ["Tom Milligan <code@tommilligan.net>"]
 description = "A preprocessor for mdbook to add Material Design admonishments."
@@ -27,7 +28,9 @@ path = "src/lib.rs"
 [dependencies]
 anyhow = "1.0.75"
 # Note: clap 4.4 increases MSRV to 1.70.0 (2023-06-01)
-clap = { version = "~4.3", default_features = false, features = ["std", "derive"], optional = true }
+# To use MSRV supported dependencies, install using the lockfile with
+# `cargo install mdbook-admonish --locked`
+clap = { version = "4.3", default_features = false, features = ["std", "derive"], optional = true }
 env_logger = { version = "0.10", default_features = false, optional = true }
 log = "0.4.20"
 mdbook = "0.4.35"
diff --git a/README.md b/README.md
index bf6a50d..26d9bad 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,9 @@ Install the tool:
 
 ```bash
 cargo install mdbook-admonish
+
+# If you get compilation/installation errors, try a locked installation
+cargo install mdbook-admonish --locked
 ```
 
 Then let `mdbook-admonish` add the required files and configuration:
@@ -101,6 +104,21 @@ Then, build your book as usual:
 mdbook path/to/book
 ```
 
+### Reproducible builds
+
+For a reproducible build suitable for use in CI or scripts, please:
+
+- Pin to a specific version
+- Install with lockfile dependencies
+- Always install the latest CSS assets
+
+```bash
+cargo install mdbook-admonish --vers "1.5.0" --locked
+mdbook-admonish install path/to/your/book
+```
+
+The Minimum Supported Rust Version (MSRV) is documented in `Cargo.toml`, and noted in the `CHANGELOG.md`. We aims to support around six months of stable Rust.
+
 ### Updates
 
 **Please note**, when updating your version of `mdbook-admonish`, updated styles will not be applied unless you rerun `mdbook-admonish install` to update the additional CSS files in your book.
@@ -117,12 +135,6 @@ ERROR:
 
 If you want to update across minor versions without breakage, you should always run `mdbook-admonish install`.
 
-Alternatively, pin to a specific version for a reproducible installation:
-
-```bash
-cargo install mdbook-admonish --vers "1.5.0" --locked
-```
-
 ### Process included files
 
 You can ensure that content inlined with `{{#include}}` is also processed by [setting the `after` option](https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html#require-a-certain-order):
diff --git a/scripts/install-mdbook b/scripts/install-mdbook
index 8ff23e8..5fac222 100755
--- a/scripts/install-mdbook
+++ b/scripts/install-mdbook
@@ -1,9 +1,18 @@
 #!/bin/bash
 
-set -exuo pipefail
+set -euo pipefail
 
 cd "$(dirname "$0")"/..
 
-if ! mdbook --version; then
-  cargo install mdbook --version 0.4.32 --force
+function eprintln() {
+  >&2 echo "$1"
+}
+
+VERSION="0.4.35"
+
+eprintln "Checking if mdbook $VERSION is installed"
+if [[ "$(mdbook --version)" != "mdbook v$VERSION" ]]; then
+  eprintln "Installing mdbook $VERSION"
+  cargo install mdbook --version "$VERSION" --force
 fi
+eprintln "mdbook $VERSION is installed"