@convesoft/nx-rust 1.0.0-rc.1 → 1.0.0-rc.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/PLUGIN.md +106 -0
- package/README.md +8 -4
- package/docs/artifacts.mara.md +374 -0
- package/docs/caching.mara.md +999 -0
- package/docs/ci.mara.md +308 -0
- package/docs/configuration.mara.md +508 -0
- package/docs/decisions.mara.md +3267 -0
- package/docs/execution.mara.md +533 -0
- package/docs/index.mara.md +51 -0
- package/docs/product.mara.md +366 -0
- package/docs/release.mara.md +493 -0
- package/docs/setup.mara.md +486 -0
- package/docs/targets.mara.md +704 -0
- package/docs/testing.mara.md +431 -0
- package/docs/verification.mara.md +465 -0
- package/docs/workspaces.mara.md +445 -0
- package/package.json +1 -1
- package/src/cargo/build-settings.d.ts +8 -1
- package/src/cargo/build-settings.js +21 -11
- package/src/cargo/build-settings.js.map +1 -1
- package/src/cargo/metadata.d.ts +2 -0
- package/src/cargo/metadata.js.map +1 -1
- package/src/cargo/redirections.d.ts +4 -1
- package/src/cargo/redirections.js +7 -2
- package/src/cargo/redirections.js.map +1 -1
- package/src/cargo/warnings-setting.d.ts +24 -0
- package/src/cargo/warnings-setting.js +81 -0
- package/src/cargo/warnings-setting.js.map +1 -0
- package/src/executors/cargo/schema.json +4 -0
- package/src/executors/cargo-output.d.ts +8 -2
- package/src/executors/cargo-output.js +20 -6
- package/src/executors/cargo-output.js.map +1 -1
- package/src/executors/command.d.ts +13 -0
- package/src/executors/command.js +37 -7
- package/src/executors/command.js.map +1 -1
- package/src/executors/denied-warnings.d.ts +99 -0
- package/src/executors/denied-warnings.js +188 -0
- package/src/executors/denied-warnings.js.map +1 -0
- package/src/executors/group-run.d.ts +1 -1
- package/src/executors/group-run.js +23 -13
- package/src/executors/group-run.js.map +1 -1
- package/src/executors/groups.d.ts +7 -2
- package/src/executors/groups.js +22 -3
- package/src/executors/groups.js.map +1 -1
- package/src/executors/nextest.d.ts +6 -2
- package/src/executors/nextest.js +12 -6
- package/src/executors/nextest.js.map +1 -1
- package/src/executors/task-guards.js +7 -2
- package/src/executors/task-guards.js.map +1 -1
- package/src/executors/task.js +10 -3
- package/src/executors/task.js.map +1 -1
- package/src/executors/test-mode.d.ts +4 -1
- package/src/executors/test-mode.js +7 -1
- package/src/executors/test-mode.js.map +1 -1
- package/src/executors/test-steps.d.ts +20 -8
- package/src/executors/test-steps.js +45 -14
- package/src/executors/test-steps.js.map +1 -1
- package/src/graph/caching.js +5 -0
- package/src/graph/caching.js.map +1 -1
- package/src/graph/clippy-input.d.ts +53 -0
- package/src/graph/clippy-input.js +107 -0
- package/src/graph/clippy-input.js.map +1 -0
- package/src/graph/collisions.d.ts +7 -0
- package/src/graph/collisions.js.map +1 -1
- package/src/graph/discovery.d.ts +15 -0
- package/src/graph/discovery.js +5 -0
- package/src/graph/discovery.js.map +1 -1
- package/src/graph/inputs.d.ts +3 -1
- package/src/graph/inputs.js +11 -1
- package/src/graph/inputs.js.map +1 -1
- package/src/graph/projects.js +13 -2
- package/src/graph/projects.js.map +1 -1
- package/src/graph/rustfmt-config.d.ts +42 -0
- package/src/graph/rustfmt-config.js +173 -0
- package/src/graph/rustfmt-config.js.map +1 -0
- package/src/graph/targets.d.ts +11 -7
- package/src/graph/targets.js +12 -8
- package/src/graph/targets.js.map +1 -1
|
@@ -0,0 +1,493 @@
|
|
|
1
|
+
# Releasing
|
|
2
|
+
|
|
3
|
+
> **Status:** implemented as described here, for milestone 0.5. `nx release
|
|
4
|
+
> version` versions crates and brings `Cargo.lock` up to date as
|
|
5
|
+
> [Versioning](#versioning) describes, and `nx release publish` publishes
|
|
6
|
+
> them as [Publishing](#publishing), [Registries](#registries) and
|
|
7
|
+
> [Dependencies that are not published](#dependencies-that-are-not-published)
|
|
8
|
+
> describe. Known gaps that are not scheduled yet are in the backlog.
|
|
9
|
+
|
|
10
|
+
A repository that versions and publishes its JS packages with
|
|
11
|
+
[Nx release](https://nx.dev/features/manage-releases) releases its crates
|
|
12
|
+
through the same commands:
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
nx release # versions, changelogs, commit and tag, then asks whether to publish
|
|
16
|
+
nx release --yes # the same, and publishes without asking
|
|
17
|
+
nx release publish --dry-run # check what publishing the committed versions would upload
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Nx release keeps doing what it does for JS packages: it works out the bumps
|
|
21
|
+
from conventional commits or version plans, writes changelogs, and makes the
|
|
22
|
+
git commit and tag. The plugin teaches it `Cargo.toml`, `Cargo.lock` and
|
|
23
|
+
`cargo publish`.
|
|
24
|
+
|
|
25
|
+
## Setting it up
|
|
26
|
+
|
|
27
|
+
Release configuration lives in `nx.json`, and in a crate folder's
|
|
28
|
+
`project.json` where one exists, as for JS packages; the plugin's tables in
|
|
29
|
+
`Cargo.toml` hold none. Each crate's project already names the plugin's
|
|
30
|
+
version actions, so `nx.json` needs no `versionActions`, and a repository with
|
|
31
|
+
only Rust needs no `@nx/js`.
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"release": {
|
|
36
|
+
"groups": {
|
|
37
|
+
"crates": {
|
|
38
|
+
"projects": ["core", "api", "cli"],
|
|
39
|
+
"projectsRelationship": "fixed"
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
"git": { "commit": true, "tag": true }
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
- Cargo publishes committed files only. `nx release` commits and tags by
|
|
48
|
+
default, with the settings of `release.git`. `nx release version` on its own
|
|
49
|
+
only stages its changes, and refuses a root `release.git`. To run the
|
|
50
|
+
subcommands one after another, have it commit and tag with
|
|
51
|
+
`nx release version --git-commit --git-tag --stage-changes`, or set
|
|
52
|
+
`release.version.git` in place of `release.git`, which `nx release` refuses
|
|
53
|
+
in turn.
|
|
54
|
+
- Crates that inherit `version.workspace = true` share one version. Put all of
|
|
55
|
+
them into one release group with `"projectsRelationship": "fixed"`;
|
|
56
|
+
otherwise `nx release version` stops before it writes anything and names
|
|
57
|
+
them.
|
|
58
|
+
- Leave the workspace project of a virtual manifest, such as `rust` or
|
|
59
|
+
`cargo-workspace`, out of the release projects. It has no version.
|
|
60
|
+
- Publishing needs Cargo 1.91 or later, which the plugin requires anyway.
|
|
61
|
+
|
|
62
|
+
## Versioning
|
|
63
|
+
|
|
64
|
+
`nx release version` reads each crate's current version from its `Cargo.toml`,
|
|
65
|
+
following `[workspace.package]` where the crate inherits it, and writes the
|
|
66
|
+
new one back:
|
|
67
|
+
|
|
68
|
+
| What | What happens |
|
|
69
|
+
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
70
|
+
| A crate with its own `version` | The new version is written to its `[package]` table |
|
|
71
|
+
| Crates with `version.workspace = true` | One version, written once to `[workspace.package].version` |
|
|
72
|
+
| A crate that depends on a bumped crate, as a normal or build dependency with a `version` | It is bumped as well, by a patch by default (Nx's `updateDependents`), because its published crate names the new version |
|
|
73
|
+
| A dev-dependency on a bumped crate | No bump: the crates that use a crate never build its dev-dependencies |
|
|
74
|
+
| A path dependency without `version` on a bumped crate | No bump: cargo leaves such a dev-dependency out when it publishes, and refuses to publish a crate with such a normal dependency |
|
|
75
|
+
| Any version requirement on a bumped crate in the repository's Cargo workspaces | Updated, also in `[workspace.dependencies]` and in crates that are not released, so that every workspace still resolves |
|
|
76
|
+
| `Cargo.lock` | `cargo update --workspace` in each workspace whose manifests changed or whose lockfile locks a bumped crate by path; no other locked package moves, and Nx commits it; a workspace without a `Cargo.lock` gets none |
|
|
77
|
+
|
|
78
|
+
A requirement is updated like this:
|
|
79
|
+
|
|
80
|
+
| Requirement | New version | Result |
|
|
81
|
+
| ---------------------- | ----------- | ------------------------------------------------------------------------------- |
|
|
82
|
+
| `0.1.0`, `^0.1` | 0.1.4 | Kept: it still matches (Nx's `preserveMatchingDependencyRanges`, on by default) |
|
|
83
|
+
| `0.1.0` | 0.2.0 | `0.2.0` |
|
|
84
|
+
| `^0.1` | 0.2.0 | `^0.2.0` |
|
|
85
|
+
| `~0.1.0` | 0.2.0 | `~0.2.0` |
|
|
86
|
+
| `=0.1.0` | 0.1.4 | `=0.1.4` |
|
|
87
|
+
| `>=0.1, <0.2`, `0.1.*` | 0.1.4 | Kept, also with `preserveMatchingDependencyRanges` off; the output names it |
|
|
88
|
+
| `>=0.1, <0.2`, `0.1.*` | 0.2.0 | Versioning stops before it writes anything, naming the manifest |
|
|
89
|
+
|
|
90
|
+
Only the version strings change. Comments and layout of the manifests stay as
|
|
91
|
+
they are, and Nx's formatter leaves the manifests alone. `git-tag` works as the
|
|
92
|
+
current-version resolver as Nx provides it; `registry` is not supported.
|
|
93
|
+
Where `preserveMatchingDependencyRanges` differs between crates, the setting of
|
|
94
|
+
the crate whose manifest holds the requirement counts, and for a crate outside
|
|
95
|
+
the release and in `[workspace.dependencies]` that of the crate whose version
|
|
96
|
+
changes. `versionPrefix` and `manifestRootsToUpdate` have no effect.
|
|
97
|
+
|
|
98
|
+
Besides the dependency tables, versioning keeps these places in step with a
|
|
99
|
+
crate's new version, or stops before it writes anything:
|
|
100
|
+
|
|
101
|
+
| Place that names a bumped crate | What happens |
|
|
102
|
+
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
103
|
+
| `[patch.<source>]` entry with `path` and `version`, in a root manifest | The requirement is updated by the rules above; it makes no crate a dependent |
|
|
104
|
+
| The same in a `.cargo/config.toml` that cargo reads, inside the repository | The same |
|
|
105
|
+
| The same in a Cargo configuration outside the repository, such as the Cargo home's | Kept where it still matches; otherwise versioning stops, naming the file |
|
|
106
|
+
| `[replace]` entry whose `path` names the crate | Versioning stops: cargo takes a replacement only with the version it replaces; use `[patch]` |
|
|
107
|
+
| A registry requirement that a `[patch]` redirects to the crate, by `crates-io`, a registry's name or an index or git URL | Kept where the new version still matches it; otherwise versioning stops, because cargo would quietly take the registry's crate |
|
|
108
|
+
| `[profile.<name>.package."<crate>@<version>"]`, also by `file://` URL | Versioning stops where the new version leaves it; write the table without the version |
|
|
109
|
+
|
|
110
|
+
Nx decides two kinds of bump across release groups by itself, which show only
|
|
111
|
+
where groups take their bumps from conventional commits or version plans: a
|
|
112
|
+
specifier on the command line, as in `nx release version minor`, applies to
|
|
113
|
+
every crate of the run.
|
|
114
|
+
|
|
115
|
+
- A fixed group that gets no bump of its own is bumped when a crate of it has an
|
|
116
|
+
edge in the project graph to a crate of a group that Nx bumped before it,
|
|
117
|
+
also through a dev-dependency, because the plugin's edges include those. The
|
|
118
|
+
run goes on, and its output names the group, the edge and what it is in
|
|
119
|
+
Cargo. This is a known limit of Nx release.
|
|
120
|
+
- A crate in an independent group that depends on a crate of a fixed group is
|
|
121
|
+
not bumped when Nx bumps that group, unless its own group bumps it. Its
|
|
122
|
+
requirement would change without a new version, so versioning stops before
|
|
123
|
+
it writes anything and names the crate: release it in the same run, with a
|
|
124
|
+
version plan or a conventional commit of its own. The same holds for any crate
|
|
125
|
+
in the release whose requirement would change without a bump, as under
|
|
126
|
+
`updateDependents: "never"`.
|
|
127
|
+
|
|
128
|
+
Every check runs before the first file is written, also one that each file to
|
|
129
|
+
be changed is writable and lies inside the repository once symbolic links are
|
|
130
|
+
followed: a `.cargo/config.toml` or a member's folder that links outside stops
|
|
131
|
+
versioning, naming where it leads. A file that a link inside the repository
|
|
132
|
+
leads to is written, staged and committed under its own path, and the link
|
|
133
|
+
stays as it is. A manifest, configuration file or lockfile that exists but
|
|
134
|
+
cannot be read, or a lockfile that is no valid TOML, such as one with merge
|
|
135
|
+
conflict markers, stops versioning before anything is written, naming it. A
|
|
136
|
+
failure while Nx writes the files, which no check foresees, such as a full disk,
|
|
137
|
+
can leave manifests changed and unstaged: `git checkout` undoes them.
|
|
138
|
+
|
|
139
|
+
The lockfiles are updated last, after Nx has written the manifests, with
|
|
140
|
+
`cargo update --workspace`, which asks the registry: online, never with
|
|
141
|
+
`--locked`, also under the `locked` option or `NX_RUST_LOCKED=true`. Where
|
|
142
|
+
cargo fails there, for example without network, or offline through
|
|
143
|
+
`CARGO_NET_OFFLINE=true` or `net.offline` with an empty cache, versioning stops
|
|
144
|
+
with cargo's message and commits and tags nothing. The manifests and any
|
|
145
|
+
lockfile already updated stay changed and unstaged. The message prints a
|
|
146
|
+
`git checkout --` command that takes them back, and a
|
|
147
|
+
`(cd <folder> && cargo update --workspace)` command for each failed workspace
|
|
148
|
+
to go on by hand before committing, each on a line of its own and quoted for a
|
|
149
|
+
POSIX shell, to be run in the root of the Nx workspace. Files that git does not
|
|
150
|
+
track are named to be taken back by hand. A workspace without a `Cargo.lock`
|
|
151
|
+
gets none.
|
|
152
|
+
|
|
153
|
+
## Publishing
|
|
154
|
+
|
|
155
|
+
`nx release publish` runs the target `nx-release-publish`, which every crate
|
|
156
|
+
without `publish = false` has, apart from a cargo-hakari hack crate. Nx release
|
|
157
|
+
runs that name only, so `targetNames` cannot rename it.
|
|
158
|
+
|
|
159
|
+
```text
|
|
160
|
+
nx release publish
|
|
161
|
+
core:nx-release-publish ┐
|
|
162
|
+
api:nx-release-publish ├─ rust/ -> cargo publish --locked -p core -p api -p cli
|
|
163
|
+
cli:nx-release-publish ┘
|
|
164
|
+
xtask:nx-release-publish ── tools/xtask/ -> cargo publish --locked -p xtask
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
- Each Cargo workspace of a release group is one `cargo publish` call, or one
|
|
168
|
+
per registry where its crates go to different registries. Cargo orders the
|
|
169
|
+
crates of a call, checks every one of them before it uploads any, and waits
|
|
170
|
+
for each upload to show in the registry's index. Calls run with a
|
|
171
|
+
dependency's call first, and Nx runs release groups with a dependency's
|
|
172
|
+
group first.
|
|
173
|
+
- Before the first call, the plugin checks that each dependency entry on a
|
|
174
|
+
crate of the repository points to the registry that the dependency goes
|
|
175
|
+
to; where one does not, nothing of the release group is uploaded
|
|
176
|
+
([Registries](#registries)).
|
|
177
|
+
- Before each call, the plugin checks every crate of the repository that a
|
|
178
|
+
crate of the call needs as a normal or build dependency and that the call
|
|
179
|
+
does not publish itself: its version must be in the registry that the
|
|
180
|
+
dependency's entry points to already. Otherwise the crate's task fails before anything is
|
|
181
|
+
uploaded and says which dependency to publish first. Cargo alone would
|
|
182
|
+
upload the crate against an older version of the dependency that its
|
|
183
|
+
requirement still accepts.
|
|
184
|
+
- A version that the registry already has is left out with a message, so a
|
|
185
|
+
second run after a partial publish publishes the rest.
|
|
186
|
+
- Every call passes `--locked`, so publishing changes no tracked file outside
|
|
187
|
+
Cargo's build directory, by default `target`, where cargo writes the
|
|
188
|
+
packaged crates as plain `cargo publish` does; don't keep files there that
|
|
189
|
+
git tracks. A stale `Cargo.lock` stops the task before anything is uploaded;
|
|
190
|
+
run `nx release version`, which brings it up to date.
|
|
191
|
+
- The plugin passes no token: cargo uses its own credentials for the registry
|
|
192
|
+
it publishes to ([Registries](#registries)). It never passes
|
|
193
|
+
`--allow-dirty` and does not look at your working tree: whether uncommitted
|
|
194
|
+
changes stop publishing is cargo's own check. Where cargo refuses them, the
|
|
195
|
+
task's output says to commit the versions first.
|
|
196
|
+
- Nx's `--tag`, `--access` and `--otp` are npm's: a task ignores them with a
|
|
197
|
+
line. `--registry` stops each crate's task before cargo runs
|
|
198
|
+
([Registries](#registries)).
|
|
199
|
+
- Do not turn caching on for `nx-release-publish`: a result restored from the
|
|
200
|
+
cache reports success without uploading anything.
|
|
201
|
+
|
|
202
|
+
On Cargo 1.91.0, cargo does not refuse uncommitted changes where the Cargo
|
|
203
|
+
workspace lies in a subfolder of the git repository, which is the usual layout
|
|
204
|
+
of an Nx monorepo; Cargo 1.97.1 to 1.100.0 refuse them, and 1.92 to 1.96 were
|
|
205
|
+
not tried. So commit before you publish, as `nx release` does by default.
|
|
206
|
+
|
|
207
|
+
### Registries
|
|
208
|
+
|
|
209
|
+
Cargo chooses where a crate goes, as plain `cargo publish` does. Before each
|
|
210
|
+
call the plugin asks cargo which registry that is, and then names it to cargo,
|
|
211
|
+
so that its checks look where cargo uploads.
|
|
212
|
+
|
|
213
|
+
| Setting | Where the crate goes |
|
|
214
|
+
| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
|
|
215
|
+
| `CARGO_REGISTRY_DEFAULT=my-registry` in the environment, or `registry.default` in `.cargo/config.toml` | There; a crate whose `publish` list leaves that registry out is refused |
|
|
216
|
+
| `publish = ["my-registry"]` in the crate's `Cargo.toml`, and no default | `my-registry` |
|
|
217
|
+
| None of these | crates.io |
|
|
218
|
+
|
|
219
|
+
Tokens come from cargo's credentials too. For a registry other than
|
|
220
|
+
crates.io, use `cargo login --registry my-registry`,
|
|
221
|
+
`CARGO_REGISTRIES_MY_REGISTRY_TOKEN` or a credential provider.
|
|
222
|
+
`CARGO_REGISTRY_TOKEN` holds crates.io's token only. Plain `cargo login` saves
|
|
223
|
+
the token for the registry that `registry.default` names, and for crates.io
|
|
224
|
+
only where none is named.
|
|
225
|
+
|
|
226
|
+
Each entry of a dependency on another crate of the repository that is
|
|
227
|
+
published elsewhere than crates.io has to name that registry, in
|
|
228
|
+
`[workspace.dependencies]` where the entry inherits it:
|
|
229
|
+
|
|
230
|
+
```toml
|
|
231
|
+
[dependencies]
|
|
232
|
+
core = { path = "../core", version = "0.3.0", registry = "my-registry" }
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Without the key, the published crate depends on crates.io's crate of that
|
|
236
|
+
name, whatever registry both crates go to, also where your Cargo
|
|
237
|
+
configuration puts that registry in place of crates.io: a replacement changes
|
|
238
|
+
where cargo looks on your machine, not what it writes into the crate. The
|
|
239
|
+
plugin stops the release group before anything of it is uploaded and names
|
|
240
|
+
the entry to change. Cargo refuses a manifest whose `registry` key names no configured
|
|
241
|
+
registry, so configure the registry wherever the workspace is built.
|
|
242
|
+
|
|
243
|
+
A dotenv file in a crate's folder can give that crate's task settings of
|
|
244
|
+
its own, such as `CARGO_REGISTRY_DEFAULT`. The plugin therefore works out
|
|
245
|
+
where a dependency goes with the environment of the dependency's own task,
|
|
246
|
+
the one its upload uses. Where a crate's dependency entry points to another
|
|
247
|
+
registry than the one its dependency goes to, or where the plugin cannot
|
|
248
|
+
tell, the release group stops before anything of it is uploaded, and the
|
|
249
|
+
message names both crates, both registries and where each setting comes
|
|
250
|
+
from:
|
|
251
|
+
|
|
252
|
+
```text
|
|
253
|
+
core:nx-release-publish: core depends on base through the entry in rust/Cargo.toml, which points to the registry `alpha`, while base is published to the registry `beta`, which CARGO_REGISTRY_DEFAULT chooses in the environment of base:nx-release-publish, set by rust/crates/base/.env, and @convesoft/nx-rust cannot establish that these are one registry: …
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Every other crate of the group fails with it and says that nothing of the
|
|
257
|
+
run was uploaded. Nx publishes release groups one after another, so the
|
|
258
|
+
check covers one group at a time: a group that Nx published before stays
|
|
259
|
+
published, with its crates where their own settings sent them, and the
|
|
260
|
+
group that the check stops is not uploaded. The plugin cannot rebuild the
|
|
261
|
+
environment of a task that it does not run itself: without a batch, as with
|
|
262
|
+
`NX_BATCH_MODE=false`, where each task runs on its own, and for a dependency
|
|
263
|
+
in another release group or outside the run. There, a crate and a crate
|
|
264
|
+
that it depends on whose dotenv files give different Cargo settings stop
|
|
265
|
+
the release, also where the settings would agree. For a dependency outside
|
|
266
|
+
the run, every configuration of its `nx-release-publish` target, and none,
|
|
267
|
+
must give the same Cargo settings, because the plugin cannot tell with which
|
|
268
|
+
of them it was published. Keep such settings in the environment of the command
|
|
269
|
+
or in `.cargo/config.toml`, or publish the crates in one run with batches,
|
|
270
|
+
as `nx release publish` does by default.
|
|
271
|
+
|
|
272
|
+
A crate's dotenv files go through the same check as for the cargo targets
|
|
273
|
+
([Dotenv files](execution.mara.md#dotenv-files)), with a batch and without
|
|
274
|
+
one. A value that refers to a variable whose value Nx sets differently
|
|
275
|
+
depending on how the task runs, such as
|
|
276
|
+
`CARGO_REGISTRY_DEFAULT=team-${NX_TASK_TARGET_CONFIGURATION}` in
|
|
277
|
+
`.env.nx-release-publish`, fails the crate's task before cargo runs, and
|
|
278
|
+
nothing is uploaded for it:
|
|
279
|
+
|
|
280
|
+
```text
|
|
281
|
+
base:nx-release-publish: rust/crates/base/.env.nx-release-publish makes Nx look up NX_TASK_TARGET_CONFIGURATION where it expands CARGO_REGISTRY_DEFAULT, and NX_TASK_TARGET_CONFIGURATION has a value there that depends on how the task runs: …
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Without a batch, where that crate depends on another crate of the
|
|
285
|
+
repository, the other crates of the run stop as well, as described above for
|
|
286
|
+
dotenv files with different Cargo settings. Name the registry itself in the
|
|
287
|
+
file, or refer to a variable that you set in the environment of the command.
|
|
288
|
+
|
|
289
|
+
The plugin publishes a crate only where cargo's own output shows that the
|
|
290
|
+
checks before the upload asked the registry that the upload goes to.
|
|
291
|
+
Otherwise it stops the crate, and the crates that depend on it, before
|
|
292
|
+
anything is uploaded, and says what it could not tell. Configure Cargo
|
|
293
|
+
plainly:
|
|
294
|
+
|
|
295
|
+
- One name for each registry, and the same name in every Cargo workspace.
|
|
296
|
+
- No source replacement for the registry you publish to. On a machine whose
|
|
297
|
+
configuration replaces crates.io, such as with a mirror, publish to
|
|
298
|
+
crates.io from a job whose configuration does not.
|
|
299
|
+
- Where a crate depends on a crate of another Cargo workspace of the
|
|
300
|
+
repository on a registry other than crates.io, give that registry's index
|
|
301
|
+
in the environment, as `CARGO_REGISTRIES_MY_REGISTRY_INDEX`, so that it is
|
|
302
|
+
the same for every workspace.
|
|
303
|
+
- Publish online: offline, cargo does not say which registry it asked, and
|
|
304
|
+
it refuses to publish anyway.
|
|
305
|
+
|
|
306
|
+
`nx release publish --registry` is npm's flag: Nx hands the same value, for
|
|
307
|
+
npm a URL, to every publish task, and cargo needs the name of a registry from
|
|
308
|
+
its configuration. A crate's task that receives it stops before cargo runs and
|
|
309
|
+
says how to choose the registry instead; so does a `registry` from a
|
|
310
|
+
`project.json` or from a `targetDefaults` entry. To publish to another
|
|
311
|
+
registry for one run, set the variable instead:
|
|
312
|
+
|
|
313
|
+
```sh
|
|
314
|
+
CARGO_REGISTRY_DEFAULT=my-registry nx release publish
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
In a repository that also publishes npm packages, give the registry to those
|
|
318
|
+
alone: publish them in a run of their own, such as
|
|
319
|
+
`nx release publish --groups npm-packages --registry https://npm.example.com/`,
|
|
320
|
+
set it in `.npmrc`, or put it in a `targetDefaults` entry keyed by
|
|
321
|
+
`@nx/js:release-publish`, which reaches npm packages only. An entry keyed by
|
|
322
|
+
`nx-release-publish` reaches crates as well, unless `nx.json` has the empty
|
|
323
|
+
entry keyed by `@convesoft/nx-rust:release-publish` that `init` adds.
|
|
324
|
+
|
|
325
|
+
### What a dry run shows
|
|
326
|
+
|
|
327
|
+
`nx release publish --dry-run` packages and checks each crate as cargo would
|
|
328
|
+
upload it, uploads nothing and changes no tracked file outside Cargo's build
|
|
329
|
+
directory. Within one cargo call, cargo
|
|
330
|
+
checks a crate against the new versions of the other crates of the call. It
|
|
331
|
+
cannot do that across calls: a crate whose dependency's new version another
|
|
332
|
+
call would publish, for a crate of another Cargo workspace, registry or
|
|
333
|
+
release group, is not handed to cargo. Its task succeeds and says that the
|
|
334
|
+
crate was not checked, naming the dependency, its version and the task that
|
|
335
|
+
would publish it. A dry run proves neither what crates.io itself checks on
|
|
336
|
+
upload nor how fast its index is.
|
|
337
|
+
|
|
338
|
+
A dry run of `nx release version` or of `nx release` writes no versions, so
|
|
339
|
+
check publishing with `nx release publish --dry-run` after the new versions
|
|
340
|
+
are committed.
|
|
341
|
+
|
|
342
|
+
### Dependencies that are not published
|
|
343
|
+
|
|
344
|
+
A crate that depends, with a version requirement, on a crate of the
|
|
345
|
+
repository that is not published to the registry that the dependency's entry
|
|
346
|
+
points to, through `publish = false` or a `publish` list without that registry, cannot be
|
|
347
|
+
published as it is: cargo packages the dependency for that registry, where it
|
|
348
|
+
fails to resolve or resolves to an unrelated crate of the same name.
|
|
349
|
+
Publishing such a crate stops before cargo runs, in a dry run too, and so do
|
|
350
|
+
the crates of its cargo call that depend on it:
|
|
351
|
+
|
|
352
|
+
```text
|
|
353
|
+
core:nx-release-publish: core depends on internal through the entry in rust/Cargo.toml, which points to the registry `my-registry`, and internal is not published there: rust/crates/internal/Cargo.toml sets `publish = false`. Nothing was uploaded for core: …
|
|
354
|
+
To publish it, publish internal to the registry `my-registry` as well, by removing `publish = false` from its manifest; or make internal no normal or build dependency of core.
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Where the dependency has a `publish` list, the message also offers to point
|
|
358
|
+
the entry's `registry` key at a registry of that list.
|
|
359
|
+
|
|
360
|
+
The plugin never publishes the hack crate of
|
|
361
|
+
[cargo-hakari](https://docs.rs/cargo-hakari), the crate that
|
|
362
|
+
`hakari-package` in `.config/hakari.toml` names, whatever
|
|
363
|
+
`featureUnification` says. `cargo hakari init` writes it with
|
|
364
|
+
`publish = false`, and `cargo hakari manage-deps` gives every other member a
|
|
365
|
+
dependency on it with a version requirement, so each crate that you publish
|
|
366
|
+
stops with the message above, which then adds the two ways that cargo-hakari
|
|
367
|
+
offers:
|
|
368
|
+
|
|
369
|
+
- publish a stub of the hack crate once under a name of your own and without
|
|
370
|
+
`publish = false`, after which your crates publish normally;
|
|
371
|
+
- or publish such a crate with `cargo hakari publish -p <crate>` outside Nx.
|
|
372
|
+
|
|
373
|
+
The plugin does not publish the stub either: until its version is in the
|
|
374
|
+
registry, the crates that depend on it stop and say to publish it once.
|
|
375
|
+
|
|
376
|
+
## What is not part of it
|
|
377
|
+
|
|
378
|
+
- Publishing the napi and wasm packages to npm ([[ADR-V1-SCOPE]]).
|
|
379
|
+
- Reading current versions from the registry.
|
|
380
|
+
- Installing cargo-hakari, cargo-edit or any other tool.
|
|
381
|
+
|
|
382
|
+
## Requirements
|
|
383
|
+
|
|
384
|
+
:::mara requirement REQ-RELEASE
|
|
385
|
+
:mid: 01M78FHG7F358GRCJTK5Y6AQMR
|
|
386
|
+
:title: Version and publish crates through Nx release
|
|
387
|
+
:status: accepted
|
|
388
|
+
:satisfies: NEED-RELEASE
|
|
389
|
+
|
|
390
|
+
`nx release version` versions crates in their `Cargo.toml`. It bumps a crate's version, also one that the crate inherits from `[workspace.package]`, and bumps the crates that depend on a bumped crate through a normal or build dependency with a version requirement. Crates that share an inherited version are versioned together, and a configuration that would version them apart fails before anything is written. It updates every version requirement on a bumped crate in the repository's Cargo workspaces, in `[workspace.dependencies]` and in crates outside the release too, so that each workspace still resolves, and it brings the `Cargo.lock` of each workspace whose manifests changed, or which locks a bumped crate by path, up to date without moving any other locked package. It stops where a crate of the release would get a rewritten requirement on a bumped crate without a new version of its own, and where a place that names a bumped crate with a version would stop working with the new version and cannot be rewritten. Every check of `nx release version` runs before it writes its first file, so a run that a check stops changes no file; a failure while the files are written, which no check foresees, and a failure of cargo while it brings the lockfiles up to date, which runs after the files are written, can leave some of them changed and unstaged, and the latter says how to take them back or finish the release.
|
|
391
|
+
|
|
392
|
+
`nx release publish` publishes the selected crates with `cargo publish`, each to the registry that Cargo's own settings choose for it. It never uploads a crate while a crate of the repository that it needs as a normal or build dependency lacks its version in the registry that the dependency's entry points to: such a crate, unless the same cargo call publishes the dependency, fails before anything is uploaded and says which dependency to publish first. Where the registry that a crate's dependency entry points to cannot be established as the registry that the dependency is published to, in the environment of the dependency's own task, nothing of the run is uploaded, and the message names both crates and both registries and says where each setting comes from; a run of `nx release publish` publishes one release group after another, so a group that it published before keeps its crates where their own settings sent them, while the group that the check stops is not uploaded. It leaves out a crate whose version the registry already has, never publishes a crate with `publish = false` or a [[TERM-HACK-CRATE]], and fails before anything is uploaded for a crate that depends, with a version requirement, on a crate of the repository that is not published to the registry that the dependency's entry points to, saying why and how to change that and, for a hack crate, how such a crate can be published. A crate's task that receives Nx's `registry` option fails before anything is uploaded and says how Cargo chooses a registry instead. Publishing changes no tracked file outside Cargo's build directory.
|
|
393
|
+
|
|
394
|
+
A dry run of `nx release version` writes nothing, and a dry run of `nx release publish` uploads nothing and changes no tracked file outside Cargo's build directory. The dry run of `nx release publish` checks each crate that would be published against the registry and against the new versions of the other crates of its cargo call, and reports each crate that it could not check because another call would publish the new version of one of its dependencies. Publishing napi and wasm packages to npm is not part of it ([[ADR-V1-SCOPE]]).
|
|
395
|
+
:::
|
|
396
|
+
|
|
397
|
+
## Design
|
|
398
|
+
|
|
399
|
+
:::mara design DES-RELEASE
|
|
400
|
+
:mid: 01M78FHG7F65ZV4NB8NPNJGH1T
|
|
401
|
+
:title: Release flow
|
|
402
|
+
:status: accepted
|
|
403
|
+
:satisfies: REQ-RELEASE
|
|
404
|
+
:mitigates: RISK-UNCOMMITTED-PUBLISH
|
|
405
|
+
|
|
406
|
+
Nx release works out the bumps, walks dependents, writes changelogs and makes the commit, tag and push itself. The plugin adds the version actions for `Cargo.toml`, the lockfile step, the target `nx-release-publish` with its executor, and the checks before each publish call ([[EVD-NX-24-RELEASE]], [[EVD-NX-24-VERSION-ACTIONS]]). The maintainer chose the four answers that had real alternatives on 14 November 2026: one `cargo publish` per workspace ([[ADR-BATCHED-PUBLISH]]), one fixed release group for an inherited version, dependents from the manifests with requirements rewritten everywhere ([[ADR-RELEASE-DEPENDENTS]]), and an early failure for the hack crate. The control plane of the work settled the rest the same day from the measured facts ([[EVD-CARGO-PUBLISH]]): how requirements are rewritten, the lockfile step, and that npm publishing of napi and wasm packages stays out ([[ADR-V1-SCOPE]]). After a review of this design, the control plane decided the same day, and the maintainer is told: the check that a dependency's version is in the registry before a crate is uploaded, the dry run's limit across cargo calls, `--locked` on every publish call, what happens to a compound requirement that still matches, and the early failure for every dependency that is not published, which extends the maintainer's answer for the hack crate. The research on Nx's `--registry` (nxr-fwxn1r) brought the maintainer's choice, the same day, that a crate's task fails on Nx's `registry` option with guidance ([[ADR-PUBLISH-REGISTRY-OPTION]]), and three decisions of the control plane, of which the maintainer is told: the checks compare the registry that a dependency's entry points to with the registry the dependency is published to (**Where a dependency points**), the calls are split by registry as well ([[ADR-BATCHED-PUBLISH]]), and the executor learns that registry from cargo and names it to cargo (**Target registry**) ([[EVD-CARGO-PUBLISH-REGISTRIES]]). A review the same day corrected the first and the probe of the second, and after a second review the control plane put every registry question under one principle (**Registries**); the maintainer is told. The maintainer chose the same day that a crate that would publish to crates.io fails where the Cargo configuration replaces crates.io ([[ADR-PUBLISH-REPLACED-CRATES-IO]]). On 20 November 2026 (nxr-4884vg) the maintainer overturned the control plane's provisional answer, which left dotenv files that give the crates of one release different registry settings unsupported and said so in the release guide only: an upload cannot be undone, so a dependency's target registry is established in the dependency's own environment, and the release fails early where the tasks of one release disagree (**A dependency's environment**, **Checks before the first call**). The control plane settled the rest within that direction the same day, and the maintainer is told: that the early failure stops every task of the run, which Cargo settings count, how a dependency whose task the executor does not run is treated, and that every _Dependencies published elsewhere_ failure stops the run. On 21 November 2026 (nxr-c63t0r) the maintainer decided that each task runs the dotenv check of the cargo executors before cargo runs (**Dotenv files**).
|
|
407
|
+
|
|
408
|
+
**Registration.** Each crate's project carries `release.version.versionActions`, which names the plugin's version actions through its package, `@convesoft/nx-rust/src/release/version-actions`, so that Nx resolves them from the repository root and every checkout gives the project the same configuration. `createNodes` sets it as Nx allows for a project's `release.version`, and Nx takes it ([[EVD-NX-24-VERSION-ACTIONS]]), so neither `nx.json` nor `@nx/js` is needed for them. The workspace project of a root manifest without a `[package]` table carries none: it has no version, and the user leaves it out of the release projects. The version actions find a project's crate through its `metadata.cargo`, the package name and manifest ([[DES-PROJECT-GRAPH]]), because the Nx name can differ from the package name. They read the repository's Cargo workspaces, those whose root manifest a project of the graph names, from one `cargo metadata --no-deps` report each, started in the workspace's root folder ([[DES-INVOCATION]]).
|
|
409
|
+
|
|
410
|
+
**Current version.** The version actions read the current version from the crate's manifest, following `[workspace.package].version` where the crate inherits it, which is what Nx's default `disk` resolver asks for. `git-tag` works as Nx provides it. The `registry` resolver is not supported in v1: a project of the release whose `currentVersionResolver` is `registry` fails versioning with a message that says so and names `disk` and `git-tag`. A crate in the release whose manifest has no `version`, which cargo reports as 0.0.0, or which inherits a version that `[workspace.package]` does not set, fails versioning with a message that names the manifest. Both checks run when Nx loads the version actions, for every project configured for release, because Nx replaces an error from reading a current version with a message of its own, which in both cases would point elsewhere ([[EVD-NX-24-VERSION-ACTIONS]]).
|
|
411
|
+
|
|
412
|
+
**Inherited versions.** Crates of one Cargo workspace that inherit `version.workspace = true` share one version. They are versioned together or not at all: they must be in one fixed release group, and a release configuration that puts them into different groups, or a run that would version some of them and not others, fails before anything is written, with a message that names the crates and the groups. The version actions check the groups when Nx validates the run, and the run when they write the version, because Nx adds a crate to a run as a dependent of a crate in another group without the rest of its group ([[EVD-NX-24-VERSION-ACTIONS]]). The version is written once, to `[workspace.package].version`; where Nx bumps a crate twice in one run, first as a dependent and then by its group's own bump, as it does for the crates of a fixed group that depend on a crate of an independent group bumped in the same run, the last version stays, as it does for a version of a crate's own ([[EVD-NX-24-VERSION-ACTIONS]]). The maintainer's option, word for word: "Require one fixed release group (Recommended)". Rejected: independent groups that silently move every crate inheriting the version, whose versions would then change without Nx's tags and changelogs; and no support for inherited versions, as in `@monodon/rust` 3.0.0, which blocks a common layout ([[EVD-NX-24-RELEASE]]). The rule binds only crates that share an inherited version: a crate with a version of its own can be in another release group than a crate it depends on.
|
|
413
|
+
|
|
414
|
+
**Dependents.** The version actions read a crate's dependencies from its workspace's `cargo metadata --no-deps` report ([[DES-METADATA-REPORT]]), not from the project graph, whose `implicit` edges are a superset kept for the cache key ([[ADR-RELEASE-DEPENDENTS]]). Nx release takes dependents only from what the version actions report ([[EVD-NX-24-RELEASE]]). A dependency makes the crate a dependent of the crate it names when it names, by path, a crate with an Nx project, is of kind normal or build, and carries a version requirement, in its own entry or in the `[workspace.dependencies]` entry it inherits. The report gives the requirement `*` both for an entry without a version requirement and for the requirement `*` written out ([[EVD-CARGO-PUBLISH]]), so the version actions read the manifest to tell the two apart. They find the dependency's entries there by its kind, its key, which is the rename where it has one, and the folder that it names, its own path or that of the `[workspace.dependencies]` entry it inherits, not by the platform of its target table, which cargo's report writes normalised, so that `cfg( unix )` in a header is `cfg(unix)` in the report; where entries in several target tables name the crate, a requirement in any of them counts. Where the manifest holds no such entry, versioning fails before anything is written, with a message that names the manifest and the dependency. Optional, renamed and target-specific dependencies count. The path identifies the crate at the real path of its folder, as in [[DES-PROJECT-GRAPH]], and a crate of another workspace is found in that workspace's report. Dev-dependencies make no dependent, by the maintainer's choice: the crates that use a crate never build its dev-dependencies, although cargo keeps a dev-dependency with a version requirement in the published manifest. Dependencies without a version requirement make no dependent either: cargo leaves such a dev-dependency out of the published crate and refuses to publish a crate with such a normal dependency ([[EVD-CARGO-PUBLISH]]). Under Nx's default `updateDependents`, each dependent gets a patch bump.
|
|
415
|
+
|
|
416
|
+
Nx decides two kinds of bump across release groups without the reported dependencies ([[EVD-NX-24-VERSION-ACTIONS]]), which show only where groups take their bumps from conventional commits or version plans: with a specifier on the command line, every crate of the run gets it. The maintainer answered both on 14 November 2026 (nxr-5a9w1y), with the options chosen, word for word:
|
|
417
|
+
|
|
418
|
+
- A fixed release group that gets no bump of its own is bumped as a whole through any edge of the project graph to a project of a group that Nx bumped before it, the plugin's `implicit` edges included, so also through a dev-dependency or an edge that the plugin adds for the cache key, and whether it happens depends on the order of the groups in `nx.json`. "Accept it and say so in the output (Recommended)": the run goes on, and for each project of the group that has such an edge, the output names the group, the edge and what it is in Cargo, a normal, build or dev-dependency or no dependency at all, and calls it a known limit of Nx release. The version actions know it from the reason `DEPENDENCY_ACROSS_GROUPS_WAS_BUMPED` with which Nx asks the project's `calculateNewVersion` for its version, right before its `updateProjectVersion`, and they name the project's edges into release groups in which the run has written a version by then. Nx judges a group bumped by the first of its projects in the run, so where several groups are involved, the line can name an edge into a group of which Nx counted another project; where the project has no such edge, the line names the group without an edge. Rejected: stopping such a run.
|
|
419
|
+
- A crate in an independent group that depends, through a normal or build dependency with a version requirement, on a crate of a fixed group is not bumped when Nx bumps that group as a whole, unless its own group bumps it, while its requirement is rewritten. "Stop such a run before anything is written (Recommended)": versioning fails, naming each crate whose requirement would change without a bump and its release group, and says to release it in the same run. Rejected: accepting it. The version actions check it once every version of the run is decided and before Nx writes anything: Nx calls `updateProjectDependencies` for each crate whose version the run writes only after its last version decision, and the first of these calls checks every requirement that the run rewrote in a normal or build dependency table, or in a `[workspace.dependencies]` entry for each member that inherits it there, against the crates whose versions the run writes. The check covers every crate configured for release whose requirement the run rewrites without a bump, so it also stops a run in which `updateDependents` is `never`, or `auto` across groups, keeps Nx from bumping such a crate; the maintainer confirmed this on 14 November 2026, word for word: "Yes, stop in every such run (Recommended)". Rejected: following `updateDependents`. A crate outside the release and a dev-dependency stay as **Requirements** says: their requirements are rewritten without a bump.
|
|
420
|
+
|
|
421
|
+
**Requirements.** When a crate's version changes, every version requirement on it, matched by path, is updated in every manifest of the repository's Cargo workspaces that the plugin reads, at the moment the version actions write the crate's new version, because Nx asks for the dependency updates of crates in the release only: in each member's dependency tables of every kind and their `[target.*]` forms, whether the member is released or not and whether it has an Nx project or not, in each root manifest's `[workspace.dependencies]` and `[patch.<source>]` tables, and in the `[patch.<source>]` tables of the Cargo configuration files that cargo reads for each workspace ([[DES-METADATA-REPORT]]). A dependency that inherits its entry with `workspace = true` is updated where the requirement is written, in `[workspace.dependencies]`. A `[patch]` entry that names a bumped crate by path and carries a version requirement is a requirement on that crate: cargo fails once the crate's new version leaves it ([[EVD-CARGO-PATCH-AFTER-BUMP]]), so it is rewritten, kept or fails versioning by the same rules as any other, and it never makes a dependent or bumps a crate; the control plane decided this on 14 November 2026, within the maintainer's "rewrite everywhere". Cargo ignores `[patch]` in a member's manifest, and so do the version actions. No file outside the repository is written: a requirement there that has to change, as in the Cargo home's configuration, fails versioning with a message that names the file. Three more places can name a bumped crate with a version, and each fails versioning before anything is written, with a message that names the file and says what to do, where the new version would leave it ([[EVD-CARGO-PATCH-AFTER-BUMP]]): a `[replace]` entry whose path names the crate, because cargo takes a replacement only with the version it replaces and fails after the bump, while a key rewritten to the new version leaves the replacement unused; a registry or git requirement that a `[patch]` entry naming the crate by path redirects to it, which the old version satisfied and the new one does not, because cargo would take the package from the registry instead without an error; and a profile's package table whose specification names the crate with a version, as `base@0.1.0`, `base:0.1.0`, `base@0.1` and the forms `path+file://` and `file://` of the crate's folder with `#base@0.1.0` or `#0.1.0`, because the profile's settings would stop applying to it with a warning only. The version actions take a `[patch.<source>]` table to apply to a registry or git dependency where the key is `crates-io` and the dependency comes from crates.io; where the key is a URL that names the dependency's git repository or registry index as cargo compares them, with `sparse+` kept for a sparse index; or where the key is a registry's name that `CARGO_REGISTRIES_<NAME>_INDEX` or the `[registries]` table of the workspace's Cargo configuration maps to the dependency's index, or that the dependency's entry names. A name that none of these maps or names is not matched. So after a run that succeeds, every place in the repository's manifests and in the Cargo configuration that names a bumped crate with a version accepts its new version, and cargo resolves every Cargo workspace of the repository as before, as far as the bumped crates go. For the redirected registry requirement, the maintainer chose on 14 November 2026 (nxr-6kmd0d), word for word: "Keep stopping the run (Recommended)". Rejected: rewriting it like any other requirement, although cargo then takes the member again ([[EVD-CARGO-PATCH-AFTER-BUMP]]). A requirement that the new version satisfies is kept while Nx's `preserveMatchingDependencyRanges` is on, its default; the setting that counts is that of the crate whose manifest holds the requirement, where that crate is configured for release, and otherwise, as in `[workspace.dependencies]`, that of the crate whose version changes. With it off, a bare, `^`, `~` or `=` requirement is rewritten to the new version. Any requirement that the new version leaves is rewritten to the new version with its operator kept, where it has one of these forms. A requirement of another form, such as a comparison or a wildcard, is kept unchanged as long as the new version satisfies it, also with `preserveMatchingDependencyRanges` off, and the output says so, naming the manifest and the requirement: the plugin rewrites only the forms that it can rewrite without inventing bounds, and a requirement that still matches needs no change to stay correct. Such a requirement that the new version leaves fails versioning before Nx writes any file, with a message that names the manifest, the dependency and the requirement. The control plane decided the case of a matching compound requirement on 14 November 2026 after the review. Nx's `versionPrefix` has no effect, because a rewritten requirement keeps its operator, and neither has `manifestRootsToUpdate`: the version actions write the crates' own manifests. Only version strings change in a manifest. The version actions replace the characters of each version string in the manifest's text, between the string's own quotes, at the place that a scanner of their own finds for its key, and refuse the edit, before Nx writes anything, unless the edited text, parsed by smol-toml, differs from the old one in exactly those values. So comments, layout, the order of keys, quoting, line endings and a missing final newline stay byte for byte. A TOML package that writes the document anew was not taken: smol-toml keeps no layout, `@ltd/j-toml`, which `@monodon/rust` uses, reformats the file ([[EVD-NX-24-RELEASE]]), and a package that reports places would be a new dependency for finding a few strings. The version actions list every manifest and configuration file that they change in their `manifestsToUpdate`, which is how Nx excludes a file from its formatting pass, so that a formatter that formats TOML, such as oxfmt, leaves them alone ([[EVD-NX-24-VERSION-ACTIONS]]). Failing on every requirement that the new version leaves, as `@nx/js` does for npm ranges, was not taken: every Cargo requirement is a range, so it would block every breaking release ([[EVD-NX-24-RELEASE]]).
|
|
422
|
+
|
|
423
|
+
**Writes.** Nx keeps the changes of a run in its tree and writes them once every release group is processed, without a way back ([[EVD-NX-24-VERSION-ACTIONS]]). Every check of the version actions runs before that, so a failure of a check leaves every file as it was. Among the checks is one that every file that the run changes, the lockfiles that the lockfile step will update among them, lies inside the repository and can be written. A file is inside the repository when its real path, with the symbolic links of the file and of every folder on its way followed, lies within the real path of the repository root; a file whose path lies inside but which a link leads outside, such as a `.cargo/config.toml` that links elsewhere or the manifest of a member whose folder is a link, fails the run before any write, with a message that names the file and where it leads. A file whose path lies outside the repository is never written (**Requirements**). Inside the repository, the version actions read and write each file in Nx's tree at its real path, relative to the real path of the repository root, and list that path in `manifestsToUpdate`: Nx stages the paths that its tree changed, and git keeps a link apart from the file that it leads to, so a write through the path of a link, such as a member's `Cargo.toml` that links to a file elsewhere in the repository, would change that file and leave it out of the commit ([[EVD-NX-24-VERSION-ACTIONS]]). The link stays as it is. Only a file that does not exist is absent: a manifest or configuration file that exists but cannot be read, for a missing permission or because it is a folder, fails the run before any write with a message that names it and the reason. Nx's tree answers as for a missing file wherever it cannot read one ([[EVD-NX-24-VERSION-ACTIONS]]), so the version actions read such a file from disk once more to tell. A Cargo configuration file that cannot even be looked at, in a `.cargo` folder that may not be searched, counts as absent, as it does for cargo, which fails on one that it finds and cannot read ([[EVD-CARGO-LOCKFILE-UPDATE]]). A failure while Nx writes, such as a disk that is full or a file that becomes read-only meanwhile, can still leave some files changed and unstaged, without a commit or tag; `git checkout` undoes them ([[RISK-NX-RELEASE]]). So can a failure of the lockfile step, which runs after Nx has written the files: it leaves them and the lockfiles that cargo updated before it changed and unstaged, without a commit or tag, and its message lists them (**Lockfile**, [[EVD-CARGO-LOCKFILE-UPDATE]]).
|
|
424
|
+
|
|
425
|
+
**Lockfile.** The version actions module exports `afterAllProjectsVersioned`, which Nx calls once after it has written the files of the run and before it stages and commits them ([[EVD-NX-24-VERSION-ACTIONS]]). It runs `cargo update --workspace` in the root folder of each Cargo workspace whose lockfile the run makes stale ([[DES-INVOCATION]]): each workspace whose manifests or Cargo configuration files the version actions changed, and each workspace whose `Cargo.lock` locks a bumped crate as a path package at its old version, such as one whose member depends on it by path without a version requirement, whose manifests stay as they are, and whose lockfile cargo's `--locked` would refuse ([[EVD-CARGO-LOCKFILE-UPDATE]]); a lockfile names no path, so another path crate of the same name and version only costs an update that changes nothing. The control plane accepted this second kind of workspace on 14 November 2026, and the maintainer is told. A workspace without a `Cargo.lock` gets none: the step runs nothing there, although `cargo update` would write one ([[EVD-CARGO-LOCKFILE-UPDATE]]), because the step exists to keep an existing lockfile current, and where none exists nothing can be stale; a user who wants a lockfile runs cargo once. The control plane decided this on 14 November 2026 (nxr-4717pj), and the maintainer is told. Rejected: creating the lockfile. Only a lockfile that does not exist is absent: a lockfile of any workspace of the repository that exists but cannot be read, or is no valid TOML, fails the run before any write, with a message that names it and the reason, because the version actions can then tell neither whether the run makes it stale nor bring it up to date. The step runs online, without `--offline`, because `--offline` fails with an empty Cargo home as on CI, and never with `--locked`, also in locked mode, because the lockfile has to change, as for the `update` target ([[DES-WORKSPACE-TARGETS]]); it runs with the environment of the command, so an environment or configuration that forces cargo offline applies, and cargo fails where its cache does not hold what it needs. Cargo then changes the bumped members' entries and the references in other entries' dependency lists that spell out a version or a source, and moves no other locked package ([[EVD-CARGO-PUBLISH]], [[EVD-CARGO-LOCKFILE-UPDATE]]). The function returns the lockfiles that cargo changed and that git does not ignore, each at its real path relative to the repository root (**Writes**), because cargo writes through a lockfile that is a link and leaves the link as it is, which Nx stages, and commits with the manifests where the git settings of `nx release version` ask for a commit or the command is `nx release` ([[EVD-NX-24-RELEASE]]); Nx itself also leaves out what git ignores. The version actions check the lockfiles that the step will write with the other files, before Nx writes anything (**Writes**). The step goes through the workspaces in the order of their lockfiles' paths and on after a failure, and when cargo has failed in any of them, the release fails with a message that names each such workspace and carries cargo's message, says which files Nx wrote and which lockfiles cargo updated, at their real paths, and prints the commands that go back, `git checkout --` with those of the files that git tracks, or on, `(cd <folder> && cargo update --workspace)` for each failed workspace, to run once cargo works before committing and tagging the release by hand; Nx makes no commit or tag. Each command is on a line of its own, to be run in the root of the Nx workspace, with each path quoted for a POSIX shell as the verbose cargo command quotes its words ([[DES-INVOCATION]]), with `--literal-pathspecs` where a path holds a character that git reads as a pattern, and with `./` before a folder that starts with `-`. The files that git does not track, which `git checkout` refuses together with the rest, are named to be taken back by hand. A lockfile that can no longer be read when the step reaches it fails the same way. In a dry run it runs nothing, because Nx has written nothing. Release may write the lockfile ([[REQ-NO-MANIFEST-WRITES]], [[ADR-V1-SCOPE]]). `@monodon/rust` 3.0.0 runs the update in the Nx root only and swallows its failures ([[EVD-NX-24-RELEASE]]); a workspace elsewhere would keep a stale lockfile.
|
|
426
|
+
|
|
427
|
+
**Publish target.** Every crate without `publish = false`, other than the hack crate, has the target `nx-release-publish`. Nx release runs that name only ([[EVD-NX-24-RELEASE]]), so `targetNames` does not apply to it ([[DES-TARGETS]], [[DES-PLUGIN-OPTIONS]]). The target is not cached ([[DES-OUTPUTS]]) and has no `dependsOn` ([[REQ-NO-RUST-TASK-DEPS]]). It runs the executor `@convesoft/nx-rust:release-publish`, which declares a batch implementation and `preferBatch: true` ([[ADR-BATCH-EXECUTOR]], [[ADR-BATCHED-PUBLISH]]).
|
|
428
|
+
|
|
429
|
+
**Batch.** `nx release publish` runs one release group after another, in the order of the dependencies that the version actions report, so a batch holds the runnable `nx-release-publish` tasks of one group ([[EVD-NX-24-RELEASE]]). The batch implementation runs one `cargo publish --locked` per Cargo workspace and target registry (**Target registry**), started in the workspace root, with the registry as **Target registry** names it and a `-p` and the real package name for each crate of its tasks that the checks below leave in ([[DES-INVOCATION]]). Crates of one workspace that cargo publishes to different registries go into separate calls, because one call for crates whose `publish` settings differ fails as a whole, while plain cargo publishes each of them alone ([[ADR-BATCHED-PUBLISH]], [[EVD-CARGO-PUBLISH-REGISTRIES]]). Cargo orders those crates, packages and verifies each against the others before it uploads any, waits after each upload until the registry's index lists it, and stops rather than publish a crate after the wait for one it depends on has timed out ([[EVD-CARGO-PUBLISH]]). The calls run one after another, a call after those whose crates its crates depend on with a version requirement, in another workspace or for another registry of the same one, so that a dependency is in the registry when the call of its dependents is checked. Where such dependencies form a cycle between calls, no order satisfies cargo, and the checks or cargo fail the call that cannot resolve. Cargo's output is mapped to one result per task: a task succeeds where cargo's output shows that its crate was uploaded, `Uploaded <name> v<version>`, or in a dry run verified, a `Verifying` of it that reached `Finished` or an `Uploading` of it, whatever the exit status of the call, and fails otherwise, with a message that says that cargo's output does not show it; so where a call fails after it verified or uploaded some of its crates, their tasks succeed, and a second run leaves out the versions that the registry then has (**Existing versions**). The control plane settled this on 15 November 2026 after the review of nxr-m8evx2, where the first version took a dry run's results from the exit status of the call and failed crates that cargo had verified. The batch reports a result for every task it receives, also for one that it does not hand to cargo, because Nx starts a new batch without end for a task left out, and it does not throw, because a throw fails every task of the batch ([[EVD-NX-24-BATCHES]]). Known limit: Nx orders release groups by the reported dependencies, which leave out dev-dependencies, so a crate whose dev-dependency with a version requirement is published in a later group fails verification with cargo's message, and a second run publishes it.
|
|
430
|
+
|
|
431
|
+
**Registries.** The plugin uploads a crate only where it can establish, from what cargo itself reports, which registry each lookup before the upload asked and which registry the upload goes to, and that they are the same. Where it cannot establish that, the crate fails before any upload, and so does each crate that depends on it with a version requirement, with a message that says what could not be established and how to configure Cargo plainly. A wrong failure in an unusual configuration is accepted; an upload against the wrong registry is not. A registry's name does not establish it: lookups follow a replacement of a named registry while `cargo publish` uploads to the registry by its name, two names can configure one index, of which cargo then shows one for both, and one name can configure different indexes in the configuration files of two Cargo workspaces ([[EVD-CARGO-PUBLISH-REGISTRIES]]). The paragraphs **Target registry**, **Lookups**, **Where a dependency points**, the checks before each call and **Existing versions** apply this. The control plane decided it on 14 November 2026, after two reviews of this design, and the maintainer is told.
|
|
432
|
+
|
|
433
|
+
**Target registry.** The executor names to cargo the registry that cargo would publish a crate to. Cargo takes `--registry`; else `registry.default`, from `CARGO_REGISTRY_DEFAULT` or from its configuration files, which wins over a crate's `publish` list, so that cargo refuses a crate whose list leaves it out; else the one entry that the `publish` lists of all crates of the call share; else crates.io, which it refuses while its configuration replaces crates.io ([[EVD-CARGO-PUBLISH-REGISTRIES]]). The executor reads each crate's `publish` from the report and `CARGO_REGISTRY_DEFAULT` from the task's environment. It does not read `registry.default` from configuration files: cargo has no stable command that prints it, and Cargo 1.91 ignores a value set through `include` that later versions apply. So, for the crates that it is about to publish and the crates of the repository that they depend on, other than those with `publish = false`, which go nowhere:
|
|
434
|
+
|
|
435
|
+
- Where `CARGO_REGISTRY_DEFAULT` holds a name, that name is every crate's target registry, and no probe runs. A crate whose `publish` list leaves it out fails before cargo runs, with a message that names the list and the registry, because cargo would refuse it, and in a call with other crates the whole call.
|
|
436
|
+
- Otherwise the executor asks cargo, once per workspace and distinct `publish` value, with `cargo publish --dry-run --no-verify --locked -p <crate>` for one crate of that value, started in the workspace root with `CARGO_TARGET_DIR` and `CARGO_BUILD_BUILD_DIR` naming a new folder of the plugin's own outside the repository, which it removes afterwards. Cargo writes the packaged crate into the `package` folder of its build directory, which is the target directory unless the configuration sets `build.build-dir`, and overwrites what lies there, also files that the repository tracks; with both variables set, nothing of the probe lands in the repository on either version, and the probe's output is the same ([[EVD-CARGO-PUBLISH-REGISTRIES]]). The first line of cargo's output that starts with `Updating` shows the registry that cargo chose, ``Updating `<name>` index`` or `Updating crates.io index`, also where cargo goes on to fail, such as on a dependency that is not in the registry yet or on a stale lockfile. Where two names configure one index, cargo shows one of them for both: with `alias` and `alpha` on one index, the probe of a crate with `publish = ["alpha"]` said "found `alpha` as only allowed registry" and then ``Updating `alias` index`` ([[EVD-CARGO-PUBLISH-REGISTRIES]]). The name that the executor passes is therefore, for a one-entry `publish` list, its entry, which cargo has accepted once the line appears; for a list of several entries, the entry that the line names literally, and where it names none, the crates fail; and without a list, the name that the line shows. The executor asks about a crate with a one-entry `publish` list too: a `registry.default` in a configuration file wins over the list and cargo refuses the crate, while passing the list's entry would publish it. Where cargo fails before such a line because it cannot choose, as for a list without the default, a list of two entries and no default, or crates.io replaced and no default, each task of those crates fails with cargo's message, which plain `cargo publish` gives for them as well. The probe uploads nothing.
|
|
437
|
+
- The executor then passes `--registry <name>` to the `cargo publish` of those crates, which uploads to the index that the configuration gives that name, also where the configuration replaces that registry, and which refuses a name that a crate's `publish` list leaves out before it uploads anything ([[EVD-CARGO-PUBLISH-REGISTRIES]]). It never passes `--registry crates-io`: under a replacement of crates.io, `cargo publish --registry crates-io` goes to crates.io itself. For crates.io it passes no `--registry` to `cargo publish`, which then publishes to crates.io as the probe or the environment said.
|
|
438
|
+
|
|
439
|
+
The executor never guesses a target registry: a crate whose registry it cannot tell is not published, and its task fails, and so does the task of each crate that depends on it with a version requirement, with a message that names it. The control plane decided this on 14 November 2026, and the maintainer is told.
|
|
440
|
+
|
|
441
|
+
**Lookups.** The executor looks a version up with `cargo info <crate>@<version> --registry <name> --locked`, and on crates.io with `--index sparse+https://index.crates.io/` in place of `--registry`, with the name that **Target registry** gives, started in the root of the Cargo workspace of the crate looked up, with that crate's own environment (**A dependency's environment**). Without `--registry` or `--index`, `cargo info` describes the workspace's own crate of that name on Cargo 1.100 and asks the default registry on 1.91, and without `--locked` it rewrites a stale `Cargo.lock` ([[EVD-CARGO-PUBLISH-REGISTRIES]], [[EVD-CARGO-PUBLISH]]). A lookup establishes which registry it asked only where the first line of its output that starts with `Updating` names that registry as the executor passed it, ``Updating `<name>` index``, or says `Updating crates.io index` for crates.io, and where, for a version found in a named registry, its `version:` line says ``from registry `<name>` `` with the same name. Cargo shows everything else there ([[EVD-CARGO-PUBLISH-REGISTRIES]]): with `alpha` replaced by `beta`, a lookup with `--registry alpha` printed ``Updating `beta` index`` and ``from registry `alpha-src` ``, the name of the table that replaced it, and where the replacement was a table named `alpha` holding `beta`'s index, ``Updating `alpha` index`` but still ``from registry `alpha-src` ``; where two names configure one index, it printed one of them for both; and offline, by `CARGO_NET_OFFLINE` or `net.offline`, it printed no `Updating` line and answered from its cache. Where the source is established, exit code 0 means that the registry has the version and 101 with "could not find `<crate>@<version>`" that it does not, a full version being matched exactly; any other failure, such as an unreachable registry, fails the task with cargo's message. A lookup that does not establish its source fails, whatever it answered, the task of the crate that it concerns and of each crate that depends on that crate, with a message that names the lookup and what cargo printed in place of the registry, and says to configure the registry under one name, without a replacement, and to publish online. The plugin does not change offline mode: offline, `cargo publish` refuses too, with "attempting to make an HTTP request, but --offline was specified", and the executor never passes `--offline`.
|
|
442
|
+
|
|
443
|
+
**crates.io replaced.** On a machine whose Cargo configuration replaces crates.io, a crate that would publish to crates.io fails before `cargo publish` runs, with each crate that depends on it, and its message says to publish it from a job whose Cargo configuration does not replace crates.io. The executor sees the replacement in the lookup on crates.io, whose `Updating` line then names the replacement, and in the probe of a crate without a `publish` list, which cargo refuses with "crates-io is replaced with …", to which the executor adds this guidance. A `publish = ["crates-io"]` list or `CARGO_REGISTRY_DEFAULT=crates-io` would make `cargo publish` go to crates.io itself past the replacement, while the lookup asks the replacement ([[EVD-CARGO-PUBLISH-REGISTRIES]]). The maintainer's option, word for word: "Keep failing, with guidance (Recommended)" ([[ADR-PUBLISH-REPLACED-CRATES-IO]]). Rejected: passing `--registry crates-io`.
|
|
444
|
+
|
|
445
|
+
**Where a dependency points.** For each dependency, cargo writes into the published crate the registry that the dependency's entry names with `registry`, and crates.io where it names none, and the crates that use the published crate resolve the dependency there. Cargo's configuration never changes it, a replacement of crates.io included: with crates.io replaced by the registry that a call published to, cargo resolved an entry without the key in that registry while it packaged the crate, and still recorded crates.io for it, so that the crate in that registry depends on crates.io's crate of that name ([[EVD-CARGO-PUBLISH-REGISTRIES]]). The executor reads it from the report of the dependent's workspace ([[DES-METADATA-REPORT]]): a dependency's `registry` is `null` for an entry without the key, crates.io's index URL for `registry = "crates-io"`, and otherwise the index URL of the registry that the entry names, also for an entry inherited from `[workspace.dependencies]`. Both `null` and crates.io's URL mean crates.io; any other registry's name is the entry's `registry` value in the manifest, for an inherited entry in the `[workspace.dependencies]` entry that it inherits. A `registry` key that no configuration names makes `cargo metadata` fail, and with it graph creation, so the registry has to be configured wherever cargo reads the manifest ([[EVD-CARGO-PUBLISH-REGISTRIES]]). The executor asks for the report when the task starts, in the task's environment. The registry that an entry points to is established as the dependency's own target registry (**Target registry**), which the executor finds in the dependency's own environment (**A dependency's environment**), only where both are crates.io; or where the dependency and the crate that needs it are in one Cargo workspace, whose configuration files are then the same for both, the environments of the two crates hold the same Cargo settings apart from `CARGO_REGISTRY_DEFAULT`, which chooses the target registry only, and the entry names the very name that the executor passes for the dependency; or where `CARGO_REGISTRIES_<NAME>_INDEX` in the dependency's environment gives the target registry's index, which then holds in every workspace because the environment wins over configuration files, and the report gives the entry that index ([[EVD-CARGO-PUBLISH-REGISTRIES]]). Nothing else establishes it: not two names for one index, the entry naming one and the dependency published under the other; not one name that the configuration files of two workspaces give different indexes, where a dependent in the second workspace was uploaded against a copy of the dependency in its index while the dependency went to the first; not one name in the environments of two crates of one workspace whose Cargo settings differ, such as in `CARGO_HOME`, with which the name can stand for different indexes; and not any other dependency between two Cargo workspaces on a registry other than crates.io whose index only configuration files give. The control plane decided on 14 November 2026, after a review, that the checks compare this registry, and not the one where cargo resolves the dependency on the publishing machine, and after a second review that two registries count as one only as established here; the maintainer is told.
|
|
446
|
+
|
|
447
|
+
**A dependency's environment.** Nx gives each task the dotenv files of its own project, so a `.env` in a crate's folder can give that crate's task Cargo settings that its dependents' tasks lack, such as `CARGO_REGISTRY_DEFAULT`, and the crate's upload goes where its own task's environment sends it. The executor therefore finds a dependency's target registry (**Target registry**), and looks its version up (**Lookups**), with the environment of the dependency's own `nx-release-publish` task. Where the executor received that task, that is the environment it runs the task's cargo commands with ([[DES-BATCH]]). It cannot rebuild the environment of a task that it does not run: one that Nx runs on its own, as without a batch, or one outside the run, as in another release group. A dependency's task in the run's task graph is taken as Nx built it, with its configuration. For one outside the task graph, the executor takes the configuration that Nx would give a run of that target in such a command, by Nx's own rule (`ProcessTasks.resolveConfiguration` in Nx 24's `create-task-graph.js`, which it calls): the configuration of the dependent's task, where that is not merely the dependent target's own `defaultConfiguration` and the dependency's target declares it, otherwise the dependency's `defaultConfiguration`. Because another command may have published the dependency with any configuration, that task counts only where every configuration that its target declares, and none, give the same Cargo settings in their dotenv files; otherwise the dependency's registry is not established, and the message names the dependency's task, the configurations that differ, the settings and the files. The configuration is the only part of the task that the executor chooses: Nx derives the rest of the dotenv files' identifiers, the target and, for an atomized target, its owner's, from the project graph. The maintainer decided this on 20 November 2026 after the review of nxr-4884vg, where a dependency published by its default configuration's dotenv file to `beta` let its dependent be uploaded to `alpha` against another copy. For such a task it compares the dotenv files that Nx loads for it with those of the dependent's task, or, for another crate of the run (**Checks before the first call**), with those of the tasks that it received: where they give the same Cargo settings, the environment of the task compared with stands for it; otherwise the dependency's registry is not established, and the message names both tasks, the settings that differ and the files that set them. Cargo's settings are the variables whose names start with `CARGO` or `RUSTUP_`, which cargo and rustup read, and `HOME` and `PATH`, which locate Cargo's home and choose the cargo that runs, apart from credentials, `CARGO_REGISTRY_TOKEN`, `CARGO_REGISTRIES_<NAME>_TOKEN` and the credential providers, which say how cargo authenticates, not where it goes. The dotenv files are compared by their values before Nx expands them, and where one of those values refers to another variable, by every variable that they define. A variable of the command wins over a dotenv file, which the comparison does not take into account, so it can fail where the settings would agree; that is accepted (**Registries**). A dependency without an `nx-release-publish` task, which the plugin does not publish, such as one without an Nx project or a hack crate, is looked at with the environment of the dependent, as before. Rejected: requiring the crates of one release to agree on their registry settings even in a batch, which would fail a dependency whose dotenv file chooses the very registry that its dependents' entries name; and rebuilding a task's environment from Nx's dotenv functions outside a batch, where the process's own environment already holds the dotenv files of its task.
|
|
448
|
+
|
|
449
|
+
**Checks before the first call.** Before the first `cargo publish` of a batch, or of a task that Nx runs on its own, the executor runs the check _Dependencies published elsewhere_ for each crate of the run: for each crate whose task it received and whose target registry it knows, and for each other crate whose `nx-release-publish` task is in Nx's task graph of the run, whose environment it compares as **A dependency's environment** says, and which fails the check where it depends on a crate of the repository and that comparison does not establish its environment. A crate whose own lookup does not leave it for cargo (**Existing versions**), because its target registry has its version or the lookup fails, is left out of the check: it is not uploaded either way, and the checks before its call report it. So are the dependencies that fail _Unpublished dependencies_, which fails the crate before its call. Where the check fails for any crate, every task that the executor received fails before any upload: the task of each such crate with its message and a line that says that nothing of the run is uploaded, and every other with a message that says that nothing of the run was uploaded, followed by each such message. Nx runs the publish tasks of a release group as one batch ([[EVD-NX-24-PUBLISH-BATCHES]]), so in a release no crate of the group is uploaded; without a batch, each task runs the check for the whole task graph, so every task of the run stops. A release group that an earlier group published before stays published, with its crates where their own settings sent them: the run of the later group does not reach back, and that group is not uploaded. The control plane decided on 20 November 2026 (nxr-4884vg), within the maintainer's direction, that the failure stops the whole run rather than the crates concerned, because the dependency's upload is the one that the dependent's entry contradicts.
|
|
450
|
+
|
|
451
|
+
**Checks before each call.** Before each `cargo publish`, with or without a batch, the executor checks each crate that the call would publish, in this order:
|
|
452
|
+
|
|
453
|
+
- _Unpublished dependencies._ A normal or build dependency with a version requirement on a crate of the repository that is not published to the registry that its entry points to (**Where a dependency points**), through `publish = false` or a `publish` list that does not hold that registry by the entry's own name, `crates-io` for crates.io, fails the crate's task. Cargo packages such a dependency for that registry whatever the dependency's `publish` says: it fails to resolve where the registry has no crate of that name, and it resolves to an unrelated crate where the registry has one, which cargo then publishes as the dependency ([[EVD-CARGO-PUBLISH]]). The message names the crate and the dependency and says that the dependency has to be published to that registry, or the entry's `registry` key has to name a registry that the dependency's `publish` list allows, or the dependency has to stop being a normal or build dependency; for a hack crate it adds cargo-hakari's ways (**Hack crate**). The control plane extended the maintainer's answer for the hack crate to every such dependency on 14 November 2026, as its consequence. A dependency without a version requirement is left to cargo, which refused a crate with such a normal dependency before it uploaded anything of its call ([[EVD-CARGO-PUBLISH]]). The remedy of the `registry` key is given only where the dependency has a `publish` list, whose entries the message names, because no registry allows a crate with `publish = false`. Where the entry points to a registry other than crates.io and the executor finds no `registry` key in it, so that it cannot compare the dependency's `publish` list with the entry's name, the crate fails as well, with a message that says so and names the index (**Registries**). The check runs after the crate's own lookup of **Existing versions**, which uploads nothing. The control plane settled these three points on 16 November 2026 (nxr-k4c6ek).
|
|
454
|
+
- _Dependencies published elsewhere._ For every other normal or build dependency with a version requirement on a crate of the repository, also one that the same call publishes, the registry that its entry points to has to be established as the dependency's own target registry (**Where a dependency points**). The check runs for every crate of the run before the first call, where a failure stops the run (**Checks before the first call**), and again here. Otherwise the crate's task fails before any upload, with a message that names the dependency, the manifest that holds its entry, which is the root manifest for an entry inherited from `[workspace.dependencies]`, the crate that needs it, the registry that the entry points to and the registry that the dependency is published to with the setting that chooses it, `CARGO_REGISTRY_DEFAULT` in the environment of the dependency's task, with the dotenv file that sets it where one does, the crate's `publish` list or cargo's choice by `registry.default`, says what could not be established, and says what to do: add the `registry` key with the dependency's registry to that entry, or correct it; use one name for one index; for a dependency in another Cargo workspace, give the registry's index in the environment as `CARGO_REGISTRIES_<NAME>_INDEX` or keep both crates in one workspace; and where the two crates' environments differ, give the crates of one release the same Cargo settings. This happens to every dependency without a `registry` key on a crate that is published elsewhere than crates.io, to a registry that replaces crates.io as well. Cargo would otherwise publish the crate pointing at another registry's crate of that name: where it resolves the entry in a registry that lacks the version, packaging fails, and where it finds the version, through a replacement of crates.io or in an unrelated crate, it uploads the crate depending on the crate of that name in the registry that the entry points to, crates.io for an entry without the key, also in one call with the dependency, and although `cargo info` had found the version in the dependency's own registry ([[EVD-CARGO-PUBLISH-REGISTRIES]]). For a crate published to crates.io, a dependency whose entry names another registry passes the check where the dependency is published to that registry; what cargo and crates.io then do with the crate is not established ([[RISK-REGISTRY-BEHAVIOUR]]). The control plane decided this check, without an exception for a dependency of the same call, on 14 November 2026, and the maintainer is told.
|
|
455
|
+
- _Dependencies published first._ For each such dependency that passes both checks above, other than one that the same call publishes, the dependency's version in its manifest must already be in the dependency's target registry, by a lookup that establishes its source (**Lookups**). Otherwise the crate's task fails before any upload, with a message that names the dependency, its version and the crate that needs it, and says to publish the dependency first: in the same `nx release publish`, which publishes a dependency's workspace and release group first, or by running the dependency's task before this one. This holds across workspaces and release groups. Cargo would otherwise upload the crate against any registry version that its requirement accepts: with `a` 0.1.0 in the registry and `a` bumped to 0.1.1 beside `b`, whose requirement `0.1.0` still matched, `cargo publish -p b` uploaded `b` built against `a` 0.1.0, and `a` 0.1.1 was never uploaded ([[EVD-CARGO-PUBLISH]]). The control plane chose a check over a narrower promise because an upload cannot be undone. In the normal flow the check passes: cargo waits after each upload until the index lists it, for up to 60 seconds, and right after a call had published a crate, the lookup of **Lookups** found its version ([[EVD-CARGO-PUBLISH]]). Where the index is slower than that, the check fails the dependent before any upload, and a second run publishes it.
|
|
456
|
+
|
|
457
|
+
A crate whose task fails a check is left out of the call, and so is each crate of the call that depends on a crate left out, whose task fails with a message that names that crate; the rest of the call runs.
|
|
458
|
+
|
|
459
|
+
**Dry run.** With `--dry-run`, the executor passes `--dry-run`, and cargo verifies the crates of a call without uploading, each against the registry and against the new versions of the other crates of the same call. That overlay does not carry from one call to the next: after the dry run of a crate's call, the dry run of a dependent's call in another workspace failed with "no matching package named" ([[EVD-CARGO-PUBLISH]]). In a dry run, a crate whose dependency fails only the check _Dependencies published first_, because another call would publish it, is therefore not handed to cargo, and neither is a crate of its call that depends on it. Its task succeeds and says that the crate was not verified, naming the dependency, its version and the task that would publish it, `<project>:nx-release-publish`. The other crates of the call are verified. This happens across Cargo workspaces, across the registries of one workspace and across release groups, which the rule for inherited versions does not prevent. A dependency that no task would publish, or that is not published to the registry that its entry points to, fails as in a real run. The control plane decided this limit on 14 November 2026 after the review; a real run is covered by the checks.
|
|
460
|
+
|
|
461
|
+
**Existing versions.** Nx runs the target on every crate of a group, bumped or not, and cargo fails a whole multi-crate call before uploading anything when one selected version already exists ([[EVD-CARGO-PUBLISH]]). The executor therefore looks each crate of the call up in the call's target registry (**Lookups**), leaves out each crate whose version that registry already has, and its task succeeds with a message that names the crate and the version, so a second run after a partial publish publishes the rest. A crate whose lookup does not establish its source fails before any upload, because a version found elsewhere would leave the crate unpublished while its task reported success.
|
|
462
|
+
|
|
463
|
+
**Tracked files.** Every `cargo publish` and `cargo info` that the executor runs passes `--locked`, whatever the plugin's `locked` option says ([[DES-INVOCATION]]), so publishing changes no tracked file outside Cargo's build directory, in a dry run or a real one. Into its build directory, which is the target directory unless the configuration sets `build.build-dir`, cargo writes the packaged crates and, where it verifies them, their sources and build, and overwrites what lies there, also files that the repository tracks, as plain `cargo publish` does; the probe of **Target registry** writes into a folder of the plugin's own instead ([[EVD-CARGO-PUBLISH-REGISTRIES]]). Without `--locked`, a dry run with a committed bump beside a stale `Cargo.lock` rewrote the lockfile ([[EVD-CARGO-PUBLISH]]). With it, a stale lockfile fails the call before any upload, with cargo's message, which differs between Cargo versions, and the executor adds that `nx release version` brings the lockfile up to date (**Lockfile**). After that step the multi-crate call with `--locked` succeeds, as a dry run and as a real one ([[EVD-CARGO-PUBLISH]]). The control plane decided this on 14 November 2026 after the review.
|
|
464
|
+
|
|
465
|
+
**Credentials and tree.** The executor passes no token: cargo takes the token of the registry that it publishes to from its own credentials, as plain `cargo publish` does. For a registry other than crates.io these are `cargo login --registry <name>`, `CARGO_REGISTRIES_<NAME>_TOKEN` and a credential provider configured for it; `CARGO_REGISTRY_TOKEN` holds crates.io's token only and does not apply where `--registry`, `registry.default` or a `publish` list names another registry. `cargo login` without `--registry` saves the token for the registry that `registry.default` names, and for crates.io only where none is named ([[EVD-CARGO-PUBLISH-REGISTRIES]]). It never passes `--allow-dirty`, and it does not check the working tree itself: whether a tree with uncommitted changes is refused is cargo's own check on the Cargo in use. Cargo 1.100.0 refused uncommitted changes, staged ones too, while Cargo 1.91.0 did not where the Cargo workspace lies in a subfolder of the git repository, the usual layout of an Nx monorepo, and 1.97.1 to 1.99.0 refused them there as well ([[EVD-CARGO-PUBLISH]]). Where cargo refuses, the task fails with cargo's message and a line that says to commit the new versions first. The maintainer decided on 15 November 2026 (nxr-rsaxx7) to leave this to cargo and document the limit, in his words: "Ok why git what if we don't have git document it as a limitation we have nothing to do with it": the plugin has nothing to do with git, and a repository need not use git at all. Rejected: a check of the plugin's own with git before each call, and requiring a newer Cargo for publishing than the plugin's minimum. The release guide names the limit and says to commit before publishing ([[RISK-UNCOMMITTED-PUBLISH]]). `nx release` commits and tags by default, while `nx release version` on its own only stages its changes unless `release.version.git` or `--git-commit` asks for a commit; it refuses a root `release.git` unless it is given `--git-commit`, `--git-tag` and `--stage-changes` ([[EVD-NX-24-RELEASE]], [[EVD-NX-24-VERSION-ACTIONS]]). Cargo's `registry.default` and a crate's `publish` list choose the registry as with plain cargo (**Target registry**).
|
|
466
|
+
|
|
467
|
+
**Options.** The executor's schema declares the options that `nx release publish` passes and that it uses or accepts ([[EVD-NX-24-RELEASE]], [[EVD-NX-24-PUBLISH-OPTIONS]]): `dryRun`, which passes `--dry-run` and which Nx also signals with `NX_DRY_RUN=true`; `registry`, which fails the task (below); and `firstRelease` and `nxReleaseVersionData`, which change nothing. `firstRelease` makes `@nx/js` skip its lookup of the version in the registry; the executor keeps its own (**Existing versions**), because cargo fails a whole call on a version that exists. `tag`, `access` and `otp` are npm's and mean nothing to cargo, which has no distribution tags, access levels or one-time passwords on `cargo publish`: the schema does not declare them, and a task ignores each with a line ([[DES-UNKNOWN-OPTIONS]]). Nx passes `otp` as a number, which a schema that declared it as a string would refuse for every task of the batch.
|
|
468
|
+
|
|
469
|
+
A task whose options hold `registry` fails before cargo runs, whatever the value and in a dry run too, by the maintainer's decision ([[ADR-PUBLISH-REGISTRY-OPTION]]): ignored, it would publish to another registry than the one asked for, and Nx hands every publish task of the run the same value, an npm URL where npm packages take part. The message names the task, the option, its value and where the value came from. Nx puts `registry` among the overrides of every task of the run only when `nx release publish` receives it, and a target's option or a `targetDefaults` entry only into the task's options ([[EVD-NX-24-PUBLISH-OPTIONS]]). So where the overrides that the task graph holds for the task carry the value that the task received, the message says that the value was passed to `nx release publish`. Otherwise it says that the value comes from the workspace's configuration, names `nx show target <project>:nx-release-publish --json` and its `sourceMap` as in [[DES-UNKNOWN-OPTIONS]], and says that an entry of `targetDefaults` keyed by `nx-release-publish` and written for npm reaches crates unless it has a `filter` or the empty entry keyed by `@convesoft/nx-rust:release-publish` that `init` adds is in `nx.json`, and that an entry keyed by `@nx/js:release-publish` reaches npm packages only ([[EVD-NX-TARGET-DEFAULTS]], [[EVD-NX-24-PUBLISH-OPTIONS]]). The message then gives Cargo's own ways: `publish = ["<name>"]` in the crate's `Cargo.toml`, `registry.default` in `.cargo/config.toml`, or `CARGO_REGISTRY_DEFAULT=<name>` in the environment of one run, which Nx passes on to each task's cargo; with the note that the crate's dependencies on crates of the repository then need `registry = "<name>"` in their entries (**Where a dependency points**). Last, for a repository that also publishes npm packages, it says how to give those alone a registry: publish them in a run of their own, with `--groups` or `--projects` and `--registry`, or set the registry in npm's configuration, such as `.npmrc`. For example:
|
|
470
|
+
|
|
471
|
+
```text
|
|
472
|
+
api:nx-release-publish: the option `registry` (https://npm.example.com/) was passed to `nx release publish`, and nx-rust does not map it to a Cargo registry.
|
|
473
|
+
Cargo chooses the registry itself: set `publish = ["<name>"]` in the crate's Cargo.toml or `registry.default` in .cargo/config.toml, or run `CARGO_REGISTRY_DEFAULT=<name> nx release publish` for one run. Dependencies on crates of this repository then need `registry = "<name>"` in their entries.
|
|
474
|
+
To give npm packages alone a registry, publish them in a run of their own (`nx release publish --groups <group> --registry <url>`) or set it in .npmrc.
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
**Dotenv files.** Each task, alone and in a batch, runs the check of a task's dotenv files that the cargo executors run before cargo ([[DES-BATCH]], "Dotenv files"). The executor runs it while it builds the task's environment, before it starts on the tasks, with the environment that the cargo executors check: the one that it builds for the task, before it leaves out the variables that Nx gives each task of its own for its cargo calls (**Settled during implementation**), which are among the variables whose value depends on how the task runs, so that leaving them out changes no verdict. A failure is reported where a failure of the task's environment is: after the check of the target, whose failure comes first, and before the check of the `registry` option and any cargo command. A task that fails the check fails with its message, and nothing is uploaded for it. A task whose dotenv files pass the check publishes as before; besides a reference to a variable whose value depends on how the task runs, the check also refuses a vault that dotenv would read, a file that defines `NX_LOAD_DOT_ENV_FILES` and a `$` form from which it cannot tell which variables Nx looks up. Where the installed Nx lacks what the check reads, the task fails as well. On its own it says that the plugin cannot check the dotenv files of the task, that nothing was published and to use a supported Nx; in a batch the rebuild of the task's environment reads the same parts of Nx before the check, so the task fails with the batch's message that the plugin cannot rebuild the task's environment in a batch, which also names `NX_BATCH_MODE=false`, and with the first message only where the rebuild succeeded. An unexpected error of the check in a batch fails that task alone, with the batch's message, and every other task keeps a result of its own. A task that the check refuses, like any task that fails before the executor reads its crate, such as on its target or the `registry` option, stays a task that the executor received and failed: no cargo command runs for it, and the checks before the first call never take it for a task of another run (**Checks before the first call**), so it fails no other task of the batch. A crate of the batch that depends on its crate with a version requirement fails before its call, in a dry run too, with a message that names the dependency and the failed task, as a crate that depends on a crate left out of a call fails (**Batch**) and as a dry run counts on no task that failed in the same batch (**Settled during implementation**): without that task's environment, the executor can tell neither where the dependency goes nor whether its version is there, and an upload cannot be undone. The refusal is local to the task in a batch only: without a batch, Nx runs the refused task as a run of its own, so for every other task it is a task of another run, and the rule of **Checks before the first call** applies to it as to any such task; where the refused crate depends on a crate of the repository and its dotenv files give other Cargo settings, every other task stops with that rule's message, which names a batch as the way out. Without the check, a crate's `.env.nx-release-publish` with `CARGO_REGISTRY_DEFAULT=team-${NX_TASK_TARGET_CONFIGURATION}` named the registry `team-release` without a batch and `team-` followed by a placeholder of the batch in one (nxr-c63t0r), so that an upload could go to another registry alone than in a batch, or to one that does not exist. The target is not cached, so no stored result depends on the check; it exists because an upload cannot be undone. The maintainer decided on 21 November 2026 that the executor runs the check and fails closed, as the cargo executors do. The control plane decided the same day, after a review, that a task that fails before its crate is read stays one of the batch, how its dependents fail, that an unexpected error of the check fails that task alone, and that without a batch the rule of **Checks before the first call** applies to a refused task as to any task of another run; the maintainer is told.
|
|
478
|
+
|
|
479
|
+
**Without a batch.** `nx run <project>:nx-release-publish` gives a batch of that one task ([[EVD-NX-24-BATCHES]]). When Nx runs a publish task outside a batch, as with `--batch=false` or `NX_BATCH_MODE=false`, the task runs the same checks and `cargo publish --locked -p <crate>` for its own crate, with its target registry. A crate that needs another crate of the repository then passes the check _Dependencies published first_ only once that crate's new version is in the registry; the tasks run in no set order, because the target has no `dependsOn`, so such a task can fail before any upload, and a second run publishes it. Each task runs the checks before the first call for the whole task graph, with the environments of the other tasks compared through their dotenv files (**A dependency's environment**).
|
|
480
|
+
|
|
481
|
+
**Hack crate.** In a workspace with a cargo-hakari configuration, the hack crate is the package that its `hakari-package` names, in `.config/hakari.toml` as `cargo hakari init` writes it, or in `.guppy/hakari.toml` where cargo-hakari reads that file instead ([[EVD-HAKARI-UNIFICATION]], [[DES-UNIFICATION]]). This holds whatever strategy the workspace uses, also where `featureUnification` chooses another one or the workspace falls back from `hakari`, because publishing does not depend on the strategy; a configuration that does not parse, or whose `hakari-package` names no member, names no hack crate, and graph creation warns about it where the workspace would use `hakari` ([[DES-UNIFICATION]], "Fallback"). The plugin never publishes it: it has no `nx-release-publish`. `cargo hakari init` writes the hack crate with `publish = false`, and `cargo hakari manage-deps` gives every other member a normal dependency on it, with the requirement `0.1` from dep-format 2 on, which is the default 4, and without a `registry` key ([[EVD-HAKARI-PUBLISHING]]). When the hack crate has `publish = false`, the check _Unpublished dependencies_ fails each crate that depends on it, and the message points to cargo-hakari's two ways: a stub of the hack crate published once under a unique name, after which plain `cargo publish` works, and `cargo hakari publish` for one crate at a time, outside Nx. The message adds them wherever that check fails for a dependency on the hack crate, also for a `publish` list that leaves out the registry. On crates.io, a requirement on the common name `workspace-hack` resolves to an unrelated crate ([[EVD-CARGO-PUBLISH]]). Where the hack crate does not set `publish = false`, as such a published stub does, its dependents publish normally once the stub's version is in the registry; until then the check _Dependencies published first_ fails them, and its message says that the plugin never publishes the hack crate and to publish the stub once outside Nx, in place of naming a task. Under dep-format 1, whose dependency carries no version requirement, cargo refuses each such crate itself before it uploads anything of its call. The control plane settled the scope of the recognition and the two messages on 16 November 2026 (nxr-k4c6ek). The maintainer's option, word for word: "Fail early with guidance (Recommended)". Rejected: running `cargo hakari publish` for each crate, which needs cargo-hakari installed ([[ADR-V1-SCOPE]]) and loses the multi-crate dry run and cargo's stop after a timeout; and taking the dependency out of the manifest around the cargo call, which writes manifests for a moment, needs `--allow-dirty` and leaves them changed when interrupted.
|
|
482
|
+
|
|
483
|
+
**Other milestones.** Publishing rests on the batch executor of milestone 0.2 ([[ADR-BATCH-EXECUTOR]], [[DES-BATCH]]) and on what Nx does with a batch: on Nx 24.0.6 each task of a batch keeps its own result and terminal output ([[EVD-NX-24-BATCHES]], [[RISK-BATCH-BEHAVIOUR]]). Per-task results from a batch matter here; per-task caching does not, because the target is not cached. The hack crate is recognised through the cargo-hakari configuration that the `hakari` strategy of milestone 0.2 detects ([[DES-UNIFICATION]]).
|
|
484
|
+
|
|
485
|
+
**Settled during implementation.** These points do not change what the paragraphs above promise. The implementation work settles each with evidence and records it here:
|
|
486
|
+
|
|
487
|
+
- What cargo-hakari writes beyond the configuration file that names the hack crate, settled on 16 November 2026 (nxr-k4c6ek) by a run of cargo-hakari 0.9.39 ([[EVD-HAKARI-PUBLISHING]]): `cargo hakari init` gives the hack crate `publish = false`, which `generate` keeps; `manage-deps` writes `workspace-hack = { path = "…" }` under dep-format 1 and `workspace-hack = { version = "0.1", path = "…" }` under 2, 3 and 4, in each member's own `[dependencies]`, also where `[workspace.dependencies]` holds the hack crate, and without a `registry` key (**Hack crate**).
|
|
488
|
+
- Whether Nx 24 hands the `nx-release-publish` tasks of one release group to one batch under `nx release publish`, as [[EVD-NX-24-RELEASE]] reads it ([[RISK-NX-RELEASE]]): it does, and `--projects` and `--groups` narrow each group's batch to the selected tasks ([[EVD-NX-24-PUBLISH-BATCHES]]). How it drives the version actions was run ([[EVD-NX-24-VERSION-ACTIONS]]).
|
|
489
|
+
- The environment of a call, settled on 15 November 2026 (nxr-m8evx2): the tasks of one Cargo workspace and target registry share a call where their environments are the same apart from the variables that Nx gives each task of its own, `NX_TASK_TARGET_PROJECT`, `NX_TASK_TARGET_TARGET`, `NX_TASK_TARGET_CONFIGURATION` and `LERNA_PACKAGE_NAME`, and where all of them run dry or none; the call, and the probes, reports and lookups for its crates, run with that environment without those variables. Tasks whose environments differ otherwise, as through a dotenv file in one crate's folder, publish in calls of their own, ordered as calls of different workspaces are.
|
|
490
|
+
- Which task would publish a dependency in a dry run (**Dry run**): the `nx-release-publish` task of the dependency's project, where the project graph gives the project that target and the task did not fail in the same batch. Outside the batch, as in another release group, that is the task that Nx runs in that group's turn; a dependency without such a target fails as in a real run.
|
|
491
|
+
- A lookup that found its version is not asked again for the same batch; one that did not is asked again before each later call, so that an upload of an earlier call counts only once a lookup finds it in the index (**Dependencies published first**).
|
|
492
|
+
- The executor reads the name of the registry that a dependency's entry names, its `registry` key, from the manifest, or from the root manifest for an entry inherited from `[workspace.dependencies]`, matching the entry by its kind, its key and the folder it names, as the version actions do (**Dependents**); a dependency for which it finds no entry fails the crate.
|
|
493
|
+
:::
|