Rust projects typically reference the crate version number in several
places, such as the README.md
file. The version-sync crate makes it
easy to add an integration test that checks that README.md
is
updated when the crate version changes.
Add this to your Cargo.toml
:
toml
[dev-dependencies]
version-sync = "0.9"
Then create a tests/version-numbers.rs
file with:
```rust
fn testreadmedeps() { versionsync::assertmarkdowndepsupdated!("README.md"); }
fn testhtmlrooturl() { versionsync::asserthtmlrooturlupdated!("src/lib.rs"); } ```
This integration test will ensure that the dependencies mentioned in
your README.md
file are kept in sync with your crate version and
that your html_root_url
points to the correct documentation on
docs.rs. If everything is well, the test passes:
``` $ cargo test Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs Running target/debug/deps/version_numbers-504f17c82f1defea
running 2 tests test testreadmedeps ... ok test testhtmlroot_url ... ok
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured ```
If the README or html_root_url
is out of sync with the crate
version, the tests fail. In this example, the crate is called
your-crate
and the version number in Cargo.toml
has been changed
to 0.2.0 while the README.md
and html_root_url
still use 0.1.2.
The tests now fail and the problematic TOML code and attribute are
shown:
``` $ cargo test Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs Running target/debug/deps/version_numbers-f399bac3e468d035
running 2 tests test testreadmedeps ... FAILED test testhtmlroot_url ... FAILED
failures:
---- testreadmedeps stdout ---- Checking code blocks in README.md... README.md (line 20) ... expected minor version 2, found 1 in [dev-dependencies] your-crate = "0.1"
thread 'testreadmedeps' panicked at 'dependency errors in README.md', tests/version-numbers.rs:6
note: Run with RUST_BACKTRACE=1
for a backtrace.
---- testhtmlrooturl stdout ---- Checking doc attributes in src/lib.rs... src/lib.rs ... expected minor version 2, found 1 in #![doc(htmlroot_url = "https://docs.rs/your-crate/0.1.2")]
thread 'testhtmlrooturl' panicked at 'htmlroot_url errors in src/lib.rs', tests/version-numbers.rs:11
failures: testhtmlrooturl testreadme_deps
test result: FAILED. 0 passed; 2 failed; 0 ignored; 0 measured
error: test failed ```
You can add no_sync
to the language line in a code block to exclude
it from the checks done by assert_markdown_deps_updated!
:
~~~markdown
toml,no_sync
[dependencies]
your_crate = "0.1.2"
~~~
This is a changelog describing the most important changes per release.
non_fmt_panic
lint error in latest nightly.\r\n
to \n
to ensure ^
and $
always match line boundaries.Drop support for Rust 1.31.0 since our dependencies keep releasing new
patch versions that push up the minimum required Rust version. These
updates mean that version-sync 0.8.1 no longer compiles with Rust
1.31.0 because cargo sync
will pull in too new versions of the
direct and transitive dependencies. This happens even if there are no
changes in version-sync.
The constant build failures in our CI makes it infeasible to keep version-sync compatible with any particular version of Rust. We will therefore track the latest stable version of Rust from now on.
At the time of writing, the code compiles with Rust 1.36, but this will likely become outdated soon.
Issues closed:
Dependencies were relaxed to make it easier to upgrade version-sync.
We now use Rust 2018, which means we require Rust version
1.31.0 or later. The assert_html_root_url_updated!
macro will again
report accurate line numbers based on span information from the syn
crate.
Special characters are now correctly escaped in the {name}
and
{version}
placeholders in assert_contains_regex!
.
Dependencies were updated and version-sync now requires Rust version 1.27.2 or later.
You can use assert_contains_regex!
to grep files for the current
version number. The search is done with a regular expression where
{version}
is replaced with the current version number.
Git dependencies are now always accepted, which means that blocks like
~~~markdown
toml
[dependencies]
your_crate = { git = "..." }
~~~
will work without you having to add no_sync
.
Issues closed:
Dependencies were updated and version-sync now requires Rust version 1.21 or later.
Error messages from assert_html_root_url_updated!
now again include
line numbers (based on a heuristic until the syn crate can provide the
information).
This release replaces the dependency on the abandoned syntex_syntax with with a dependency on the much lighter syn crate. This improves compilation speed. Unfortunately, the syn crate does not provide information about line numbers, so error messages are are no longer as good. We might be able to work around that in a later version.
This release fixes a small problem with the handling of pre-release identifiers.
Issues closed:
When checking dependencies in READMEs, TOML blocks can now be excluded
from the check by adding no_sync
to the language line:
~~~markdown
toml,no_sync
[dependencies]
your_crate = "0.1"
~~~
This TOML block will not be checked. This is similar to no_run
for
Rust code blocks.
Added assert_html_root_url_updated!
which will check that the
html_root_url
attribute points to the correct version of the crate
documentation on docs.rs.
First public release with support for finding outdated version numbers
in dependencies
and dev-dependencies
.
Versions 0.1.0 to 0.1.2 were released under the name check-versions.
Version-sync can be distributed according to the MIT license. Contributions will be accepted under the same license.