From daaa2eb6423a75448e939c792bc42816a1f1df45 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Thu, 5 Feb 2026 16:01:48 +0100 Subject: [PATCH] docs: fix recipe examples and add verification guidelines --- .claude/CLAUDE.md | 37 +++++++++++++++++++++ examples/icp-motoko-recipe/README.md | 21 ++++++------ examples/icp-rust-recipe/README.md | 18 +++++----- examples/icp-static-assets-recipe/README.md | 25 ++++++-------- 4 files changed, 69 insertions(+), 32 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 69d8c23eb..668956972 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -247,3 +247,40 @@ The `examples/` directory contains working project templates demonstrating: - `icp-pre-built/`: Using prebuilt WASM files These serve as integration tests and documentation for users and must be kept up to date. + +## Recipe Documentation Verification + +**IMPORTANT**: This project uses recipes from `icp-cli-recipes` repository. When working with recipe-related documentation or examples: + +### Always Verify Against icp-cli-recipes + +1. **Check the actual recipe template**: Recipe templates are in `github.com/dfinity/icp-cli-recipes/recipes//recipe.hbs` +2. **Verify parameters match**: Documentation must match what the recipe template actually supports +3. **Check required vs optional**: Parameters used directly in templates (not in `{{#if}}`) are required + +### Documentation Consistency Checklist + +When modifying recipe-related docs or examples, verify: + +1. **YAML syntax**: Use `canisters: - name:` array syntax, not singular `canister:` +2. **Recipe type format**: Use `@dfinity/` (e.g., `@dfinity/rust`), not just `rust` +3. **Parameter accuracy**: Only document parameters that exist in the recipe template +4. **Config option descriptions**: Each parameter description must accurately describe what it does, verified against the actual behavior in the `recipe.hbs` template +5. **Example accuracy**: Examples in `examples/` directories must use correct recipe syntax +6. **README consistency**: Example READMEs must match their `icp.yaml` files + +### Key Files to Keep in Sync + +- `docs/guides/using-recipes.md` - Main recipe usage guide +- `docs/migration/from-dfx.md` - Migration examples using recipes +- `docs/guides/creating-templates.md` - Template examples using recipes +- `examples/icp-*-recipe/` - Example projects using recipes + +### Cross-Repository Verification + +Before finalizing recipe-related changes, ask the user: +- Whether they have a local clone of `icp-cli-recipes` with changes to verify against +- Or whether to fetch the latest recipe templates from the remote repository +- What branch or version to compare with + +Then verify documentation matches the recipe templates from the specified source. diff --git a/examples/icp-motoko-recipe/README.md b/examples/icp-motoko-recipe/README.md index ad763c87e..0aa1d4f8e 100644 --- a/examples/icp-motoko-recipe/README.md +++ b/examples/icp-motoko-recipe/README.md @@ -8,22 +8,23 @@ The `motoko` recipe type provides a streamlined way to build Motoko canisters us ## Configuration -The [`icp.yaml`](./icp.yaml) file configures a canister using the built-in `motoko` recipe: +The [`icp.yaml`](./icp.yaml) file configures a canister using the `@dfinity/motoko` recipe: ```yaml -canister: - name: my-canister - recipe: - type: motoko - configuration: - # main motoko entry point (defaults to main.mo) - entry: src/main.mo +canisters: + - name: my-canister + recipe: + type: "@dfinity/motoko" + configuration: + main: src/main.mo + args: --incremental-gc ``` ### Key Components -- **`type: motoko`**: Uses the built-in Motoko recipe type -- **`entry`**: Specifies the main Motoko source file (defaults to `main.mo` if not provided) +- **`type: "@dfinity/motoko"`**: Uses the official DFINITY Motoko recipe +- **`main`**: Specifies the main Motoko source file (required) +- **`args`**: Compiler flags passed to `moc` (optional) ## Source Code diff --git a/examples/icp-rust-recipe/README.md b/examples/icp-rust-recipe/README.md index 440109c7e..19251ff92 100644 --- a/examples/icp-rust-recipe/README.md +++ b/examples/icp-rust-recipe/README.md @@ -8,21 +8,23 @@ The `rust` recipe type provides a streamlined way to build Rust canisters using ## Configuration -The [`icp.yaml`](./icp.yaml) file configures a canister using the built-in `rust` recipe: +The [`icp.yaml`](./icp.yaml) file configures a canister using the `@dfinity/rust` recipe: ```yaml -canister: - name: my-canister - recipe: - type: rust - configuration: - package: icp-rust-recipe +canisters: + - name: my-canister + recipe: + type: "@dfinity/rust" + configuration: + package: icp-canister + shrink: true ``` ### Key Components -- **`type: rust`**: Uses the built-in Rust recipe type +- **`type: "@dfinity/rust"`**: Uses the official DFINITY Rust recipe - **`package`**: Specifies the Cargo package name to build (required) +- **`shrink`**: Enables WASM optimization (optional) ## Project Structure diff --git a/examples/icp-static-assets-recipe/README.md b/examples/icp-static-assets-recipe/README.md index ad4c90b25..6820eed63 100644 --- a/examples/icp-static-assets-recipe/README.md +++ b/examples/icp-static-assets-recipe/README.md @@ -8,26 +8,23 @@ The `assets` recipe type provides a streamlined way to deploy static websites an ## Configuration -The [`icp.yaml`](./icp.yaml) file configures a canister using the built-in `assets` recipe: +The [`icp.yaml`](./icp.yaml) file configures a canister using the `@dfinity/asset-canister` recipe: ```yaml -canister: - name: my-canister - recipe: - type: assets - configuration: - # assets canister version (default is 0.27.0) - version: 0.27.0 - - # assets directory (default is www) - dir: www +canisters: + - name: my-canister + recipe: + type: "@dfinity/asset-canister" + configuration: + version: 0.29.2 + dir: www ``` ### Key Components -- **`type: assets`**: Uses the built-in assets recipe type -- **`version`**: Specifies the assets canister version to use (defaults to 0.27.0) -- **`dir`**: Directory containing static assets to deploy (defaults to `www`) +- **`type: "@dfinity/asset-canister"`**: Uses the official DFINITY asset canister recipe +- **`version`**: Specifies the assets canister version to use (optional, defaults to latest) +- **`dir`**: Directory containing static assets to deploy (required) ## Assets Directory