Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
126 changes: 126 additions & 0 deletions .claude/skills/update-rue-docs/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
---
name: update-rue-docs
description: Update the Rue docs for a new Rue release (or commit), based on the Rue diff since the version the docs were last written against. Use when asked to update, sync or refresh the docs for a Rue release.
argument-hint: "<release tag or commit, default: latest release>"
---

# Update the Rue docs

The pages in `docs/` document the [Rue](https://github.com/xch-dev/rue) language, standard library and
tooling. The Rue version they're written against is in `.rue-version`. Your job is to bring the docs up
to date with a newer Rue release (the argument, or the latest release if none is given), and open a PR.

## 1. Get the diff

1. Clone or update Rue somewhere outside this repo (or use an existing checkout, read only). Check out
the target in a separate worktree, so you have its source to read: `git worktree add --detach <dir> <target>`.
2. Resolve the target to a tag or full commit hash, and diff it against the tag in `.rue-version`:
`git log --oneline <old>..<target>` and `git diff <old>..<target> -- crates README.md tests examples`.
Ignore CI, benchmarks, dependency bumps and internal refactors that don't change what users see.
3. Read the release notes (`gh release view <tag> --repo xch-dev/rue`) and the descriptions of the
merged PRs (`gh pr view <number> --repo xch-dev/rue`) for intent, especially for behaviour changes.
4. Build the CLI at the target (`cargo build --release -p rue-cli` in the worktree), so you can try
claims and run the example check against it. Don't rely on whatever `rue` is on PATH.

These are the places in the Rue repo that define what the docs describe:

| Area | Where to look |
| --------------------- | ----------------------------------------------------------------------------------------- |
| Syntax and keywords | `crates/rue-lexer`, `crates/rue-parser/src/grammar` |
| Rules and errors | `crates/rue-diagnostic/src/kind.rs`, `crates/rue-compiler/src/compile` |
| Builtins | `crates/rue-hir/src/builtins.rs`, `crates/rue-compiler/src/compile/expr/function_call.rs` |
| Standard library | `crates/rue-compiler/src/std` (written in Rue) |
| Operators | `crates/rue-compiler/src/compile/expr/binary.rs`, `prefix.rs`, and `binary_binding_power` |
| Lints | `crates/rue-lint`, and `rue lints` |
| CLI | `crates/rue-cli`, and `rue <command> --help` |
| `Rue.toml` | `crates/rue-options` |
| Language server | `crates/rue-lsp` (the server capabilities) |
| Examples of behaviour | `tests/` and `examples/` (`.rue` files, with `.yaml` snapshots of output and diagnostics) |

## 2. Plan the changes

Sort every relevant change into one of these, and map it to the pages it affects (`grep -rn` the docs
for the keyword, type, function, flag or lint involved):

- **New features** (syntax, builtins, standard library items, CLI commands and flags, `Rue.toml` keys,
lints, language server features): add them to the relevant page, or write a new page for a major
feature.
- **Changed behaviour** (type checking, narrowing, inference, codegen, defaults, error rules): rewrite
the affected prose. The example check won't find most of these, so read the diff and the changed
tests carefully, and check every claim on the affected pages against the new source.
- **Renames and changed signatures**: update the prose and examples. The example check finds most of these.
- **Removals**: remove or replace them, including in examples.

Also check the tables and lists that summarize the language, since they go stale quietly:

- `docs/lints.md`: the lint tables (regenerate them from `rue lints`, grouped the same way, and escape
`|` as `\|` inside table cells), the levels, the groups, and the naming conventions.
- `docs/cli.md`: the command table and every flag table, against `--help` for each command.
- `docs/projects.md` and `docs/formatting.md`: the `Rue.toml` keys and defaults, and the manifest that
`rue init` generates (it includes the version).
- `docs/builtins.md` and `docs/standard-library.md`: every builtin and standard library item, with
its signature.
- `docs/operators.md`: the operator tables and the precedence table.
- `docs/type-system/atoms.md`: the atom types and the literal table.
- `docs/installation.md`: the editor support and the hello world output.
- `sidebars.ts`, if pages are added, moved or removed.

For a large diff, split independent pages between subagents, giving each this skill's conventions,
the target's source and CLI, and the pages it owns.

## 3. Update the docs

Conventions:

- The docs describe Rue as it is at the target version, as if it's always been that way. Don't label
anything as new, don't mention Rue versions in prose (other than `.rue-version`, the `rue init`
manifest sample, and the tutorials' "last tested with" notes), and don't describe old behaviour.
- Every claim must match what the compiler actually does. When in doubt, compile a scratch program
with the target's CLI rather than trusting the source's comments or the old docs.
- Pages are conceptual: what something is, when to use it, how it fits with the rest of the language,
then realistic examples, then gotchas. Keep the existing pages' structure and tone: plain, direct
prose, no marketing language or emoji.
- Every ` ```rue ` block is checked by `pnpm check:rue-examples` (see `scripts/check-rue-examples.py`):
it must compile with no errors or warnings (unused items are allowed), its tests must pass, and it
must be formatted the way `rue fmt` formats it. Prefer complete examples with a `fn main` or `test fn`.
Use an info string only where needed:
- ` ```rue ignore ` for a fragment that continues an earlier block, a file of a multi-file example
(such as one that imports a sibling module), or code that needs a file that isn't there.
- ` ```rue error ` for a block that deliberately shows an error. Put the error in a comment.
- ` ```rue warn ` for a block that deliberately shows a warning.
- ` ```rue nofmt ` only where `rue fmt`'s output is clearly worse, with an MDX comment
(`{/* ... */}`) next to it saying why. Remove these when the formatter is fixed.
- If an example shows output (CLI output in a ` ```bash ` block, a compiled program, a hash), run it
with the target's CLI and paste the real output.
- Link other pages with `/docs/<path>.md#anchor`. `pnpm build` fails on broken links and anchors.
- New pages get a `slug` in their front matter, matching the existing pages, and an entry in `sidebars.ts`.
- The Rue syntax highlighter is `src/theme/prism-rue.ts`. Update it if keywords, literals or
operators change.

