# 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
Install the Cargo launcher and bootstrap the private task package:
```sh
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`:
```toml
socketry-project = "0.2"
```
Run regeneration again to link its task registrations:
```sh
cargo bake --regenerate
```
Set release reviewers in the root `Cargo.toml`:
```toml
[workspace.metadata.bake.release]
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.
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 project's agent context:
```sh
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, publishes after merge through the configured `crates-io`
environment, and then creates or updates the matching GitHub Release from
`releases.md`. See the [Cargo Publishing guide](https://github.com/socketry/bake-cargo-rust/blob/main/context/publishing.md)
for trusted publishing and repository setup. See the [Rust Testing](testing.md)
guide for test workflow details and optional downstream compatibility workflow.
## 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.