diff --git a/Cargo.lock b/Cargo.lock index 9eee62a..1205bbe 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -677,7 +677,7 @@ dependencies = [ [[package]] name = "socketry-project" -version = "0.3.10" +version = "0.3.11" dependencies = [ "bake", "bake-agent-context", diff --git a/Cargo.toml b/Cargo.toml index 4a5da07..94593d2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "socketry-project" -version = "0.3.10" +version = "0.3.11" edition = "2024" license = "MIT" repository = "https://github.com/socketry/socketry-project-rust" diff --git a/bake/Cargo.toml b/bake/Cargo.toml index f4da9dd..c2ee72b 100644 --- a/bake/Cargo.toml +++ b/bake/Cargo.toml @@ -7,4 +7,4 @@ publish = false [dependencies] bake = "0.19.0" bake-markdown = "0.3.0" -socketry-project = { path = "..", version = "0.3.10" } +socketry-project = { path = "..", version = "0.3.11" } diff --git a/context/conventions.md b/context/conventions.md index d30447c..17e6388 100644 --- a/context/conventions.md +++ b/context/conventions.md @@ -40,6 +40,15 @@ Before introducing a new semantic, layout, or naming pattern, check how related - Avoid duplicating Rust-wide guidance from `bake-agent-context`; add project context for the architecture and decisions that are specific to the crate. - Follow the Agent Context section in `readme.md` to install and discover shared context and skills. The `bake-agent-context` guide explains the installer's behavior. +## Dependency versions in documentation + +- Prefer installation commands such as `cargo add socketry-markdown` or `cargo add --manifest-path bake/Cargo.toml socketry-project`. Let Cargo select the dependency and write its manifest requirement. See [Cargo's `cargo add` documentation](https://doc.rust-lang.org/cargo/commands/cargo-add.html). +- Treat `Cargo.toml` as the authority for supported dependency requirements and the workspace's root `Cargo.lock` as its resolved selection, following [Cargo's manifest and lockfile guidance](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html). Link to the relevant manifest; `cargo metadata --locked` identifies resolved package versions and manifest paths. Use the resolved provider's manifest when checking installed tooling. +- Describe required capabilities, APIs, and task names in prose. When a numeric minimum explains a compatibility boundary, keep it in one provider-owned guide with the reason and a link to the supporting release or API documentation. Other guides should refer to that source. +- Keep explicit versions where they convey necessary information: migration instructions, historical release notes, minimum supported Rust versions, or reproducible examples tied to a particular release. Preserve historical references when newer releases appear. +- Use manifest snippets when explaining dependency requirements or features, and validate them against the supported API. Choose ranges according to the package's compatibility policy. The open-ended minimum for private `socketry-project` tooling follows its setup guidance; runtime libraries use requirements appropriate to their supported APIs. +- When a version must appear in several current documents, generate those references from authoritative metadata as part of the documentation tasks. + ## Development and releases - Keep development tasks in a private `bake/` package. Depend on `socketry-project` there so task tooling does not become a runtime dependency of the published library. diff --git a/context/releasing.md b/context/releasing.md index 7508486..535c763 100644 --- a/context/releasing.md +++ b/context/releasing.md @@ -34,7 +34,7 @@ The check job installs the Bake launcher and runs `cargo:release:detect --base " After a merge to the configured branch, the `crates-io` environment gates the publish job. `cargo:publish:pending --version "$BAKE_VERSION"` checks which workspace packages still need publishing. GitHub OIDC authentication runs only when packages are pending. `cargo:release:publish --version "$BAKE_VERSION" --sha "$BAKE_SHA"` publishes the remaining packages, then creates and pushes the version tag and creates or updates the matching GitHub Release from `releases.md` using `cargo:releases:github:release`. -These operations are Bake tasks; the workflow contains no inline Python release scripts. The task names in this workflow require `bake` 0.19.0 and `bake-cargo` 0.4.0 or newer in the resolved task binary, including its `Cargo.lock`. The version-bump hook also requires `bake-markdown` 0.3.0 or newer, which uses hyphen markers for unordered lists. +These operations are Bake tasks. The supported task-provider requirements are declared in the resolved `socketry-project` package's `Cargo.toml`; the [source manifest](https://github.com/socketry/socketry-project-rust/blob/main/Cargo.toml) shows the current project's requirements. Use `cargo metadata --locked` to locate the resolved provider's manifest and confirm the versions used by the task binary. Update the workspace lockfile deliberately when adopting newer tooling, then regenerate task links with `cargo bake --regenerate`. After merging, check the workflow result, published package versions, version tag, and GitHub Release. If a publish workflow is still waiting for environment approval, obtain that approval through the configured reviewer process. diff --git a/context/setup.md b/context/setup.md index ff66110..7e17031 100644 --- a/context/setup.md +++ b/context/setup.md @@ -32,7 +32,7 @@ cargo add --manifest-path bake/Cargo.toml socketry-project In `bake/Cargo.toml`, prefix the version selected by Cargo with `>=` to make it an open-ended minimum. Keep that actual minimum in the manifest and the resolved version in `Cargo.lock`; the setup documentation does not need a copy of either version. -The open-ended minimum requirement allows newer `socketry-project` releases. The workspace's root `Cargo.lock` records the selected version for the private `bake/` package, so update that lockfile deliberately when adopting a newer release. +The open-ended minimum requirement allows newer `socketry-project` releases. The workspace's root `Cargo.lock` records the selected version for the private `bake/` package, so update that lockfile deliberately when adopting a newer release. Follow the [dependency-version documentation guidelines](https://github.com/socketry/socketry-project-rust/blob/main/context/conventions.md#dependency-versions-in-documentation) when writing setup examples or compatibility requirements. Run regeneration again to link its task registrations: @@ -61,7 +61,7 @@ Configure repository metadata, collaboration features, pull request defaults, an Use the `socketry-project-testing` skill for organization-wide testing expectations. Consult the installed `bake-test-rust` context for canonical `test.yml` and optional `external.yml` workflows, task setup, coverage options, and downstream test configuration. -Use `cargo bake cargo:setup:workflow` to generate `.github/workflows/publish.yml` from the canonical Bake Cargo template. The workflow runs `cargo:release:detect` and `cargo:release` for release checks, then `cargo:publish:pending` and `cargo:release:publish` after merge through the configured `crates-io` environment. The standard workflow is documented in the shared Releasing skill; its task binary must resolve `bake` 0.19.0, `bake-cargo` 0.4.0, and `bake-markdown` 0.3.0 or newer. Follow the `bake-test-rust` context for test workflow and task details. +Use `cargo bake cargo:setup:workflow` to generate `.github/workflows/publish.yml` from the canonical Bake Cargo template. The workflow runs `cargo:release:detect` and `cargo:release` for release checks, then `cargo:publish:pending` and `cargo:release:publish` after merge through the configured `crates-io` environment. Follow the `socketry-project-releasing` skill for the standard workflow and task-provider requirements, and the `bake-test-rust` context for test workflow and task details. ## Work on the project diff --git a/readme.md b/readme.md index 6571f06..a094e79 100644 --- a/readme.md +++ b/readme.md @@ -39,6 +39,11 @@ Prepare a release with `cargo bake cargo:version:patch` (or `minor`, `major`, or See [releases.md](releases.md) for the full release history. +### v0.3.11 + +- Document how to maintain dependency versions in installation examples and compatibility guidance, using manifests and lockfiles as authoritative sources. +- Replace duplicated release-tooling version lists with guidance for checking the resolved provider's manifest. + ### v0.3.10 - Add independent adversarial review guidance, with local iteration until all non-trivial issues are resolved before opening a pull request. @@ -48,11 +53,6 @@ See [releases.md](releases.md) for the full release history. - Follow Rust acronym casing in type and trait names, using `HtmlRenderer`, `HttpClient`, `UrlParser`, and `FileIo`. -### v0.3.8 - -- Let Cargo select setup dependency versions while retaining open-ended minimum requirements. -- Require current agent-context and readme providers so installed guidance preserves repository instructions and shared conventions. - ## See Also diff --git a/releases.md b/releases.md index 75e9604..038f46f 100644 --- a/releases.md +++ b/releases.md @@ -1,5 +1,10 @@ # Releases +## v0.3.11 + +- Document how to maintain dependency versions in installation examples and compatibility guidance, using manifests and lockfiles as authoritative sources. +- Replace duplicated release-tooling version lists with guidance for checking the resolved provider's manifest. + ## v0.3.10 - Add independent adversarial review guidance, with local iteration until all non-trivial issues are resolved before opening a pull request.