relentless 0.7.0

Composable retry policies for fallible operations and polling.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

# Contributing

This guide explains how to work on `relentless` with the same toolchain and
checks used by the repository. Use it when you set up a new clone, install Git
hooks, or want to understand which commands are part of the normal development
loop.

`README.md` is the project overview and quick-start guide.
[docs/SPEC.md](./docs/SPEC.md) is the normative behavior and public-API
contract. Keep behavior changes aligned with the spec, and keep workflow and
CI guidance in this document rather than in the spec.

## Development environment

`relentless` uses a pinned Rust toolchain and a pinned Nix shell so contributors
run the same checks with the same tool versions.

- [rust-toolchain.toml](./rust-toolchain.toml) pins Rust `1.85.0`, `clippy`,
  `rustfmt`, and the required cross-compilation targets.
- [shell.nix](./shell.nix) provides `just`, `pre-commit`, `taplo`, `typos`,
  and `cargo-deny`.

To enter the pinned shell, run:

```bash
nix-shell
```

## First-time setup

Run the setup script once after you clone the repository. It installs the Git
hooks through the pinned shell and leaves your repository ready for normal
development.

```bash
./scripts/setup-dev.sh
```

The script installs:

- a `pre-commit` hook for fast formatting and typo checks
- a `pre-push` hook for clippy and test coverage

## Daily workflow

Use `just` for day-to-day development. The commands are split between a fast
local loop and stricter CI-oriented gates.

For normal local work, the most useful commands are:

- `just build`
- `just test`
- `just fmt`
- `just lint`
- `just pre-commit`
- `just pre-push`

For the full repository gate, run:

```bash
just ci
```

`just ci` is the canonical project gate. It runs the pinned-toolchain checks
that GitHub Actions enforces.

## Stable checks

The repository also provides an advisory latest-stable lane. Use it to see how
the code behaves on the newest stable Rust without changing the supported
toolchain policy.

```bash
just ci-stable
```

`just ci-stable` is informational. It helps you spot new warnings or behavior
changes early, but the pinned `just ci` gate remains the source of truth.

## Toolchain policy

`relentless` supports Rust `1.85.0` as its minimum supported Rust version
(MSRV). That matches the crate metadata and the Rust 2024 edition used by the
project.

You can use a newer local Rust toolchain if you want, but you must keep the
repository compatible with the pinned toolchain unless you intentionally raise
MSRV.

## Git hooks

The Git hooks are designed to give you quick feedback before a commit or push.
They run through `nix-shell`, so they use the pinned versions of the developer
tools.

The hooks currently do this:

- `pre-commit`: `just pre-commit`
- `pre-push`: `just pre-push`

If you need to reinstall the hooks, run:

```bash
./scripts/setup-dev.sh
```