diff --git a/AGENTS.md b/AGENTS.md index 36bc6b825..73fcf987b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,15 +4,18 @@ This file provides guidance to LLM agents when working with code in this reposit ## Project status -This working tree **is** the upcoming **v0.8.0** release. Every crate under [crates/](crates) is -versioned `0.8.0-alpha` in its `Cargo.toml` — the pre-release of v0.8.0 — and the documentation in the -[knowledge base](https://github.com/contextgeneric/cgp-knowledge-base/tree/main/cgp) already refers to -the current version as v0.8.0, so nothing needs a version edit when v0.8.0 ships. - -The stable release on crates.io is still **v0.7.0**, and it is not compatible with this tree. v0.7.0 -carries legacy features and syntax that v0.8.0 has removed or changed, so code or documentation -written against v0.7.0 will not compile here. Treat crates.io v0.7.0 as a separate, older line and -do not reconcile this tree's syntax against it. +This working tree **is** the upcoming **v0.8.0** release. Its crates may carry a pre-release version +such as `0.8.0-alpha` in their `Cargo.toml`, published to crates.io as a test run of the release +process; that suffix is not a version anyone documents or tracks. **Every document, comment, and +README describes this tree as v0.8.0**, as though it had already been published, per the knowledge +base's [rule on versions](https://github.com/contextgeneric/cgp-knowledge-base/blob/main/AGENTS.md#document-official-versions-never-pre-releases): +never name a pre-release, describe how one behaves, or compare one with the source, unless the user +explicitly asks. The same holds for every sibling crate, `cargo-cgp` v0.1.0 included. + +The previous official release, **v0.7.0**, is not compatible with this tree. v0.7.0 carries legacy +features and syntax that v0.8.0 has removed or changed, so code or documentation written against +v0.7.0 will not compile here. Treat v0.7.0 as a separate, older line and do not reconcile this tree's +syntax against it. Only the library crates are published. The five crates under [crates/tests/](crates/tests) are marked `publish = false`, so `cargo publish --workspace` skips them and publishes just the real CGP @@ -170,7 +173,8 @@ inward (core/macros) when changing fundamentals, outward (main) only to adjust t ## Conventions specific to this repo -- All versions are kept in lockstep at the workspace level (currently **0.8.0-alpha**); inter-crate +- All versions are kept in lockstep at the workspace level (the release in preparation, **0.8.0**, + whatever pre-release suffix the manifests carry while it is tested); inter-crate dependencies are declared once in the root [Cargo.toml](Cargo.toml) `[workspace.dependencies]` and referenced with `{ workspace = true }`. Add new crates to the `members` list and the workspace dependency table together. A crate that exists only for testing also gets diff --git a/README.md b/README.md index 2360fea77..97deef9b6 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Context-Generic Programming (CGP) is a library on stable Rust that lifts the language's one-implementation-per-type limit off your traits: it lets one interface have many interchangeable implementations and lets each *context* — an application, a test, a deployment — plug in the one it uses. The choice is written in one readable place and resolved entirely during compilation, so it compiles down to direct calls: there is no runtime container, no reflection, and nothing left in the binary for an implementation a context does not use. > [!IMPORTANT] -> The `main` branch tracks the upcoming **v0.8.0** release (published as `0.8.0-alpha` pre-release crates). The current stable release on crates.io is **v0.7.0**, which is **not compatible** with this branch — v0.8.0 changes and removes syntax that v0.7.0 used. **All documentation in this repository describes v0.8.0 only.** For v0.7.0, refer to its published crate documentation instead. +> This repository describes **v0.8.0**, which is **not compatible** with v0.7.0 — v0.8.0 changes and removes syntax that v0.7.0 used. **All documentation in this repository describes v0.8.0 only.** For v0.7.0, refer to its published crate documentation instead. **[Website](https://contextgeneric.dev/) · [crates.io](https://crates.io/crates/cgp)** @@ -105,13 +105,6 @@ use cgp::prelude::*; CGP requires **Rust 1.89+** and runs on the **stable** toolchain — no nightly, no fork. -> [!NOTE] -> `cargo add cgp` installs the current stable release, **v0.7.0**. The examples in this repository target **v0.8.0**; to follow them today, depend on the pre-release from `main`: -> ```toml -> cgp = { git = "https://github.com/contextgeneric/cgp" } -> ``` -> Once v0.8.0 is released, `cargo add cgp` will install it. - ### Install cargo-cgp for readable errors CGP compiles to ordinary Rust, so a wiring mistake surfaces as a compiler error about generated types — often a wall of them with the real cause buried. **When you start with CGP, install [`cargo-cgp`](https://github.com/contextgeneric/cargo-cgp) alongside it.** cargo-cgp is CGP's error toolchain: a drop-in for `cargo check` that rewrites those errors into a compact, root-cause-first form, leading with the field or wiring that actually failed. It is the single biggest quality-of-life improvement for writing CGP, so treat it as part of your getting-started setup. @@ -121,7 +114,7 @@ cargo install cargo-cgp # the front-end (installs on any toolchain) cargo cgp setup # provisions the compiler + driver it needs ``` -Then run `cargo cgp check` wherever you would run `cargo check`; it forces the pinned nightly that `cargo cgp setup` installed only for its own check, so your project keeps its toolchain untouched. (Prefer Nix? `nix run github:contextgeneric/cargo-cgp/v0.1.0-alpha -- check` runs it without installing.) cargo-cgp is an early pre-release that already makes the common wiring errors readable and is steadily covering more; see its [README](https://github.com/contextgeneric/cargo-cgp) for the full guide. +Then run `cargo cgp check` wherever you would run `cargo check`; it forces the pinned nightly that `cargo cgp setup` installed only for its own check, so your project keeps its toolchain untouched. (Prefer Nix? `nix run github:contextgeneric/cargo-cgp/v0.1.0 -- check` runs it without installing.) cargo-cgp is an early release that already makes the common wiring errors readable and is steadily covering more; see its [README](https://github.com/contextgeneric/cargo-cgp) for the full guide. cargo-cgp is optional and adds only a diagnostic `check`: keep building, running, and testing with ordinary cargo — CGP is a plain library needing only stable Rust (1.89+) — and reach for `cargo cgp check` when you want a wiring error made readable. Plain `cargo check` still works too, and is fine when you are not expecting a compile error. @@ -147,7 +140,7 @@ Contributors and coding agents have a second, deeper source: the [CGP knowledge ## Project status -CGP works today on stable Rust and already offers a broad feature set: components and providers, abstract types, extensible records and variants, a handler and computation family, namespaces, and modular error handling. It is also young — the paradigm and its ecosystem are still evolving, and v0.8.0 is a pre-release — so adopting it is a real decision rather than a foregone one. +CGP works today on stable Rust and already offers a broad feature set: components and providers, abstract types, extensible records and variants, a handler and computation family, namespaces, and modular error handling. It is also young — the paradigm and its ecosystem are still evolving — so adopting it is a real decision rather than a foregone one. Two properties make it low-risk to try. Because CGP is a superset of ordinary traits, it can be introduced in one corner of a codebase and stepped back from without a rewrite; and because it imposes no runtime, it does not lock a project into a framework's lifecycle. If you are evaluating it for a team, start small, and lean on the worked examples on the [website](https://contextgeneric.dev/) to gauge the learning curve honestly.