From 3b4096d3798546ecb2e6e6204253f127744e2635 Mon Sep 17 00:00:00 2001 From: Samuel Williams Date: Mon, 5 Oct 2026 23:19:36 +1300 Subject: [PATCH 1/2] Prepare socketry-project 0.3.6. --- Cargo.lock | 2 +- Cargo.toml | 2 +- bake/Cargo.toml | 2 +- bake/src/bake_generated_tasks/mod.rs | 4 +- context/conventions.md | 91 +++++++--------------------- context/github-repository.md | 72 ++++++++-------------- context/layout.md | 51 ++++------------ context/pull-requests.md | 49 +++++---------- context/releasing.md | 77 ++++++----------------- context/setup.md | 67 ++++---------------- context/testing.md | 56 +++++------------ context/update.md | 69 ++++++--------------- license.md | 20 ++---- readme.md | 57 ++++++----------- releases.md | 73 ++++++++++------------ src/markdown.rs | 10 ++- src/tests.rs | 4 +- 17 files changed, 201 insertions(+), 505 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 1f1fee0..ccad64e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -667,7 +667,7 @@ dependencies = [ [[package]] name = "socketry-project" -version = "0.3.5" +version = "0.3.6" dependencies = [ "bake", "bake-agent-context", diff --git a/Cargo.toml b/Cargo.toml index 39cbbbd..d1b1995 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "socketry-project" -version = "0.3.5" +version = "0.3.6" edition = "2024" license = "MIT" repository = "https://github.com/socketry/socketry-project-rust" diff --git a/bake/Cargo.toml b/bake/Cargo.toml index cfc4b71..d5880be 100644 --- a/bake/Cargo.toml +++ b/bake/Cargo.toml @@ -7,4 +7,4 @@ publish = false [dependencies] bake = "0.19.0" bake-markdown = "0.2.0" -socketry-project = { path = "..", version = "0.3.5" } +socketry-project = { path = "..", version = "0.3.6" } diff --git a/bake/src/bake_generated_tasks/mod.rs b/bake/src/bake_generated_tasks/mod.rs index 860794b..0ddfa03 100644 --- a/bake/src/bake_generated_tasks/mod.rs +++ b/bake/src/bake_generated_tasks/mod.rs @@ -1,4 +1,6 @@ -// Generated by `cargo bake --regenerate`; do not edit. +// Released under the MIT License. +// Copyright, 2026, by Samuel Williams. +// Generated by `cargo bake --regenerate`; do not edit. use bake_markdown as _; use socketry_project as _; diff --git a/context/conventions.md b/context/conventions.md index ee920e9..7095d73 100644 --- a/context/conventions.md +++ b/context/conventions.md @@ -1,92 +1,47 @@ # Socketry Rust Conventions -Use these conventions for Rust repositories in the Socketry organization. A -project's local `.agents/` files and package-specific documentation can add -requirements for that repository. +Use these conventions for Rust repositories in the Socketry organization. A project's local `.agents/` files and package-specific documentation can add requirements for that repository. ## Repository and package boundaries -- Use a separate repository when packages need independent versions, release - notes, or tags. -- Keep packages in one workspace when they are intentionally released together: - use one shared version, one root `releases.md`, and one `vVERSION` tag. -- Name crates for their public purpose. Use the `socketry-` prefix where needed - to identify Socketry packages in the flat crates.io namespace; keep Rust - module paths semantic and concise. -- Use Cargo's standard `src/`, `tests/`, and `examples/` directories. Use - integration tests for public behavior across crate boundaries. +* Use a separate repository when packages need independent versions, release notes, or tags. +* Keep packages in one workspace when they are intentionally released together: use one shared version, one root `releases.md`, and one `vVERSION` tag. +* Name crates for their public purpose. Use the `socketry-` prefix where needed to identify Socketry packages in the flat crates.io namespace; keep Rust module paths semantic and concise. +* Use Cargo's standard `src/`, `tests/`, and `examples/` directories. Use integration tests for public behavior across crate boundaries. ## Crate and module paths -Treat the Cargo crate name as the root namespace. Do not repeat it with a -same-named top-level module. Keep modules for meaningful domain concepts, and -re-export the main public API from the crate root when deeper modules only -organize its implementation. For example, callers can import the -agent-context API from the root: +Treat the Cargo crate name as the root namespace. Do not repeat it with a same-named top-level module. Keep modules for meaningful domain concepts, and re-export the main public API from the crate root when deeper modules only organize its implementation. For example, callers can import the agent-context API from the root: ```rust use bake_agent_context::{ContextIndex, Installer, install_skills, list_skills}; ``` -Keep public paths independent of redundant namespace layers such as -`bake_agent_context::context`. Public modules remain useful when they name a -real part of the API: a crate named `protocol_http` can expose -`protocol_http::headers::AcceptHeader`, where `headers` identifies the domain -concept within the crate. +Keep public paths independent of redundant namespace layers such as `bake_agent_context::context`. Public modules remain useful when they name a real part of the API: a crate named `protocol_http` can expose `protocol_http::headers::AcceptHeader`, where `headers` identifies the domain concept within the crate. ## Source naming -- Use `snake_case` for modules, source files, functions, methods, and variables. - Use `UpperCamelCase` for structs, enums, traits, and type parameters. -- Preserve established initialisms in type and trait names: write - `HTMLRenderer`, `HTTPClient`, and `URLParser`, rather than - `HtmlRenderer`, `HttpClient`, or `UrlParser`. Keep filenames lowercase - `snake_case`, such as `html_renderer.rs`, `http_client.rs`, and - `url_parser.rs`. -- Make public type and trait names fully descriptive; include the kind of thing - being named instead of relying on the module path to supply it. For example, - use `io_stream::BufferedStream` rather than `io_stream::Buffered`. -- Prefer clear, consistent names. Avoid abbreviations unless they are an - established domain initialism or required by an external API. -- Give each primary public struct, enum, or trait its own source file, named - after the item using lowercase `snake_case`. Keep small, closely related - helper types alongside it when that makes the code easier to understand. +* Use `snake_case` for modules, source files, functions, methods, and variables. Use `UpperCamelCase` for structs, enums, traits, and type parameters. +* Preserve established initialisms in type and trait names: write `HTMLRenderer`, `HTTPClient`, and `URLParser`, rather than `HtmlRenderer`, `HttpClient`, or `UrlParser`. Keep filenames lowercase `snake_case`, such as `html_renderer.rs`, `http_client.rs`, and `url_parser.rs`. +* Make public type and trait names fully descriptive; include the kind of thing being named instead of relying on the module path to supply it. For example, use `io_stream::BufferedStream` rather than `io_stream::Buffered`. +* Prefer clear, consistent names. Avoid abbreviations unless they are an established domain initialism or required by an external API. +* Give each primary public struct, enum, or trait its own source file, named 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. +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`. -- Start `license.md` with `# MIT License`. -- Keep `readme.md` human-focused: explain the project, its motivation when - useful, how to use it, recent releases, and how to contribute. Follow the - `Readme Structure` guide supplied by `bake-readme`. -- Put reusable, package-specific agent guidance in `context/`; keep - repository-only instructions and project-owned skills in `.agents/`. Treat - the root `agents.md` as repository-owned guidance. -- 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. + +* Keep authored repository-root Markdown files to lowercase `readme.md`, `license.md`, and `releases.md`. +* Start `license.md` with `# MIT License`. +* Keep `readme.md` human-focused: explain the project, its motivation when useful, how to use it, recent releases, and how to contribute. Follow the `Readme Structure` guide supplied by `bake-readme`. +* Put reusable, package-specific agent guidance in `context/`; keep repository-only instructions and project-owned skills in `.agents/`. Treat the root `agents.md` as repository-owned guidance. +* 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. ## 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. -- Use the `cargo:after_version_bump` hook registered by `socketry-project` to - update `license.md`, `releases.md`, and the generated sections of `readme.md`, - then normalize those files and all Markdown under the public `context/` - directory. -- Follow the `socketry-project-releasing` skill to prepare and publish a - release. It links to Bake Cargo task documentation for workflow setup, - trusted publishing, reviewers, and tag creation. +* 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. +* Use the `cargo:after_version_bump` hook registered by `socketry-project` to update `license.md`, `releases.md`, and the generated sections of `readme.md`, then normalize those files and all Markdown under the public `context/` directory. +* Follow the `socketry-project-releasing` skill to prepare and publish a release. It links to Bake Cargo task documentation for workflow setup, trusted publishing, reviewers, and tag creation. diff --git a/context/github-repository.md b/context/github-repository.md index 41a35bc..93b78a0 100644 --- a/context/github-repository.md +++ b/context/github-repository.md @@ -5,76 +5,52 @@ description: Create or maintain GitHub repository metadata, collaboration featur # GitHub Repository Setup -Use these defaults when creating a Socketry repository. Preserve deliberate -project-specific settings when maintaining an existing repository. +Use these defaults when creating a Socketry repository. Preserve deliberate project-specific settings when maintaining an existing repository. ## Repository metadata -- Use the canonical Socketry organization and project name. -- Write a short, accurate repository description. -- Set the homepage to the documentation site when one exists. -- Add focused topics for discovery; avoid repeating words already in the - repository name. -- Use `main` as the default branch. +* Use the canonical Socketry organization and project name. +* Write a short, accurate repository description. +* Set the homepage to the documentation site when one exists. +* Add focused topics for discovery; avoid repeating words already in the repository name. +* Use `main` as the default branch. ## Collaboration features -Enable Issues, Discussions, Pull Requests, Sponsorships, and repository -preservation. Disable Projects and Wiki unless the project has a concrete use -for them. +Enable Issues, Discussions, Pull Requests, Sponsorships, and repository preservation. Disable Projects and Wiki unless the project has a concrete use for them. Use GitHub issue types to classify issues consistently: -- `Bug` for defects and regressions. -- `Feature` for new user-facing capabilities. -- `Task` for maintenance, refactoring, documentation, tests, and release work. +* `Bug` for defects and regressions. +* `Feature` for new user-facing capabilities. +* `Task` for maintenance, refactoring, documentation, tests, and release work. -Prefer organization or repository labels that already exist. Add labels only -when the project needs a reusable classification not covered by issue types or -existing labels. Do not repeat issue type information in issue text when GitHub -already records it as metadata. Issue types apply to issues; do not assign one -to a pull request or include issue type information in its text. +Prefer organization or repository labels that already exist. Add labels only when the project needs a reusable classification not covered by issue types or existing labels. Do not repeat issue type information in issue text when GitHub already records it as metadata. Issue types apply to issues; do not assign one to a pull request or include issue type information in its text. ## Pull requests and commits -- Disable merge commits; allow squash and rebase merging. -- Suggest updating pull request branches, allow auto-merge, and delete merged - head branches automatically. -- Require contributors to sign off on commits made through GitHub's web - interface. -- Allow comments on individual commits. -- Use Markdown, complete sentences, and a final period for pull request titles - and commit messages. -- Keep most commit messages to one line. Start with what changed. -- Describe pull requests with a short summary followed by the problem and - solution. Do not add a separate change type section or assign an issue type - to a pull request. - -Use the `socketry-project-pull-requests` skill for the full title, commit, -description, testing, and release note conventions. +* Disable merge commits; allow squash and rebase merging. +* Suggest updating pull request branches, allow auto-merge, and delete merged head branches automatically. +* Require contributors to sign off on commits made through GitHub's web interface. +* Allow comments on individual commits. +* Use Markdown, complete sentences, and a final period for pull request titles and commit messages. +* Keep most commit messages to one line. Start with what changed. +* Describe pull requests with a short summary followed by the problem and solution. Do not add a separate change type section or assign an issue type to a pull request. + +Use the `socketry-project-pull-requests` skill for the full title, commit, description, testing, and release note conventions. ## Branch protection -Protect `main` and require pull requests with at least one approval. Allow -administrators to bypass these rules for maintenance. Require only stable -checks that are needed for safe auto-merge; do not make experimental, -informational, or unreliable coverage checks mandatory. +Protect `main` and require pull requests with at least one approval. Allow administrators to bypass these rules for maintenance. Require only stable checks that are needed for safe auto-merge; do not make experimental, informational, or unreliable coverage checks mandatory. ## Apply settings safely -Use the GitHub CLI for repository changes. Inspect the target first and always -use its full name in commands: +Use the GitHub CLI for repository changes. Inspect the target first and always use its full name in commands: ```sh gh repo view socketry/PROJECT ``` -When maintaining an existing repository, inspect its current settings and make -the smallest change that achieves the intended result. Preserve project-specific -settings. Do not rename, archive, transfer, or delete a repository without -explicit approval, and do not disable issues, pull requests, or required checks -without approval. +When maintaining an existing repository, inspect its current settings and make the smallest change that achieves the intended result. Preserve project-specific settings. Do not rename, archive, transfer, or delete a repository without explicit approval, and do not disable issues, pull requests, or required checks without approval. -The `socketry-project-releasing` skill describes the standard Cargo release -process and links to Bake Cargo task documentation for branch rulesets, -crates.io environment reviewers, and trusted publishing. +The `socketry-project-releasing` skill describes the standard Cargo release process and links to Bake Cargo task documentation for branch rulesets, crates.io environment reviewers, and trusted publishing. diff --git a/context/layout.md b/context/layout.md index 47f6924..57e2181 100644 --- a/context/layout.md +++ b/context/layout.md @@ -1,8 +1,6 @@ # Rust Repository Layout -Use Cargo's standard structure so contributors can find package code, tests, -examples, and project documentation quickly. Add directories as the project -needs them; a small crate does not need every directory shown here. +Use Cargo's standard structure so contributors can find package code, tests, examples, and project documentation quickly. Add directories as the project needs them; a small crate does not need every directory shown here. ```text project/ @@ -22,18 +20,11 @@ project/ ## Cargo package and source modules -The root `Cargo.toml` defines the package and, when needed, the workspace. Put -library code under `src/`, integration tests under `tests/`, and runnable -examples under `examples/`. See [Conventions](conventions.md) for package and -workspace boundaries, and the [setup skill](setup.md) for the private Bake -package. +The root `Cargo.toml` defines the package and, when needed, the workspace. Put library code under `src/`, integration tests under `tests/`, and runnable examples under `examples/`. See [Conventions](conventions.md) for package and workspace boundaries, and the [setup skill](setup.md) for the private Bake package. ## Source modules and files -Organize source by subsystem so the module tree is visible. For a module with -children, use the modern file-plus-directory layout: a same-named source file -and directory. For example, `src/parser.rs` defines `parser` and declares -children whose files live under `src/parser/`: +Organize source by subsystem so the module tree is visible. For a module with children, use the modern file-plus-directory layout: a same-named source file and directory. For example, `src/parser.rs` defines `parser` and declares children whose files live under `src/parser/`: ```text src/ @@ -44,32 +35,19 @@ src/ └── inline_parser.rs ``` -Declare each source module in its parent. Keep module and directory names -aligned; avoid `mod.rs` for new modules. Follow the [Socketry Rust naming -conventions](conventions.md#source-naming) for Rust items and source files. +Declare each source module in its parent. Keep module and directory names aligned; avoid `mod.rs` for new modules. Follow the [Socketry Rust naming conventions](conventions.md#source-naming) for Rust items and source files. -Cargo package metadata belongs in `Cargo.toml`. Follow the -`socketry-project-releasing` skill for the release workflow and consult Bake -Cargo task documentation for package inclusion details. +Cargo package metadata belongs in `Cargo.toml`. Follow the `socketry-project-releasing` skill for the release workflow and consult Bake Cargo task documentation for package inclusion details. ## Root files -The example project tree shows the standard root documentation files. See -[Conventions](conventions.md#source-and-documentation) for their naming and -content requirements. +The example project tree shows the standard root documentation files. See [Conventions](conventions.md#source-and-documentation) for their naming and content requirements. ## Test layout -Prefer to mirror the source organization in tests. Keep small unit test suites -within the module they exercise, using an inline `#[cfg(test)] mod tests`. When -a suite grows, move it into that module's directory; for example, -`src/parser/inline_parser.rs` can declare tests from -`src/parser/inline_parser/tests.rs`. This keeps tests able to access private -implementation details without exposing them as public API. +Prefer to mirror the source organization in tests. Keep small unit test suites within the module they exercise, using an inline `#[cfg(test)] mod tests`. When a suite grows, move it into that module's directory; for example, `src/parser/inline_parser.rs` can declare tests from `src/parser/inline_parser/tests.rs`. This keeps tests able to access private implementation details without exposing them as public API. -Put integration tests under `tests/` to check the public crate interface. A -multi-file suite can be grouped by subsystem, with `main.rs` as the test target -root and sibling files as test modules: +Put integration tests under `tests/` to check the public crate interface. A multi-file suite can be grouped by subsystem, with `main.rs` as the test target root and sibling files as test modules: ```text tests/ @@ -79,15 +57,8 @@ tests/ └── inline_parser.rs ``` -Declare child modules from `main.rs`; Cargo discovers the target root and the -declared modules organize the suite. Integration tests exercise the public -crate API. See the [Cargo integration test -layout](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#integration-tests). +Declare child modules from `main.rs`; Cargo discovers the target root and the declared modules organize the suite. Integration tests exercise the public crate API. See the [Cargo integration test layout](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#integration-tests). -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. +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. -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. +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/pull-requests.md b/context/pull-requests.md index 9fac736..78675ee 100644 --- a/context/pull-requests.md +++ b/context/pull-requests.md @@ -5,27 +5,20 @@ description: Prepare commits and GitHub pull requests for Socketry Rust projects # Pull Requests -Use these conventions when preparing commits or pull requests for Socketry Rust -projects. +Use these conventions when preparing commits or pull requests for Socketry Rust projects. ## Titles and commits -- Pull request titles must use Markdown, be complete sentences, and end with a - full stop. -- Commit messages must use Markdown and end with a full stop. -- The first line of a commit message must focus on what changed. -- Most commit messages should be a single line. -- Keep relevant context in the code itself, such as comments, rather than using - the commit message as a side channel for important details. -- Do not include agent links, attribution footers, generated-by annotations, or - similar metadata in commit messages. +* Pull request titles must use Markdown, be complete sentences, and end with a full stop. +* Commit messages must use Markdown and end with a full stop. +* The first line of a commit message must focus on what changed. +* Most commit messages should be a single line. +* Keep relevant context in the code itself, such as comments, rather than using the commit message as a side channel for important details. +* Do not include agent links, attribution footers, generated-by annotations, or similar metadata in commit messages. ## Pull request description -Start with a brief summary, followed by a detailed description of the problem -and solution. Include implementation details that help reviewers understand -the change, link relevant issues when applicable, and include screenshots for -visual changes. +Start with a brief summary, followed by a detailed description of the problem and solution. Include implementation details that help reviewers understand the change, link relevant issues when applicable, and include screenshots for visual changes. Use this structure, replacing the guidance with project-specific content: @@ -37,32 +30,22 @@ that help reviewers understand the change. Link relevant issues if applicable. Include screenshots for visual changes. ``` -Do not add a `Types of Changes` section. Issue types classify GitHub issues; -do not assign an issue type to a pull request or include issue type metadata in -its description. If a related issue needs classification, set the type on that -issue. +Do not add a `Types of Changes` section. Issue types classify GitHub issues; do not assign an issue type to a pull request or include issue type metadata in its description. If a related issue needs classification, set the type on that issue. ## Testing -Changes should include suitable test coverage. Aim for complete coverage of the -behavior being changed or introduced. If a change directly affects downstream -crates, add or update downstream integration coverage when useful. +Changes should include suitable test coverage. Aim for complete coverage of the behavior being changed or introduced. If a change directly affects downstream crates, add or update downstream integration coverage when useful. -Do not list passing test commands or verification steps in the pull request -description unless they explain an unusual risk, limitation, or manual -validation requirement. +Do not list passing test commands or verification steps in the pull request description unless they explain an unusual risk, limitation, or manual validation requirement. ## Release notes -For user-visible changes, add a brief entry to `releases.md` following the -release notes guidance provided by `bake-releases`. +For user-visible changes, add a brief entry to `releases.md` following the release notes guidance provided by `bake-releases`. ## Issue types -Issue types apply to GitHub issues. Do not try to set an issue type when -creating or updating a pull request. For a linked issue, use its issue type: +Issue types apply to GitHub issues. Do not try to set an issue type when creating or updating a pull request. For a linked issue, use its issue type: -- Use `Bug` for defect fixes and regressions. -- Use `Feature` for new user-facing capabilities. -- Use `Task` for maintenance, refactoring, documentation, tests, release work, - and internal improvements. +* Use `Bug` for defect fixes and regressions. +* Use `Feature` for new user-facing capabilities. +* Use `Task` for maintenance, refactoring, documentation, tests, release work, and internal improvements. diff --git a/context/releasing.md b/context/releasing.md index a8d787c..3f02d74 100644 --- a/context/releasing.md +++ b/context/releasing.md @@ -5,18 +5,13 @@ description: Prepare and follow through a reviewed release for Socketry Rust pro # Releasing -Use this skill to prepare releases for Socketry Rust projects. Read the root -`agents.md`, `readme.md`, and installed agent context for any project-specific -release steps. +Use this skill to prepare releases for Socketry Rust projects. Read the root `agents.md`, `readme.md`, and installed agent context for any project-specific release steps. ## Prepare a release -Keep one Cargo workspace when its publishable packages share a version, release -notes, and tag. Use separate repositories for packages that need independent -release timing. See [Conventions](conventions.md#repository-and-package-boundaries). +Keep one Cargo workspace when its publishable packages share a version, release notes, and tag. Use separate repositories for packages that need independent release timing. See [Conventions](conventions.md#repository-and-package-boundaries). -Use the tasks linked by the project's private `bake/` package to bump the -workspace version: +Use the tasks linked by the project's private `bake/` package to bump the workspace version: ```sh cargo bake cargo:version:patch @@ -25,62 +20,26 @@ cargo bake cargo:version:major cargo bake cargo:version:bump --version X.Y.Z ``` -Choose one version task. The `socketry-project` hook updates `license.md`, -`releases.md`, and generated sections of `readme.md`, then normalizes those -files and all Markdown under the public `context/` directory. Review the -generated changes and ensure the release notes describe the actual changes. +Choose one version task. The `socketry-project` hook updates `license.md`, `releases.md`, and generated sections of `readme.md`, then normalizes those files and all Markdown under the public `context/` directory. Review the generated changes and ensure the release notes describe the actual changes. -Run the project's required tests and coverage checks using the -`socketry-project-testing` skill. Commit the version and release files, then run -`cargo bake cargo:release` from the clean worktree. This validates and packages -the release candidate; it does not publish or tag it. Open a reviewed pull -request after the task succeeds. +Run the project's required tests and coverage checks using the `socketry-project-testing` skill. Commit the version and release files, then run `cargo bake cargo:release` from the clean worktree. This validates and packages the release candidate; it does not publish or tag it. Open a reviewed pull request after the task succeeds. ## Publish through GitHub Actions -Generate `.github/workflows/publish.yml` with `cargo bake cargo:setup:workflow`. -The canonical template is maintained in -[`bake-cargo-rust/src/publish.yml`](https://github.com/socketry/bake-cargo-rust/blob/main/src/publish.yml). -Keep repository-specific changes limited to the configured branch and update -this shared template when the standard workflow changes. - -The check job installs the Bake launcher and runs -`cargo:release:detect --base "$BAKE_BEFORE" --sha "$BAKE_SHA"`. That task -compares the current workspace version with the base commit, checks the matching -`releases.md` heading when the version changed, and writes the `release` and -`version` GitHub outputs. Release candidates then run `cargo:release` before the -formatting, Clippy, and test checks. - -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.2.0 or -newer. - -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. +Generate `.github/workflows/publish.yml` with `cargo bake cargo:setup:workflow`. The canonical template is maintained in [`bake-cargo-rust/src/publish.yml`](https://github.com/socketry/bake-cargo-rust/blob/main/src/publish.yml). Keep repository-specific changes limited to the configured branch and update this shared template when the standard workflow changes. + +The check job installs the Bake launcher and runs `cargo:release:detect --base "$BAKE_BEFORE" --sha "$BAKE_SHA"`. That task compares the current workspace version with the base commit, checks the matching `releases.md` heading when the version changed, and writes the `release` and `version` GitHub outputs. Release candidates then run `cargo:release` before the formatting, Clippy, and test checks. + +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.2.0 or newer. + +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. + ## Set up publishing -For a new repository, use `cargo bake cargo:setup:workflow` to generate the -workflow. Put required environment reviewers in `Cargo.toml`, preview settings -with `cargo bake cargo:setup:github:plan`, and apply them with -`cargo bake cargo:setup:github:apply` after reviewing the plan. +For a new repository, use `cargo bake cargo:setup:workflow` to generate the workflow. Put required environment reviewers in `Cargo.toml`, preview settings with `cargo bake cargo:setup:github:plan`, and apply them with `cargo bake cargo:setup:github:apply` after reviewing the plan. -For a crate's first upload, `cargo bake cargo:bootstrap PACKAGE` publishes it -with an owner token and registers its trusted publisher. Keep the token out of -the repository. After the initial upload, use GitHub OIDC for routine releases; -enable trusted-publishing-only mode after the workflow has published -successfully. +For a crate's first upload, `cargo bake cargo:bootstrap PACKAGE` publishes it with an owner token and registers its trusted publisher. Keep the token out of the repository. After the initial upload, use GitHub OIDC for routine releases; enable trusted-publishing-only mode after the workflow has published successfully. -For exact arguments and behavior of these tasks, consult the -[Bake Cargo Readme](https://github.com/socketry/bake-cargo-rust/blob/main/readme.md) -and each task's `--help` output. +For exact arguments and behavior of these tasks, consult the [Bake Cargo Readme](https://github.com/socketry/bake-cargo-rust/blob/main/readme.md) and each task's `--help` output. diff --git a/context/setup.md b/context/setup.md index d771e63..53bc3cf 100644 --- a/context/setup.md +++ b/context/setup.md @@ -5,25 +5,15 @@ description: Bootstrap a Rust repository with Socketry layout, Bake tasks, agent # Set Up a Rust Repository -Use this skill to bootstrap a new Rust repository or add its initial shared -Socketry tooling. For an audit of an established repository, use the -`socketry-project-update` skill. +Use this skill to bootstrap a new Rust repository or add its initial shared Socketry tooling. For an audit of an established repository, use the `socketry-project-update` skill. ## Create the repository -Use a separate repository for a crate that needs its own version, release notes, -or release tag. Use a Cargo workspace when its packages are meant to ship -together at one version and share one `releases.md` and one `vVERSION` tag. +Use a separate repository for a crate that needs its own version, release notes, or release tag. Use a Cargo workspace when its packages are meant to ship together at one version and share one `releases.md` and one `vVERSION` tag. -Choose the crate name for its public purpose. Crates.io has a flat package -namespace, so use a `socketry-` prefix when needed to identify a Socketry crate. -The repository can use the `-rust` suffix to distinguish it from a related -project in another language. +Choose the crate name for its public purpose. Crates.io has a flat package namespace, so use a `socketry-` prefix when needed to identify a Socketry crate. The repository can use the `-rust` suffix to distinguish it from a related project in another language. -Start with the standard Cargo layout and root files described in the -Rust Repository Layout context guide provided by `socketry-project`. Keep the -library's dependencies in the root package and development automation in a -private `bake/` workspace member. +Start with the standard Cargo layout and root files described in the Rust Repository Layout context guide provided by `socketry-project`. Keep the library's dependencies in the root package and development automation in a private `bake/` workspace member. ## Add shared project tasks @@ -34,17 +24,13 @@ cargo install socketry-cargo-bake --locked cargo bake --regenerate ``` -The command creates `bake/`, adds it to the Cargo workspace, and writes a -minimal binary. Add this dependency under the existing `[dependencies]` table in -`bake/Cargo.toml`: +The command creates `bake/`, adds it to the Cargo workspace, and writes a minimal binary. Add this dependency under the existing `[dependencies]` table in `bake/Cargo.toml`: ```toml socketry-project = ">=0.3.3" ``` -The open-ended minimum requirement allows newer `socketry-project` releases. -The private Bake package's `Cargo.lock` records the selected version, so update -the lockfile deliberately when adopting a newer release. +The open-ended minimum requirement allows newer `socketry-project` releases. The private Bake package's `Cargo.lock` records the selected version, so update the lockfile deliberately when adopting a newer release. Run regeneration again to link its task registrations: @@ -59,51 +45,22 @@ Set release reviewers in the root `Cargo.toml`: reviewers = ["socketry/managers"] ``` -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, then normalizes those files and every Markdown file under the -public `context/` directory. Locally installed `.agents/context/` files are not -included. -Keep task tooling out of unrelated published libraries. Consumer projects -should depend on `socketry-project` from their private `bake/` package. +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, then normalizes those files and every Markdown file under the public `context/` directory. Locally installed `.agents/context/` files are not included. Keep task tooling out of unrelated published libraries. Consumer projects should depend on `socketry-project` from their private `bake/` package. ## Agent context -Follow the [Agent Context section in `readme.md`](../readme.md#agent-context) -to install and discover shared context and skills. Follow -[Conventions](conventions.md#source-and-documentation) for where to keep -package guidance and project-only instructions. The `bake-agent-context` -guide documents installer behavior and options. +Follow the [Agent Context section in `readme.md`](../readme.md#agent-context) to install and discover shared context and skills. Follow [Conventions](conventions.md#source-and-documentation) for where to keep package guidance and project-only instructions. The `bake-agent-context` guide documents installer behavior and options. ## Set up GitHub -Configure repository metadata, collaboration features, pull request defaults, -and branch protection using the `socketry-project-github-repository` skill. -Generate the Cargo workflow with `cargo:setup:workflow`; follow the -`socketry-project-releasing` skill before applying rulesets, environment -reviewers, or crates.io trusted publishing. It links to the Bake Cargo Readme -for task-specific details. +Configure repository metadata, collaboration features, pull request defaults, and branch protection using the `socketry-project-github-repository` skill. Generate the Cargo workflow with `cargo:setup:workflow`; follow the `socketry-project-releasing` skill before applying rulesets, environment reviewers, or crates.io trusted publishing. It links to the Bake Cargo Readme for task-specific details. ## Test workflows -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 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.2.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. 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.2.0 or newer. Follow the `bake-test-rust` context for test workflow and task details. ## Work on the project -Keep the root `readme.md` concise and human-focused. Use the project context and -Rust API documentation for detailed implementation guidance. Run the project's -checks before opening a pull request, and update `releases.md` for user-visible -changes. +Keep the root `readme.md` concise and human-focused. Use the project context and Rust API documentation for detailed implementation guidance. Run the project's checks before opening a pull request, and update `releases.md` for user-visible changes. diff --git a/context/testing.md b/context/testing.md index 30a5a05..6a2b400 100644 --- a/context/testing.md +++ b/context/testing.md @@ -5,55 +5,31 @@ description: Add or update tests in Socketry Rust projects, require 100% region # Testing Socketry Rust Projects -Use this skill whenever a change adds or changes behavior that should be -verified by tests. +Use this skill whenever a change adds or changes behavior that should be verified by tests. ## Expectations -- Add tests that exercise the changed behavior and relevant regression cases. -- Require 100% region coverage for supported target and feature configurations. - Use LLVM's region report to find executable paths that tests have not run. -- Treat uncovered code as an opportunity to review semantics. Check that its - behavior is correct, add tests for meaningful behavior, and fix defects - rather than writing tests that codify accidental behavior. Remove dead code - or make invariants explicit when a region cannot represent supported - behavior; do not manufacture impossible internal states just to reach it. -- 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. +* Add tests that exercise the changed behavior and relevant regression cases. +* Require 100% region coverage for supported target and feature configurations. Use LLVM's region report to find executable paths that tests have not run. +* Treat uncovered code as an opportunity to review semantics. Check that its behavior is correct, add tests for meaningful behavior, and fix defects rather than writing tests that codify accidental behavior. Remove dead code or make invariants explicit when a region cannot represent supported behavior; do not manufacture impossible internal states just to reach it. +* 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. ## Difficult-to-trigger I/O failures -Use real temporary directories for normal filesystem behavior. When an -important error path depends on an operating-system failure that is difficult -to trigger reliably, a private `#[cfg(test)]` shim can make that failure -deterministic: +Use real temporary directories for normal filesystem behavior. When an important error path depends on an operating-system failure that is difficult to trigger reliably, a private `#[cfg(test)]` shim can make that failure deterministic: -- Keep production builds delegated directly to the standard library. -- In tests, wrap only the needed operation and delegate to the real filesystem - except for a specifically injected failure. -- Scope injected failures to the operation and path, and isolate them from - parallel tests. -- Assert observable behavior, such as the returned error and whether changes - were rolled back or cleaned up. +* Keep production builds delegated directly to the standard library. +* In tests, wrap only the needed operation and delegate to the real filesystem except for a specifically injected failure. +* Scope injected failures to the operation and path, and isolate them from parallel tests. +* Assert observable behavior, such as the returned error and whether changes were rolled back or cleaned up. -Filesystem error kinds and path resolution vary by operating system. Inject -failures for portable error-path tests; use platform-gated tests when the -OS-specific behavior itself is what the test needs to verify. +Filesystem error kinds and path resolution vary by operating system. Inject failures for portable error-path tests; use platform-gated tests when the OS-specific behavior itself is what the test needs to verify. -Keep the shim small and local to the code under test. Do not build a broad fake -filesystem or add production abstractions solely to satisfy coverage. If many -call sites need fault injection, reconsider the design and introduce a shared -abstraction only when it also makes the production code clearer. +Keep the shim small and local to the code under test. Do not build a broad fake filesystem or add production abstractions solely to satisfy coverage. If many call sites need fault injection, reconsider the design and introduce a shared abstraction only when it also makes the production code clearer. ## 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. +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 f7d8ec8..35986c6 100644 --- a/context/update.md +++ b/context/update.md @@ -5,69 +5,34 @@ description: Audit and update an existing Rust repository against current Socket # Update a Socketry Rust Project -Use this skill to bring an existing crate repository up to the current Socketry -baseline. For a new repository, use the `socketry-project-setup` skill. If an -established repository lacks foundational Bake setup, use that skill for the -initial setup steps. +Use this skill to bring an existing crate repository up to the current Socketry baseline. For a new repository, use the `socketry-project-setup` skill. If an established repository lacks foundational Bake setup, use that skill for the initial setup steps. ## Read the project's guidance -- Follow the repository's `agents.md` and project-specific instructions. -- Run `cargo bake agent:context:install` when shared task dependencies change - or installed context may be missing or stale. Read - `.agents/context/index.md` and the skills that apply to the work. -- Consult the current `socketry-project` context and the installed `bake-*` - context for task behavior. Prefer those task guides over copying their - implementation details into this skill. +* Follow the repository's `agents.md` and project-specific instructions. +* Run `cargo bake agent:context:install` when shared task dependencies change or installed context may be missing or stale. Read `.agents/context/index.md` and the skills that apply to the work. +* Consult the current `socketry-project` context and the installed `bake-*` context for task behavior. Prefer those task guides over copying their implementation details into this skill. ## Audit the current baseline -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. +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: -- **Cargo and Bake setup:** package and workspace boundaries, the private - `bake/` package, the shared `socketry-project` dependency, and generated task - links. -- **Project files:** lowercase `readme.md`, `license.md`, and `releases.md`, - with standard sections and generated content maintained by shared tasks. -- **Agent context:** reusable package guidance in `context/`, project-only - instructions and skills in `.agents/`, and current installed context and - skills. -- **Testing:** tests for behavior, the 100% region-coverage expectation, and - downstream testing where public compatibility makes it useful. Use the - `socketry-project` Testing context and installed `bake-test-rust` guide for - the current policy and task details. -- **GitHub workflows:** the standard test and publish workflows, plus external - testing when downstream projects are configured. Use the GitHub repository - skill for repository settings and the `socketry-project-releasing` skill for - publishing workflow setup. Consult the Bake Cargo Readme for task behavior, - workflow generation, and trusted-publishing details. +* **Cargo and Bake setup:** package and workspace boundaries, the private `bake/` package, the shared `socketry-project` dependency, and generated task links. +* **Project files:** lowercase `readme.md`, `license.md`, and `releases.md`, with standard sections and generated content maintained by shared tasks. +* **Agent context:** reusable package guidance in `context/`, project-only instructions and skills in `.agents/`, and current installed context and skills. +* **Testing:** tests for behavior, the 100% region-coverage expectation, and downstream testing where public compatibility makes it useful. Use the `socketry-project` Testing context and installed `bake-test-rust` guide for the current policy and task details. +* **GitHub workflows:** the standard test and publish workflows, plus external testing when downstream projects are configured. Use the GitHub repository skill for repository settings and the `socketry-project-releasing` skill for publishing workflow setup. Consult the Bake Cargo Readme for task behavior, workflow generation, and trusted-publishing details. -Classify findings as required baseline changes, optional recommendations, or -valid project-specific exceptions. Preserve deliberate local architecture and -custom workflows when they do not conflict with an explicit organization -convention. +Classify findings as required baseline changes, optional recommendations, or valid project-specific exceptions. Preserve deliberate local architecture and custom workflows when they do not conflict with an explicit organization convention. ## Apply updates with shared tasks -- Use `cargo bake --regenerate` after adding or changing task dependencies so - generated task links match the Bake package. -- Use shared tasks such as `license:update`, `readme:update`, and - `cargo:setup:workflow` where they apply. Review generated workflow changes - before replacing project-specific configuration. -- Use `cargo bake test:coverage` for the standard local coverage check. Consult - `bake-test-rust` for feature, target, and optional downstream test setup. -- Let `cargo:after_version_bump` refresh standard release files during release - preparation. Follow the `socketry-project-releasing` skill for version bumps, - validation, and the reviewed GitHub release process. -- Keep changes focused on the identified baseline gaps; do not rewrite valid - project-specific choices merely to match an example layout. +* Use `cargo bake --regenerate` after adding or changing task dependencies so generated task links match the Bake package. +* Use shared tasks such as `license:update`, `readme:update`, and `cargo:setup:workflow` where they apply. Review generated workflow changes before replacing project-specific configuration. +* Use `cargo bake test:coverage` for the standard local coverage check. Consult `bake-test-rust` for feature, target, and optional downstream test setup. +* Let `cargo:after_version_bump` refresh standard release files during release preparation. Follow the `socketry-project-releasing` skill for version bumps, validation, and the reviewed GitHub release process. +* Keep changes focused on the identified baseline gaps; do not rewrite valid project-specific choices merely to match an example layout. -Review the final diff and summarize completed baseline changes, optional -recommendations, and any retained project-specific exceptions. +Review the final diff and summarize completed baseline changes, optional recommendations, and any retained project-specific exceptions. diff --git a/license.md b/license.md index e589fcc..17fbb94 100644 --- a/license.md +++ b/license.md @@ -1,21 +1,9 @@ # MIT License -Copyright, 2026, by Samuel Williams. +Copyright, 2026, by Samuel Williams. -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/readme.md b/readme.md index 9c3465d..9679c35 100644 --- a/readme.md +++ b/readme.md @@ -1,12 +1,10 @@ # `socketry-project` -Shared conventions and development tasks for Rust projects in the Socketry -organization. +Shared conventions and development tasks for Rust projects in the Socketry organization. ## Motivation -Rust projects should share a small set of clear conventions and a reliable -release process without repeating task wiring in every repository. +Rust projects should share a small set of clear conventions and a reliable release process without repeating task wiring in every repository. ## Usage @@ -17,60 +15,42 @@ cargo install socketry-cargo-bake --locked cargo bake --regenerate ``` -Add this dependency under the existing `[dependencies]` table in -`bake/Cargo.toml`: +Add this dependency under the existing `[dependencies]` table in `bake/Cargo.toml`: ```toml socketry-project = ">=0.3.3" ``` -Then run `cargo bake --regenerate` again to link the dependency's tasks. The -command keeps generated links separate from task source, so no manual import in -`main.rs` is needed. Run `cargo bake --list` to see the available tasks. -The open-ended minimum requirement keeps this development dependency eligible -for newer releases. `Cargo.lock` records the selected version for reproducible -builds; update it deliberately when adopting a newer release. +Then run `cargo bake --regenerate` again to link the dependency's tasks. The command keeps generated links separate from task source, so no manual import in `main.rs` is needed. Run `cargo bake --list` to see the available tasks. The open-ended minimum requirement keeps this development dependency eligible for newer releases. `Cargo.lock` records the selected version for reproducible builds; update it deliberately when adopting a newer release. -This adds the standard Cargo, release, license, Readme, agent-context, and -testing tasks, including `test` and `test:external`. It also registers a -version-bump hook that updates the project's standard files. +This adds the standard Cargo, release, license, Readme, agent-context, and testing tasks, including `test` and `test:external`. It also registers a 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) explains source organization. The -testing skill sets expectations and points to `bake-test-rust` for task and -workflow details. +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) explains source organization. The testing skill sets expectations and points to `bake-test-rust` for task and workflow details. ## Releasing -Prepare a release with `cargo bake cargo:version:patch` (or `minor`, `major`, -or `bump --version X.Y.Z`), then run `cargo bake cargo:release` and open a -pull request. After review and merge, GitHub Actions publishes the release -when the configured `crates-io` environment approves it, then creates or updates -the matching GitHub Release from `releases.md`. See the shared -[Releasing skill](context/releasing.md) for the standard release process. +Prepare a release with `cargo bake cargo:version:patch` (or `minor`, `major`, or `bump --version X.Y.Z`), then run `cargo bake cargo:release` and open a pull request. After review and merge, GitHub Actions publishes the release when the configured `crates-io` environment approves it, then creates or updates the matching GitHub Release from `releases.md`. See the shared [Releasing skill](context/releasing.md) for the standard release process. ## Releases + See [releases.md](releases.md) for the full release history. +### v0.3.6 + +* Normalize standard project Markdown files after version bumps. +* Fix the version bump hook's invocation of the Markdown normalizer. + ### v0.3.5 -- Require `bake-test-rust` 0.3.0 or newer for LLVM region coverage and update - the shared testing guidance to match. +* Require `bake-test-rust` 0.3.0 or newer for LLVM region coverage and update the shared testing guidance to match. ### v0.3.4 -- Require Bake 0.18.0 and Bake Cargo 0.4.0 for shared task registration. -- Document a test-only shim pattern for deterministic coverage of difficult - I/O failures. - -### v0.3.3 +* Require Bake 0.18.0 and Bake Cargo 0.4.0 for shared task registration. +* Document a test-only shim pattern for deterministic coverage of difficult I/O failures. -- Point the project update skill at the shared Releasing skill and Bake Cargo - task documentation. ## Contributing @@ -79,9 +59,6 @@ Please open an issue or pull request on [GitHub](https://github.com/socketry/soc ### Agent Context -Run `cargo bake agent:context:install` to install shared context and skills. -Read `.agents/context/index.md` to find relevant guides, follow `agents.md` if -present, and apply skills under `.agents/skills/`. See the [Agent Context guide] -for guidance on organizing package context and repository-only instructions. +Run `cargo bake agent:context:install` to install shared context and skills. Read `.agents/context/index.md` to find relevant guides, follow `agents.md` if present, and apply skills under `.agents/skills/`. See the [Agent Context guide] for guidance on organizing package context and repository-only instructions. [Agent Context guide]: https://github.com/socketry/bake-agent-context-rust/blob/main/context/agent-context.md diff --git a/releases.md b/releases.md index 80ce366..dfd5420 100644 --- a/releases.md +++ b/releases.md @@ -1,93 +1,82 @@ # Releases -## Unreleased +## v0.3.6 -- Normalize standard project Markdown files after version bumps. +* Normalize standard project Markdown files after version bumps. +* Fix the version bump hook's invocation of the Markdown normalizer. ## v0.3.5 -- Require `bake-test-rust` 0.3.0 or newer for LLVM region coverage and update - the shared testing guidance to match. +* Require `bake-test-rust` 0.3.0 or newer for LLVM region coverage and update the shared testing guidance to match. ## v0.3.4 -- Require Bake 0.18.0 and Bake Cargo 0.4.0 for shared task registration. -- Document a test-only shim pattern for deterministic coverage of difficult - I/O failures. +* Require Bake 0.18.0 and Bake Cargo 0.4.0 for shared task registration. +* Document a test-only shim pattern for deterministic coverage of difficult I/O failures. ## v0.3.3 -- Point the project update skill at the shared Releasing skill and Bake Cargo - task documentation. +* Point the project update skill at the shared Releasing skill and Bake Cargo task documentation. ## v0.3.2 -- Add a shared Releasing skill and remove links to duplicated Cargo publishing - guidance. -- Update the setup instructions to use `socketry-project` 0.3. +* Add a shared Releasing skill and remove links to duplicated Cargo publishing guidance. +* Update the setup instructions to use `socketry-project` 0.3. ## v0.3.1 -- 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. +* 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 - projects. +* Add an update skill for auditing and modernizing existing Socketry Rust projects. ## v0.2.7 -- Clarify how context installation uses `.agents/context/index.md` and local - Git exclusions without changing a repository-owned `agents.md`. -- Express shared task dependencies as minimum versions so compatible updates - can be selected by the host project's lockfile. -- Require 100% line coverage for workspace targets in GitHub Actions. -- Use the shared `bake-test-rust` coverage task in the standard workflow. -- Cover Bake task execution and the version-bump hook's task ordering. +* Clarify how context installation uses `.agents/context/index.md` and local Git exclusions without changing a repository-owned `agents.md`. +* Express shared task dependencies as minimum versions so compatible updates can be selected by the host project's lockfile. +* Require 100% line coverage for workspace targets in GitHub Actions. +* Use the shared `bake-test-rust` coverage task in the standard workflow. +* Cover Bake task execution and the version-bump hook's task ordering. ## v0.2.6 -- Support `bake-agent-context` 0.2 while retaining compatibility with 0.1. -- Keep the generated context index under `.agents/context/` without modifying - the repository owner's `agents.md`. +* Support `bake-agent-context` 0.2 while retaining compatibility with 0.1. +* Keep the generated context index under `.agents/context/` without modifying the repository owner's `agents.md`. ## v0.2.5 -- Distribute repository setup, GitHub setup, and pull request guidance as - installable skills. -- Provide shared Agent Context guidance through `bake-agent-context`. +* Distribute repository setup, GitHub setup, and pull request guidance as installable skills. +* Provide shared Agent Context guidance through `bake-agent-context`. ## v0.2.4 -- Clarify crate namespaces, descriptive type names, module layout, and test paths. +* Clarify crate namespaces, descriptive type names, module layout, and test paths. ## v0.2.3 -- Rename the project guides to shorter context filenames and titles. -- Clarify source, test, naming, and coverage conventions. +* Rename the project guides to shorter context filenames and titles. +* Clarify source, test, naming, and coverage conventions. ## v0.2.2 -- Use Bake Cargo's GitHub Release automation in the standard publishing workflow. +* Use Bake Cargo's GitHub Release automation in the standard publishing workflow. ## v0.2.1 -- Document setup and task linking with `cargo bake --regenerate`. +* Document setup and task linking with `cargo bake --regenerate`. ## v0.2.0 -- Move the shared project tasks to `bake` 0.17 and include standard Rust test tasks. -- Document standard local, downstream, and publishing workflows. +* Move the shared project tasks to `bake` 0.17 and include standard Rust test tasks. +* Document standard local, downstream, and publishing workflows. ## v0.1.1 -- Add a reusable Pull Requests guide to the packaged agent context. +* Add a reusable Pull Requests guide to the packaged agent context. ## v0.1.0 -- Establish shared conventions and standard Bake tasks for Socketry Rust projects. -- Document project layout, GitHub setup, and agent context installation. +* Establish shared conventions and standard Bake tasks for Socketry Rust projects. +* Document project layout, GitHub setup, and agent context installation. diff --git a/src/markdown.rs b/src/markdown.rs index e83efed..e18d77d 100644 --- a/src/markdown.rs +++ b/src/markdown.rs @@ -15,12 +15,10 @@ pub(super) fn normalize(context: &mut Context) -> Result<()> { } fn normalize_paths(context: &mut Context, paths: Vec) -> Result<()> { - let mut owned_arguments = Vec::with_capacity(paths.len() * 2); - - for path in paths { - owned_arguments.push("--path".to_owned()); - owned_arguments.push(path_argument(&path)?); - } + let owned_arguments: Vec<_> = paths + .iter() + .map(|path| path_argument(path)) + .collect::>()?; let arguments: Vec<_> = owned_arguments.iter().map(String::as_str).collect(); context.call("markdown:normalize", &arguments)?; diff --git a/src/tests.rs b/src/tests.rs index e1ccaf9..b16fb88 100644 --- a/src/tests.rs +++ b/src/tests.rs @@ -38,7 +38,7 @@ fn update_readme(context: &mut bake::Context, _: &Arguments) -> Result { } fn normalize_markdown(context: &mut bake::Context, arguments: &Arguments) -> Result { - let paths = arguments.repeated::("path")?; + let paths = arguments.repeated::("paths")?; record(context, "markdown:normalize", None)?; context.get_mut::().unwrap().markdown_paths = paths; Ok(Value::Null) @@ -73,7 +73,7 @@ fn registry() -> Registry { .register(Task::new( "markdown:normalize", "", - vec![Parameter::new::("path").repeated()], + vec![Parameter::new::("paths").variadic()], normalize_markdown, )) .unwrap(); From f218fbf2eb56bba51250f2816774a084385ceba8 Mon Sep 17 00:00:00 2001 From: Samuel Williams Date: Tue, 6 Oct 2026 00:18:02 +1300 Subject: [PATCH 2/2] Include hyphen normalization in shared project tasks. --- Cargo.lock | 11 ++++--- Cargo.toml | 1 + bake/Cargo.toml | 2 +- context/conventions.md | 36 ++++++++++----------- context/github-repository.md | 30 +++++++++--------- context/pull-requests.md | 18 +++++------ context/releasing.md | 2 +- context/setup.md | 4 +-- context/testing.md | 18 +++++------ context/update.md | 26 +++++++-------- readme.md | 15 ++++----- releases.md | 61 ++++++++++++++++++------------------ src/lib.rs | 1 + src/tests.rs | 29 ++++++++++++++--- 14 files changed, 139 insertions(+), 115 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index ccad64e..4a44222 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -83,12 +83,12 @@ dependencies = [ [[package]] name = "bake-markdown" -version = "0.2.0" +version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8eba114380436efdf21b2872d88f5450808cbbdec7947a647f7041ef4efb08a9" +checksum = "be72df839f4db26a93f2fe0659e57ce7998900b9445b04ba1367d51b4ba38587" dependencies = [ "bake", - "socketry-markdown 0.2.0", + "socketry-markdown 0.3.0", ] [[package]] @@ -657,9 +657,9 @@ dependencies = [ [[package]] name = "socketry-markdown" -version = "0.2.0" +version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "37d3a646262edeca60e86e4c4dd493167e74beb03ea75a60b2d5c40e6d6d8c5b" +checksum = "8c02f802fe678b660dd21a6b6130bc2d0eb3423c24b9f26ebddb46514769e788" dependencies = [ "regex", "unicode-id", @@ -673,6 +673,7 @@ dependencies = [ "bake-agent-context", "bake-cargo", "bake-license", + "bake-markdown", "bake-readme", "bake-releases", "bake-test-rust", diff --git a/Cargo.toml b/Cargo.toml index d1b1995..908ea6b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -26,6 +26,7 @@ bake = ">=0.19.0" bake-agent-context = { version = ">=0.2.0" } bake-cargo = { version = ">=0.4.0" } bake-license = { version = ">=0.1.1" } +bake-markdown = { version = ">=0.3.0" } bake-readme = { version = ">=0.1.1" } bake-releases = { version = ">=0.2.1" } bake-test-rust = { version = ">=0.3.0" } diff --git a/bake/Cargo.toml b/bake/Cargo.toml index d5880be..3c8cf07 100644 --- a/bake/Cargo.toml +++ b/bake/Cargo.toml @@ -6,5 +6,5 @@ publish = false [dependencies] bake = "0.19.0" -bake-markdown = "0.2.0" +bake-markdown = "0.3.0" socketry-project = { path = "..", version = "0.3.6" } diff --git a/context/conventions.md b/context/conventions.md index 7095d73..bd8f6b4 100644 --- a/context/conventions.md +++ b/context/conventions.md @@ -4,10 +4,10 @@ Use these conventions for Rust repositories in the Socketry organization. A proj ## Repository and package boundaries -* Use a separate repository when packages need independent versions, release notes, or tags. -* Keep packages in one workspace when they are intentionally released together: use one shared version, one root `releases.md`, and one `vVERSION` tag. -* Name crates for their public purpose. Use the `socketry-` prefix where needed to identify Socketry packages in the flat crates.io namespace; keep Rust module paths semantic and concise. -* Use Cargo's standard `src/`, `tests/`, and `examples/` directories. Use integration tests for public behavior across crate boundaries. +- Use a separate repository when packages need independent versions, release notes, or tags. +- Keep packages in one workspace when they are intentionally released together: use one shared version, one root `releases.md`, and one `vVERSION` tag. +- Name crates for their public purpose. Use the `socketry-` prefix where needed to identify Socketry packages in the flat crates.io namespace; keep Rust module paths semantic and concise. +- Use Cargo's standard `src/`, `tests/`, and `examples/` directories. Use integration tests for public behavior across crate boundaries. ## Crate and module paths @@ -21,11 +21,11 @@ Keep public paths independent of redundant namespace layers such as `bake_agent_ ## Source naming -* Use `snake_case` for modules, source files, functions, methods, and variables. Use `UpperCamelCase` for structs, enums, traits, and type parameters. -* Preserve established initialisms in type and trait names: write `HTMLRenderer`, `HTTPClient`, and `URLParser`, rather than `HtmlRenderer`, `HttpClient`, or `UrlParser`. Keep filenames lowercase `snake_case`, such as `html_renderer.rs`, `http_client.rs`, and `url_parser.rs`. -* Make public type and trait names fully descriptive; include the kind of thing being named instead of relying on the module path to supply it. For example, use `io_stream::BufferedStream` rather than `io_stream::Buffered`. -* Prefer clear, consistent names. Avoid abbreviations unless they are an established domain initialism or required by an external API. -* Give each primary public struct, enum, or trait its own source file, named after the item using lowercase `snake_case`. Keep small, closely related helper types alongside it when that makes the code easier to understand. +- Use `snake_case` for modules, source files, functions, methods, and variables. Use `UpperCamelCase` for structs, enums, traits, and type parameters. +- Preserve established initialisms in type and trait names: write `HTMLRenderer`, `HTTPClient`, and `URLParser`, rather than `HtmlRenderer`, `HttpClient`, or `UrlParser`. Keep filenames lowercase `snake_case`, such as `html_renderer.rs`, `http_client.rs`, and `url_parser.rs`. +- Make public type and trait names fully descriptive; include the kind of thing being named instead of relying on the module path to supply it. For example, use `io_stream::BufferedStream` rather than `io_stream::Buffered`. +- Prefer clear, consistent names. Avoid abbreviations unless they are an established domain initialism or required by an external API. +- Give each primary public struct, enum, or trait its own source file, named 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 @@ -33,15 +33,15 @@ Before introducing a new semantic, layout, or naming pattern, check how related ## Source and documentation -* Keep authored repository-root Markdown files to lowercase `readme.md`, `license.md`, and `releases.md`. -* Start `license.md` with `# MIT License`. -* Keep `readme.md` human-focused: explain the project, its motivation when useful, how to use it, recent releases, and how to contribute. Follow the `Readme Structure` guide supplied by `bake-readme`. -* Put reusable, package-specific agent guidance in `context/`; keep repository-only instructions and project-owned skills in `.agents/`. Treat the root `agents.md` as repository-owned guidance. -* 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. +- Keep authored repository-root Markdown files to lowercase `readme.md`, `license.md`, and `releases.md`. +- Start `license.md` with `# MIT License`. +- Keep `readme.md` human-focused: explain the project, its motivation when useful, how to use it, recent releases, and how to contribute. Follow the `Readme Structure` guide supplied by `bake-readme`. +- Put reusable, package-specific agent guidance in `context/`; keep repository-only instructions and project-owned skills in `.agents/`. Treat the root `agents.md` as repository-owned guidance. +- 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. ## 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. -* Use the `cargo:after_version_bump` hook registered by `socketry-project` to update `license.md`, `releases.md`, and the generated sections of `readme.md`, then normalize those files and all Markdown under the public `context/` directory. -* Follow the `socketry-project-releasing` skill to prepare and publish a release. It links to Bake Cargo task documentation for workflow setup, trusted publishing, reviewers, and tag creation. +- 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. +- Use the `cargo:after_version_bump` hook registered by `socketry-project` to update `license.md`, `releases.md`, and the generated sections of `readme.md`, then normalize those files and all Markdown under the public `context/` directory. +- Follow the `socketry-project-releasing` skill to prepare and publish a release. It links to Bake Cargo task documentation for workflow setup, trusted publishing, reviewers, and tag creation. diff --git a/context/github-repository.md b/context/github-repository.md index 93b78a0..774c154 100644 --- a/context/github-repository.md +++ b/context/github-repository.md @@ -9,11 +9,11 @@ Use these defaults when creating a Socketry repository. Preserve deliberate proj ## Repository metadata -* Use the canonical Socketry organization and project name. -* Write a short, accurate repository description. -* Set the homepage to the documentation site when one exists. -* Add focused topics for discovery; avoid repeating words already in the repository name. -* Use `main` as the default branch. +- Use the canonical Socketry organization and project name. +- Write a short, accurate repository description. +- Set the homepage to the documentation site when one exists. +- Add focused topics for discovery; avoid repeating words already in the repository name. +- Use `main` as the default branch. ## Collaboration features @@ -21,21 +21,21 @@ Enable Issues, Discussions, Pull Requests, Sponsorships, and repository preserva Use GitHub issue types to classify issues consistently: -* `Bug` for defects and regressions. -* `Feature` for new user-facing capabilities. -* `Task` for maintenance, refactoring, documentation, tests, and release work. +- `Bug` for defects and regressions. +- `Feature` for new user-facing capabilities. +- `Task` for maintenance, refactoring, documentation, tests, and release work. Prefer organization or repository labels that already exist. Add labels only when the project needs a reusable classification not covered by issue types or existing labels. Do not repeat issue type information in issue text when GitHub already records it as metadata. Issue types apply to issues; do not assign one to a pull request or include issue type information in its text. ## Pull requests and commits -* Disable merge commits; allow squash and rebase merging. -* Suggest updating pull request branches, allow auto-merge, and delete merged head branches automatically. -* Require contributors to sign off on commits made through GitHub's web interface. -* Allow comments on individual commits. -* Use Markdown, complete sentences, and a final period for pull request titles and commit messages. -* Keep most commit messages to one line. Start with what changed. -* Describe pull requests with a short summary followed by the problem and solution. Do not add a separate change type section or assign an issue type to a pull request. +- Disable merge commits; allow squash and rebase merging. +- Suggest updating pull request branches, allow auto-merge, and delete merged head branches automatically. +- Require contributors to sign off on commits made through GitHub's web interface. +- Allow comments on individual commits. +- Use Markdown, complete sentences, and a final period for pull request titles and commit messages. +- Keep most commit messages to one line. Start with what changed. +- Describe pull requests with a short summary followed by the problem and solution. Do not add a separate change type section or assign an issue type to a pull request. Use the `socketry-project-pull-requests` skill for the full title, commit, description, testing, and release note conventions. diff --git a/context/pull-requests.md b/context/pull-requests.md index 78675ee..9622d90 100644 --- a/context/pull-requests.md +++ b/context/pull-requests.md @@ -9,12 +9,12 @@ Use these conventions when preparing commits or pull requests for Socketry Rust ## Titles and commits -* Pull request titles must use Markdown, be complete sentences, and end with a full stop. -* Commit messages must use Markdown and end with a full stop. -* The first line of a commit message must focus on what changed. -* Most commit messages should be a single line. -* Keep relevant context in the code itself, such as comments, rather than using the commit message as a side channel for important details. -* Do not include agent links, attribution footers, generated-by annotations, or similar metadata in commit messages. +- Pull request titles must use Markdown, be complete sentences, and end with a full stop. +- Commit messages must use Markdown and end with a full stop. +- The first line of a commit message must focus on what changed. +- Most commit messages should be a single line. +- Keep relevant context in the code itself, such as comments, rather than using the commit message as a side channel for important details. +- Do not include agent links, attribution footers, generated-by annotations, or similar metadata in commit messages. ## Pull request description @@ -46,6 +46,6 @@ For user-visible changes, add a brief entry to `releases.md` following the relea Issue types apply to GitHub issues. Do not try to set an issue type when creating or updating a pull request. For a linked issue, use its issue type: -* Use `Bug` for defect fixes and regressions. -* Use `Feature` for new user-facing capabilities. -* Use `Task` for maintenance, refactoring, documentation, tests, release work, and internal improvements. +- Use `Bug` for defect fixes and regressions. +- Use `Feature` for new user-facing capabilities. +- Use `Task` for maintenance, refactoring, documentation, tests, release work, and internal improvements. diff --git a/context/releasing.md b/context/releasing.md index 3f02d74..66639fd 100644 --- a/context/releasing.md +++ b/context/releasing.md @@ -32,7 +32,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.2.0 or newer. +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. 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 53bc3cf..c3fe7bb 100644 --- a/context/setup.md +++ b/context/setup.md @@ -27,7 +27,7 @@ cargo bake --regenerate The command creates `bake/`, adds it to the Cargo workspace, and writes a minimal binary. Add this dependency under the existing `[dependencies]` table in `bake/Cargo.toml`: ```toml -socketry-project = ">=0.3.3" +socketry-project = ">=0.3.6" ``` The open-ended minimum requirement allows newer `socketry-project` releases. The private Bake package's `Cargo.lock` records the selected version, so update the lockfile deliberately when adopting a newer release. @@ -59,7 +59,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.2.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. 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. ## Work on the project diff --git a/context/testing.md b/context/testing.md index 6a2b400..ad7d933 100644 --- a/context/testing.md +++ b/context/testing.md @@ -9,11 +9,11 @@ Use this skill whenever a change adds or changes behavior that should be verifie ## Expectations -* Add tests that exercise the changed behavior and relevant regression cases. -* Require 100% region coverage for supported target and feature configurations. Use LLVM's region report to find executable paths that tests have not run. -* Treat uncovered code as an opportunity to review semantics. Check that its behavior is correct, add tests for meaningful behavior, and fix defects rather than writing tests that codify accidental behavior. Remove dead code or make invariants explicit when a region cannot represent supported behavior; do not manufacture impossible internal states just to reach it. -* 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. +- Add tests that exercise the changed behavior and relevant regression cases. +- Require 100% region coverage for supported target and feature configurations. Use LLVM's region report to find executable paths that tests have not run. +- Treat uncovered code as an opportunity to review semantics. Check that its behavior is correct, add tests for meaningful behavior, and fix defects rather than writing tests that codify accidental behavior. Remove dead code or make invariants explicit when a region cannot represent supported behavior; do not manufacture impossible internal states just to reach it. +- 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. @@ -21,10 +21,10 @@ Follow the repository's test layout guidance when choosing between unit and inte Use real temporary directories for normal filesystem behavior. When an important error path depends on an operating-system failure that is difficult to trigger reliably, a private `#[cfg(test)]` shim can make that failure deterministic: -* Keep production builds delegated directly to the standard library. -* In tests, wrap only the needed operation and delegate to the real filesystem except for a specifically injected failure. -* Scope injected failures to the operation and path, and isolate them from parallel tests. -* Assert observable behavior, such as the returned error and whether changes were rolled back or cleaned up. +- Keep production builds delegated directly to the standard library. +- In tests, wrap only the needed operation and delegate to the real filesystem except for a specifically injected failure. +- Scope injected failures to the operation and path, and isolate them from parallel tests. +- Assert observable behavior, such as the returned error and whether changes were rolled back or cleaned up. Filesystem error kinds and path resolution vary by operating system. Inject failures for portable error-path tests; use platform-gated tests when the OS-specific behavior itself is what the test needs to verify. diff --git a/context/update.md b/context/update.md index 35986c6..8cbe189 100644 --- a/context/update.md +++ b/context/update.md @@ -9,9 +9,9 @@ Use this skill to bring an existing crate repository up to the current Socketry ## Read the project's guidance -* Follow the repository's `agents.md` and project-specific instructions. -* Run `cargo bake agent:context:install` when shared task dependencies change or installed context may be missing or stale. Read `.agents/context/index.md` and the skills that apply to the work. -* Consult the current `socketry-project` context and the installed `bake-*` context for task behavior. Prefer those task guides over copying their implementation details into this skill. +- Follow the repository's `agents.md` and project-specific instructions. +- Run `cargo bake agent:context:install` when shared task dependencies change or installed context may be missing or stale. Read `.agents/context/index.md` and the skills that apply to the work. +- Consult the current `socketry-project` context and the installed `bake-*` context for task behavior. Prefer those task guides over copying their implementation details into this skill. ## Audit the current baseline @@ -19,20 +19,20 @@ Review the repository's Cargo manifests, source and test layout, standard root f Check these areas: -* **Cargo and Bake setup:** package and workspace boundaries, the private `bake/` package, the shared `socketry-project` dependency, and generated task links. -* **Project files:** lowercase `readme.md`, `license.md`, and `releases.md`, with standard sections and generated content maintained by shared tasks. -* **Agent context:** reusable package guidance in `context/`, project-only instructions and skills in `.agents/`, and current installed context and skills. -* **Testing:** tests for behavior, the 100% region-coverage expectation, and downstream testing where public compatibility makes it useful. Use the `socketry-project` Testing context and installed `bake-test-rust` guide for the current policy and task details. -* **GitHub workflows:** the standard test and publish workflows, plus external testing when downstream projects are configured. Use the GitHub repository skill for repository settings and the `socketry-project-releasing` skill for publishing workflow setup. Consult the Bake Cargo Readme for task behavior, workflow generation, and trusted-publishing details. +- **Cargo and Bake setup:** package and workspace boundaries, the private `bake/` package, the shared `socketry-project` dependency, and generated task links. +- **Project files:** lowercase `readme.md`, `license.md`, and `releases.md`, with standard sections and generated content maintained by shared tasks. +- **Agent context:** reusable package guidance in `context/`, project-only instructions and skills in `.agents/`, and current installed context and skills. +- **Testing:** tests for behavior, the 100% region-coverage expectation, and downstream testing where public compatibility makes it useful. Use the `socketry-project` Testing context and installed `bake-test-rust` guide for the current policy and task details. +- **GitHub workflows:** the standard test and publish workflows, plus external testing when downstream projects are configured. Use the GitHub repository skill for repository settings and the `socketry-project-releasing` skill for publishing workflow setup. Consult the Bake Cargo Readme for task behavior, workflow generation, and trusted-publishing details. Classify findings as required baseline changes, optional recommendations, or valid project-specific exceptions. Preserve deliberate local architecture and custom workflows when they do not conflict with an explicit organization convention. ## Apply updates with shared tasks -* Use `cargo bake --regenerate` after adding or changing task dependencies so generated task links match the Bake package. -* Use shared tasks such as `license:update`, `readme:update`, and `cargo:setup:workflow` where they apply. Review generated workflow changes before replacing project-specific configuration. -* Use `cargo bake test:coverage` for the standard local coverage check. Consult `bake-test-rust` for feature, target, and optional downstream test setup. -* Let `cargo:after_version_bump` refresh standard release files during release preparation. Follow the `socketry-project-releasing` skill for version bumps, validation, and the reviewed GitHub release process. -* Keep changes focused on the identified baseline gaps; do not rewrite valid project-specific choices merely to match an example layout. +- Use `cargo bake --regenerate` after adding or changing task dependencies so generated task links match the Bake package. +- Use shared tasks such as `license:update`, `readme:update`, and `cargo:setup:workflow` where they apply. Review generated workflow changes before replacing project-specific configuration. +- Use `cargo bake test:coverage` for the standard local coverage check. Consult `bake-test-rust` for feature, target, and optional downstream test setup. +- Let `cargo:after_version_bump` refresh standard release files during release preparation. Follow the `socketry-project-releasing` skill for version bumps, validation, and the reviewed GitHub release process. +- Keep changes focused on the identified baseline gaps; do not rewrite valid project-specific choices merely to match an example layout. Review the final diff and summarize completed baseline changes, optional recommendations, and any retained project-specific exceptions. diff --git a/readme.md b/readme.md index 9679c35..7c752c3 100644 --- a/readme.md +++ b/readme.md @@ -18,12 +18,12 @@ cargo bake --regenerate Add this dependency under the existing `[dependencies]` table in `bake/Cargo.toml`: ```toml -socketry-project = ">=0.3.3" +socketry-project = ">=0.3.6" ``` Then run `cargo bake --regenerate` again to link the dependency's tasks. The command keeps generated links separate from task source, so no manual import in `main.rs` is needed. Run `cargo bake --list` to see the available tasks. The open-ended minimum requirement keeps this development dependency eligible for newer releases. `Cargo.lock` records the selected version for reproducible builds; update it deliberately when adopting a newer release. -This adds the standard Cargo, release, license, Readme, agent-context, and testing tasks, including `test` and `test:external`. It also registers a version-bump hook that updates the project's standard files. +This adds the standard Cargo, release, license, Readme, Markdown, agent-context, and testing tasks, including `test` and `test:external`. It also registers a 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) explains source organization. The testing skill sets expectations and points to `bake-test-rust` for task and workflow details. @@ -39,17 +39,18 @@ See [releases.md](releases.md) for the full release history. ### v0.3.6 -* Normalize standard project Markdown files after version bumps. -* Fix the version bump hook's invocation of the Markdown normalizer. +- Normalize standard project Markdown files after version bumps. +- Fix the version bump hook's invocation of the Markdown normalizer. +- Include `bake-markdown` 0.3.0 in the shared task set so version bumps use hyphen markers for unordered lists. ### v0.3.5 -* Require `bake-test-rust` 0.3.0 or newer for LLVM region coverage and update the shared testing guidance to match. +- Require `bake-test-rust` 0.3.0 or newer for LLVM region coverage and update the shared testing guidance to match. ### v0.3.4 -* Require Bake 0.18.0 and Bake Cargo 0.4.0 for shared task registration. -* Document a test-only shim pattern for deterministic coverage of difficult I/O failures. +- Require Bake 0.18.0 and Bake Cargo 0.4.0 for shared task registration. +- Document a test-only shim pattern for deterministic coverage of difficult I/O failures. diff --git a/releases.md b/releases.md index dfd5420..a749539 100644 --- a/releases.md +++ b/releases.md @@ -2,81 +2,82 @@ ## v0.3.6 -* Normalize standard project Markdown files after version bumps. -* Fix the version bump hook's invocation of the Markdown normalizer. +- Normalize standard project Markdown files after version bumps. +- Fix the version bump hook's invocation of the Markdown normalizer. +- Include `bake-markdown` 0.3.0 in the shared task set so version bumps use hyphen markers for unordered lists. ## v0.3.5 -* Require `bake-test-rust` 0.3.0 or newer for LLVM region coverage and update the shared testing guidance to match. +- Require `bake-test-rust` 0.3.0 or newer for LLVM region coverage and update the shared testing guidance to match. ## v0.3.4 -* Require Bake 0.18.0 and Bake Cargo 0.4.0 for shared task registration. -* Document a test-only shim pattern for deterministic coverage of difficult I/O failures. +- Require Bake 0.18.0 and Bake Cargo 0.4.0 for shared task registration. +- Document a test-only shim pattern for deterministic coverage of difficult I/O failures. ## v0.3.3 -* Point the project update skill at the shared Releasing skill and Bake Cargo task documentation. +- Point the project update skill at the shared Releasing skill and Bake Cargo task documentation. ## v0.3.2 -* Add a shared Releasing skill and remove links to duplicated Cargo publishing guidance. -* Update the setup instructions to use `socketry-project` 0.3. +- Add a shared Releasing skill and remove links to duplicated Cargo publishing guidance. +- Update the setup instructions to use `socketry-project` 0.3. ## v0.3.1 -* 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. +- 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 projects. +- Add an update skill for auditing and modernizing existing Socketry Rust projects. ## v0.2.7 -* Clarify how context installation uses `.agents/context/index.md` and local Git exclusions without changing a repository-owned `agents.md`. -* Express shared task dependencies as minimum versions so compatible updates can be selected by the host project's lockfile. -* Require 100% line coverage for workspace targets in GitHub Actions. -* Use the shared `bake-test-rust` coverage task in the standard workflow. -* Cover Bake task execution and the version-bump hook's task ordering. +- Clarify how context installation uses `.agents/context/index.md` and local Git exclusions without changing a repository-owned `agents.md`. +- Express shared task dependencies as minimum versions so compatible updates can be selected by the host project's lockfile. +- Require 100% line coverage for workspace targets in GitHub Actions. +- Use the shared `bake-test-rust` coverage task in the standard workflow. +- Cover Bake task execution and the version-bump hook's task ordering. ## v0.2.6 -* Support `bake-agent-context` 0.2 while retaining compatibility with 0.1. -* Keep the generated context index under `.agents/context/` without modifying the repository owner's `agents.md`. +- Support `bake-agent-context` 0.2 while retaining compatibility with 0.1. +- Keep the generated context index under `.agents/context/` without modifying the repository owner's `agents.md`. ## v0.2.5 -* Distribute repository setup, GitHub setup, and pull request guidance as installable skills. -* Provide shared Agent Context guidance through `bake-agent-context`. +- Distribute repository setup, GitHub setup, and pull request guidance as installable skills. +- Provide shared Agent Context guidance through `bake-agent-context`. ## v0.2.4 -* Clarify crate namespaces, descriptive type names, module layout, and test paths. +- Clarify crate namespaces, descriptive type names, module layout, and test paths. ## v0.2.3 -* Rename the project guides to shorter context filenames and titles. -* Clarify source, test, naming, and coverage conventions. +- Rename the project guides to shorter context filenames and titles. +- Clarify source, test, naming, and coverage conventions. ## v0.2.2 -* Use Bake Cargo's GitHub Release automation in the standard publishing workflow. +- Use Bake Cargo's GitHub Release automation in the standard publishing workflow. ## v0.2.1 -* Document setup and task linking with `cargo bake --regenerate`. +- Document setup and task linking with `cargo bake --regenerate`. ## v0.2.0 -* Move the shared project tasks to `bake` 0.17 and include standard Rust test tasks. -* Document standard local, downstream, and publishing workflows. +- Move the shared project tasks to `bake` 0.17 and include standard Rust test tasks. +- Document standard local, downstream, and publishing workflows. ## v0.1.1 -* Add a reusable Pull Requests guide to the packaged agent context. +- Add a reusable Pull Requests guide to the packaged agent context. ## v0.1.0 -* Establish shared conventions and standard Bake tasks for Socketry Rust projects. -* Document project layout, GitHub setup, and agent context installation. +- Establish shared conventions and standard Bake tasks for Socketry Rust projects. +- Document project layout, GitHub setup, and agent context installation. diff --git a/src/lib.rs b/src/lib.rs index ed6dfd1..eba37ae 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,6 +9,7 @@ use bake::{Context, Result}; use bake_agent_context as _; use bake_cargo as _; use bake_license as _; +use bake_markdown as _; use bake_readme as _; use bake_releases as _; use bake_test_rust as _; diff --git a/src/tests.rs b/src/tests.rs index b16fb88..79ab7fc 100644 --- a/src/tests.rs +++ b/src/tests.rs @@ -70,17 +70,36 @@ fn registry() -> Registry { ) .unwrap(); registry - .register(Task::new( + .replace( "markdown:normalize", - "", - vec![Parameter::new::("paths").variadic()], - normalize_markdown, - )) + Task::new( + "markdown:normalize", + "", + vec![Parameter::new::("paths").variadic()], + normalize_markdown, + ), + ) .unwrap(); registry } +#[test] +fn exports_markdown_normalization_with_hyphen_markers() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("readme.md"); + std::fs::write(&path, "* first\n* second\n").unwrap(); + + let registry = Registry::discover().unwrap(); + let mut context = registry.context(directory.path()); + context.call("markdown:normalize", &["readme.md"]).unwrap(); + + assert_eq!( + std::fs::read_to_string(path).unwrap(), + "- first\n- second\n" + ); +} + #[test] fn refreshes_project_files_in_order_for_the_requested_version() { let registry = registry();