socketry-project 0.2.0

Shared project conventions and development tasks for Socketry Rust crates
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

# Set Up a Socketry Rust Project

Use this guide to start a Rust repository with the shared Socketry conventions,
agent context, and release tasks.

## 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.

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 the root files described in
[Rust Project Layout](project-layout.md). Keep the library's dependencies in
the root package and development automation in a private `bake/` workspace
member.

## Add shared project tasks

In the root `Cargo.toml`, add the private Bake member and release reviewers:

```toml
[workspace]
members = ["bake"]
resolver = "3"

[workspace.metadata.bake]
manifest = "bake/Cargo.toml"

[workspace.metadata.bake.release]
reviewers = ["socketry/managers"]
```

Create `bake/Cargo.toml` with `publish = false`, then add the shared task crates
as dependencies there, rather than to the library package:

```toml
[package]
name = "project-bake"
version = "0.0.0"
edition = "2024"
publish = false

[dependencies]
bake = "0.17"
socketry-project = "0.2"
```

Create `bake/src/main.rs`:

```rust,ignore
use bake::{Registry, Result};
use socketry_project as _;

fn main() -> Result<()> {
    Registry::discover()?.run()
}
```

The `socketry-project` dependency links the shared tasks into the private Bake
binary. It also registers `cargo:after_version_bump`, which updates `license.md`,
`releases.md`, and generated sections in `readme.md` after a version change.
It bundles the standard `test` and `test:external` task providers as well.
Keep task tooling out of unrelated published libraries. Consumer projects
should depend on `socketry-project` from their private `bake/` package.

Install the Bake command and the project's agent context:

```sh
cargo install socketry-cargo-bake --locked
cargo bake agent:context:install
```

This installs all context guides provided by resolved dependencies under
`.agents/context/` and updates `agents.md` with links. Read that index, then
open the guides relevant to the work. Add `--package socketry-project` to
install only this crate's guides. See [Agent Context](agent-context.md) for how
to organize and update shared and project-only guidance.

## Set up GitHub

Configure repository metadata, collaboration features, pull request defaults,
and branch protection using [GitHub Repository Setup](github-repository.md).
Generate the Cargo workflow with `cargo:setup:workflow`; follow the
[Cargo Publishing guide](https://github.com/socketry/bake-cargo-rust/blob/main/context/publishing.md)
before applying rulesets, environment reviewers, or crates.io trusted
publishing.

## Standard workflows

Keep `.github/workflows/test.yml` for local workspace tests. When
`bake-test-rust` is linked, install the Cargo launcher and run
`cargo bake --locked test` so the optional `test:before` hook also runs.
Otherwise use `cargo test --workspace --locked`. Add platform or feature
matrix entries when the project needs them.

List selected downstream projects under
`[workspace.metadata.bake.test.external]` in the root `Cargo.toml`. Add
`.github/workflows/external.yml` only when that list is non-empty, and run
`cargo bake --locked test:external` when `bake-test-rust` is linked. The task
keeps checkouts under `external/` and applies local workspace crates as Cargo
patches so downstream tests exercise the source being developed.

Use `cargo:setup:workflow` from `bake-cargo` to generate
`.github/workflows/publish.yml`. That workflow checks a release candidate on
pull requests and publishes after merge through the configured `crates-io`
environment. See the [Rust Testing](testing.md) guide for test workflow details
and the Cargo Publishing guide for release setup.

## 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.