diff --git a/context/conventions.md b/context/conventions.md index 3cf6962..5dc5483 100644 --- a/context/conventions.md +++ b/context/conventions.md @@ -52,6 +52,16 @@ concept within the crate. after the item using lowercase `snake_case`. Keep small, closely related helper types alongside it when that makes the code easier to understand. +## Consistency across packages + +Before introducing a new semantic, layout, or naming pattern, check how related +Socketry packages handle the same concern. Reuse an established pattern when it +fits the package's purpose. When a package establishes or changes a pattern, +document the rationale and intended usage in that package's context so later +work has a reference. Preserve differences that reflect real domain needs; +consistency should make related packages easier to understand, not flatten +their APIs into one shape. + ## Source and documentation - Keep authored repository-root Markdown files to lowercase `readme.md`, `license.md`, and `releases.md`. diff --git a/context/layout.md b/context/layout.md index eab8142..c69212e 100644 --- a/context/layout.md +++ b/context/layout.md @@ -87,6 +87,6 @@ Put runnable examples under `examples/`. Store project tool configuration in a clearly named configuration file or the relevant Cargo metadata; avoid adding a configuration directory without a concrete tool that uses it. -For testing expectations and task details, see [Testing](testing.md) and the -installed `bake-test-rust` context. Use the [setup skill](setup.md) for -workflow setup. +Follow the `socketry-project-testing` skill for testing expectations and +consult the installed `bake-test-rust` context for task and workflow details. +Use the [setup skill](setup.md) for workflow setup. diff --git a/context/setup.md b/context/setup.md index 8ae3849..5cebb24 100644 --- a/context/setup.md +++ b/context/setup.md @@ -59,7 +59,6 @@ The `socketry-project` dependency makes the shared tasks available to the private Bake binary. It also registers `cargo:after_version_bump`, which updates `license.md`, `releases.md`, and generated sections in `readme.md` after a version change. -It bundles the standard `test` and `test:external` task providers as well. Keep task tooling out of unrelated published libraries. Consumer projects should depend on `socketry-project` from their private `bake/` package. @@ -80,29 +79,21 @@ Generate the Cargo workflow with `cargo:setup:workflow`; follow the before applying rulesets, environment reviewers, or crates.io trusted publishing. -## Standard workflows +## Test workflows -Keep `.github/workflows/test.yml` for local workspace tests. When -`bake-test-rust` is linked, install the Cargo launcher and run -`cargo bake --locked test` so the optional `test:before` hook also runs. -Otherwise use `cargo test --workspace --locked`. Add platform or feature -matrix entries when the project needs them. - -List selected downstream projects under -`[workspace.metadata.bake.test.external]` in the root `Cargo.toml`. Add -`.github/workflows/external.yml` only when that list is non-empty, and run -`cargo bake --locked test:external` when `bake-test-rust` is linked. The task -keeps checkouts under `external/` and applies local workspace crates as Cargo -patches so downstream tests exercise the source being developed. +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:setup:workflow` from `bake-cargo` to generate `.github/workflows/publish.yml`. That workflow checks a release candidate on pull requests, publishes after merge through the configured `crates-io` environment, and then creates or updates the matching GitHub Release from `releases.md`. See the [Cargo Publishing guide](https://github.com/socketry/bake-cargo-rust/blob/main/context/publishing.md) -for trusted publishing and repository setup. See the Rust Testing context -guide provided by `socketry-project` for test workflow details and optional -downstream compatibility workflows. +for trusted publishing and repository setup. Use the +`socketry-project-testing` skill for testing expectations and the +`bake-test-rust` context for workflow and task details. ## Work on the project diff --git a/context/testing.md b/context/testing.md index 79b15d8..0a0a933 100644 --- a/context/testing.md +++ b/context/testing.md @@ -1,19 +1,33 @@ -# Testing +--- +type: skill +description: Add or update tests in Socketry Rust projects, require 100% line coverage, and decide when downstream compatibility tests are useful. Use when asked to add tests or when behavior changes need regression coverage. +--- -Every Rust project should include tests for its public behavior and maintain -100% line coverage for compiled workspace targets. Organize unit, integration, -and documentation tests according to the [Rust repository layout guide](layout.md#test-layout). +# Testing Socketry Rust Projects -Use the shared `bake-test-rust` tasks from the private `bake/` package. The -`test:coverage` task is the canonical CI test entry point: it runs the tests and -enforces the line coverage requirement. Add `--all-targets true` when examples -and benchmarks should also be included. +Use this skill whenever a change adds or changes behavior that should be +verified by tests. -External compatibility tests are optional. List selected downstream projects -in Cargo metadata and add an external test workflow only when the list is -nonempty. +## Expectations -Consult the installed -`.agents/context/bake-test-rust/testing.md` for task configuration, local and -CI commands, coverage setup, `test:before`, and external test details. That -guide owns the canonical workflow and the mechanics for using the tasks. +- Add tests that exercise the changed behavior and relevant regression cases. +- Require 100% line coverage for supported target and feature configurations. + Use the coverage report to find and cover every executable source line. +- Treat uncovered code as an opportunity to review semantics. Check that its + behavior is correct, and fix defects rather than writing tests that codify + accidental behavior. +- Run coverage on each supported target or configuration that compiles distinct + platform-specific code. +- Consider external compatibility tests when a change could affect downstream + crates that use this project's public API. Select the relevant consumers; + downstream testing is not required for every change. + +Follow the repository's test layout guidance when choosing between unit and +integration tests. + +## Use the shared testing tasks + +Use the shared Bake test tasks for local verification and CI. Consult the +installed `bake-test-rust` context at +`.agents/context/bake-test-rust/testing.md` for canonical workflow files, task +setup and invocation, coverage options, and downstream test configuration. diff --git a/context/update.md b/context/update.md index 31e6263..ef2b639 100644 --- a/context/update.md +++ b/context/update.md @@ -25,6 +25,9 @@ initial setup steps. Review the repository's Cargo manifests, source and test layout, standard root files, Bake package, agent context, and GitHub workflows. Compare them with the current guidance in `socketry-project` and the relevant shared task packages. +Compare semantics, layout, and naming with related Socketry packages. Reuse +patterns that fit; when this package establishes a new pattern, document its +rationale and intended usage in the package context. Check these areas: diff --git a/readme.md b/readme.md index 8118812..028e50f 100644 --- a/readme.md +++ b/readme.md @@ -35,9 +35,9 @@ version-bump hook that updates the project's standard files. See the [repository setup skill](context/setup.md) for the minimal Cargo configuration and the [conventions](context/conventions.md) for repository layout, documentation, and code conventions. The -[Rust Repository Layout](context/layout.md) and -[Rust Testing](context/testing.md) guides provide more detail on source -organization and test workflows. +[Rust Repository Layout](context/layout.md) explains source organization. The +testing skill sets expectations and points to `bake-test-rust` for task and +workflow details. ## Releasing diff --git a/releases.md b/releases.md index 53ec399..60ee11b 100644 --- a/releases.md +++ b/releases.md @@ -1,5 +1,13 @@ # Releases +## Unreleased + +- Add a testing skill that sets the 100% line-coverage expectation and directs + agents to review uncovered code for semantic defects and use `bake-test-rust` + for canonical workflows and task details. +- Document how to maintain consistency across Socketry packages and record new + semantic, layout, and naming patterns in the package that establishes them. + ## v0.3.0 - Add an update skill for auditing and modernizing existing Socketry Rust