### Tutorials

The tutorials in `docs/tutorials` use the [Chia Wallet SDK](https://crates.io/crates/chia-wallet-sdk),
which compiles Rue with its own copy of the compiler. If a released `chia-wallet-sdk` depends on the
target Rue version (check the `rue-compiler` version in its `Cargo.toml`), follow each tutorial end to
end in a scratch directory with that SDK version (`rue init`, `cargo init --lib`, `cargo add
chia-wallet-sdk@<version> anyhow sha2`, then each checkpoint's code), and make sure `cargo test` passes.
Then update the Rue and Wallet SDK versions in each tutorial's "last tested with" list. If no SDK
release uses the target yet, leave the tutorials' versions alone, and say so in the PR.

## 4. Verify

1. Update `.rue-version` to the target version, and update the version in the `rue init` manifest
sample in `docs/projects.md`.
2. Run `pnpm check:rue-examples --rue <path to the target's rue binary>` until every example passes.
Failures name the markdown file and the line of the block.
3. Have a separate reviewer (a subagent given the changed pages, the target's source and its CLI, not
your conclusions) check the prose, tables and examples against the source, and fix what it finds.
4. Run `pnpm exec prettier --write .`, `pnpm prettier`, `pnpm typecheck` and `pnpm build`, and make
sure the build has no broken links or anchors.

## 5. Open a PR

Work on a branch, commit, and open a PR against `main` that names the Rue range (`<old>..<new>`), what
changed in the docs and why, which tutorials were re-tested, and anything you couldn't cover (such as
a behaviour you think is a compiler bug, rather than documenting it as intended). Follow the user's
branch naming and attribution preferences.
27 changes: 27 additions & 0 deletions .github/workflows/deploy-pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,33 @@ jobs:
with:
path: ./build

rue-examples:
timeout-minutes: 20
runs-on: ubuntu-latest

steps:
- name: Checkout
uses: actions/checkout@v7

- name: Read the Rue version
id: rue
run: echo "version=$(cat .rue-version)" >> "$GITHUB_OUTPUT"

# Building rue-cli from source takes a few minutes, so the binary is cached per version
- name: Cache the Rue CLI
id: cache
uses: actions/cache@v6
with:
path: ~/.cargo/bin/rue
key: rue-cli-${{ runner.os }}-${{ steps.rue.outputs.version }}

- name: Install the Rue CLI
if: steps.cache.outputs.cache-hit != 'true'
run: cargo install rue-cli --version "${{ steps.rue.outputs.version }}" --locked

- name: Check Rue examples
run: python3 scripts/check-rue-examples.py

deploy:
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
needs: build
Expand Down
1 change: 1 addition & 0 deletions .rue-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
0.12.0
12 changes: 12 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,15 @@ pnpm prettier
pnpm typecheck
pnpm build
```

CI also checks the Rue examples in the docs, with the Rue CLI at the version in `.rue-version`. To run the check locally, install that version (`cargo install rue-cli --version <version>`) and run:

```bash
pnpm check:rue-examples
```

Every ` ```rue ` block must compile without errors or warnings, pass its tests, and be formatted the way `rue fmt` formats it. See `scripts/check-rue-examples.py` for the info strings (such as ` ```rue ignore `) that change what's checked for a block.

## Updating for a Rue release

The docs describe the Rue version in `.rue-version`. The `update-rue-docs` skill in `.claude/skills` updates them for a new release: run `/update-rue-docs [version]` in Claude Code.
8 changes: 4 additions & 4 deletions docs/functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ fn add(a: Int, b: Int) -> Int {

And they can be called by other functions:

```rue
```rue ignore
fn main() -> Int {
add(42, 34)
}
Expand Down Expand Up @@ -64,7 +64,7 @@ Will compile to the CLVM `(q . 42)`.

Another kind of entrypoint is a test function, which lets you write unit tests directly alongside your Rue code:

```rue
```rue ignore
test fn verify() {
assert main() == 42;
}
Expand Down Expand Up @@ -144,7 +144,7 @@ extern fn sum_all(...numbers: List<Int>) -> Int {

Rue doesn't allow you to pass an arbitrary number of arguments directly. Instead, when a function has a spread parameter, the last argument you pass to it must also be spread:

```rue
```rue ignore
fn main() -> Int {
let list = [1, 2, 3, 4, 5];
sum_all(...list)
Expand Down Expand Up @@ -181,7 +181,7 @@ fn main(...solution: Solution) -> List<Condition> {

An `extern` function can also be loaded from a program that's already been compiled, instead of being written in Rue. The program is read from a hex file (such as one produced by `rue build --hex`, or the `.hex` files in the [chia_puzzles](https://github.com/Chia-Network/chia_puzzles) repository), with a path relative to the source file:

```rue
```rue ignore
extern fn add(a: Int, b: Int) -> Int from "./add.hex";

fn main() -> Int {
Expand Down
6 changes: 3 additions & 3 deletions docs/lints.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Among the flags, a lint's own flag takes precedence over its group's, unless the

Levels can also be set in the source code, with an `allow`, `warn`, `deny` or `forbid` attribute on an item (such as a function, constant, struct, type alias, import or module) or a statement. The attribute applies to everything inside of what it's attached to, and the innermost one takes precedence over any outer attributes and the project's levels, whether it names a lint or a group. An attribute can list multiple lints, separated by commas:

```rue
```rue warn
#[deny(unused_binding)]
mod strict {
#[allow(unused_function, unused_parameter)]
Expand All @@ -74,7 +74,7 @@ If an item or statement has more than one attribute for the same lint, the last

A `forbid` attribute works like `deny`, but nothing inside of it can change the lint's level. The same goes for lints forbidden in `Rue.toml` or on the command line. An attribute or flag that tries to change the level of a forbidden lint has no effect on it, and is reported as an error:

```rue
```rue error
#[forbid(unused_binding)]
fn strict() -> Int {
#[allow(unused_binding)] // Error: Cannot set lint `unused_binding` to `allow`
Expand All @@ -101,7 +101,7 @@ An `expect` for a group is fulfilled by any lint in it, and like `allow`, it can

To set a level for a whole file, use an inner attribute (with a `!`) at the start of the file, before any items. Inner attributes can also go at the start of a `mod { ... }` body to apply to the whole module, where they come after the attributes on the `mod` itself, so they take precedence unless those forbid the lint. Attributes on the items inside still override them:

```rue
```rue warn
#![allow(unused_function)]

fn reserved() -> Int {
Expand Down
10 changes: 5 additions & 5 deletions docs/modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Exporting a function from `main.rue` also makes it an [entrypoint](/docs/functio

You can reference exported symbols and types from other modules by using the module name followed by the path to the symbol or type:

```rue
```rue ignore
fn main() -> String {
utils::greet("Alice")
}
Expand All @@ -59,7 +59,7 @@ In this case, we are referencing the `greet` function from the `utils` module.

Instead of referencing by path every time, you can import symbols and types from other modules into the current scope so that they can be referenced directly:

```rue
```rue ignore
import utils::greet;

fn main() -> String {
Expand All @@ -69,7 +69,7 @@ fn main() -> String {

You can import multiple items at once:

```rue
```rue ignore
import utils::{exclaim, greet};

fn main() -> String {
Expand All @@ -79,7 +79,7 @@ fn main() -> String {

You can also import all of the exported items from a module by using the `*` wildcard:

```rue
```rue ignore
import utils::*;

fn main() -> String {
Expand All @@ -95,7 +95,7 @@ A name can refer to both a symbol (such as a function or constant) and a type (s

It's possible to re-export items, which makes them available to other modules as if they were declared in the current module:

```rue
```rue ignore
export conditions::*;
export utils::greet;
```
Expand Down
10 changes: 4 additions & 6 deletions docs/tutorials/password.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,9 @@ Open it in your editor of choice. You should see a `puzzles` directory with a `m

You can replace the contents of `main.rue` with the following:

```rue
{/* nofmt: rue fmt breaks this signature inside `List<Condition>` instead of between the parameters (https://github.com/xch-dev/rue/issues/322). */}

```rue nofmt
fn main(
correct_password: String,
password: String,
Expand Down Expand Up @@ -223,11 +225,7 @@ To solve this, we could curry the hash of the password instead of the password i
Here's the new Rue puzzle:

```rue
fn main(
password_hash: Bytes32,
password: String,
conditions: List<Condition>,
) -> List<Condition> {
fn main(password_hash: Bytes32, password: String, conditions: List<Condition>) -> List<Condition> {
assert sha256(password) == password_hash;

conditions
Expand Down
15 changes: 3 additions & 12 deletions docs/tutorials/signature.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,14 +32,8 @@ Open it in your editor of choice. You should see a `puzzles` directory with a `m
You can replace the contents of `main.rue` with the following:

```rue
fn main(
public_key: PublicKey,
conditions: List<Condition>,
) -> List<Condition> {
let agg_sig = AggSigMe {
public_key,
message: tree_hash(conditions),
};
fn main(public_key: PublicKey, conditions: List<Condition>) -> List<Condition> {
let agg_sig = AggSigMe { public_key, message: tree_hash(conditions) };

[agg_sig, ...conditions]
}
Expand Down Expand Up @@ -232,10 +226,7 @@ fn main(
delegated_puzzle: fn(...solution: Any) -> List<Condition>,
delegated_solution: Any,
) -> List<Condition> {
let agg_sig = AggSigMe {
public_key,
message: tree_hash(delegated_puzzle),
};
let agg_sig = AggSigMe { public_key, message: tree_hash(delegated_puzzle) };

let conditions = delegated_puzzle(...delegated_solution);

Expand Down
2 changes: 1 addition & 1 deletion docs/type-system/aliases.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ The type system is equipped to handle recursive types like this, and they are qu

However, a type must pass through a pair before it refers to itself. A type that refers to itself directly (or through a union, or another alias) without any nesting is an error, since it doesn't describe any actual value:

```rue
```rue error
// Error: Type `Value` refers to itself without passing through a pair
type Value = Value | Int;
```
2 changes: 1 addition & 1 deletion docs/type-system/generics.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ fn identity<T>(value: T) -> T {

When you call a generic function, the compiler infers the type parameters from the arguments you pass:

```rue
```rue ignore
fn main() -> Int {
identity(42)
}
Expand Down
6 changes: 3 additions & 3 deletions docs/type-system/structs.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,23 +17,23 @@ struct Point {

You can initialize a value with this type like so:

```rue
```rue ignore
fn main() -> Point {
Point { x: 42, y: 34 }
}
```

If you have a binding with the same name as a field, you can use the shorthand syntax:

```rue
```rue ignore
fn point(x: Int, y: Int) -> Point {
Point { x, y }
}
```

And access fields on the value:

```rue
```rue ignore
fn area(point: Point) -> Int {
point.x * point.y
}
Expand Down
2 changes: 1 addition & 1 deletion docs/type-system/unions.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ type Owner = Bytes32 | nil;

You can assign either of these types to `Owner`:

```rue
```rue ignore
fn main() -> Owner {
nil
}
Expand Down
Loading
Loading