Skip to content

Describe main as v0.8.0 without the pre-release #280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
soareschen merged 1 commit into from
Oct 11, 2026
Merged

Describe main as v0.8.0 without the pre-release #280

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
13 changes: 3 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)**

Expand Down Expand Up @@ -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.
Expand All @@ -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.

Expand All @@ -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.

Expand Down
Loading