refactor: major CLI simplification and comprehensive improvements #53
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit represents a comprehensive refactor of the CLI and SDK to use the official polkadot-sdk-parachain-template (v0.0.4) and simplify the user experience. Key Changes: Template Integration: - Integrate polkadot-sdk-parachain-template v0.0.4 as base template - Support dual pathway: full parachain vs pallet-only mode - XCM support now always included (no prompt) - Pallet-only mode only available via --pallet-only flag CLI Improvements: - Remove --with-xcm flag (XCM always included) - Remove XCM and pallet-only interactive prompts - Simplify pathway names (Custom Parachain, Smart Contract, etc.) - Update question: "What would you like to build?" - Improve developer experience with clearer messaging Testing: - Add comprehensive integration test for parachain pathway - Test full workflow: compile → chain-spec → node → PAPI tests - Add TestNode helper with automatic cleanup - Add tokio and serial_test dependencies - Update all pathway integration tests Documentation: - Rewrite first-recipe.md tutorial - Update CLI reference documentation - Update README.md with current pathway names - Remove outdated references to removed features Templates: - Add Cargo.pallet-only.toml.template for minimal workspace - Add README.pallet-only.md.template for pallet-only docs - Add zombienet-xcm.toml.template for multi-chain testing - Add setup-zombienet-binaries.sh for one-time binary setup - Update all template READMEs to latest format Breaking Changes: - Removed config.enable_xcm field - Removed --with-xcm CLI flag - XCM is now always included in full parachain recipes - Pallet-only mode requires explicit --pallet-only flag
Contributor
🤖 Semantic Version AnalysisResult: No version bump required Commit Analysis
Summary
This PR contains only non-versioned changes (docs, chore, etc). Manual override: If this is incorrect, you can manually add one of these labels:
Once a manual label is added, this workflow will respect it and not override. |
…ved Runtime variant
Contributor
🤖 Semantic Version AnalysisResult: PATCH version bump Commit Analysis
Summary
This PR will trigger a PATCH version bump when merged. Manual override: If this is incorrect, you can manually add one of these labels:
Once a manual label is added, this workflow will respect it and not override. |
Contributor
✅ Coverage ReportSDK Library Coverage: 83.77% (threshold: 80%) SDK library coverage detailsFull workspace coverage details✅ SDK library coverage meets the 80% threshold. Note: Only the SDK library is required to meet the 80% threshold. CLI coverage is tracked but not enforced due to interactive prompts. |
Add comprehensive unit tests for previously uncovered code paths: **Templates module (templates/mod.rs)** - Achieve 100% coverage (was 0%) - Add tests for list_available_templates function - Add tests for TemplateInfo Clone and Debug traits **Recipe configuration (config/recipe.rs)** - Improve coverage from 53.76% to 69.84% - Add tests for RecipeType and RecipePathway traits (Clone, Copy, Debug) - Add tests for RecipeConfig with pathway and description - Add test for YAML serialization **Error handling (error.rs)** - Improve coverage from 80% to 94.20% - Add tests for serde_yaml, serde_json, and regex error conversions - Add tests for CommandError and FileSystemError display formatting - Add test for Debug trait Overall SDK library coverage increased from ~75% to 76.80%, with 84 tests passing. Generated with https://claude.com/claude-code Co-Authored-By: Assistant <noreply@anthropic.com>
Add comprehensive tests for FrontmatterData and FrontmatterError: **FrontmatterData tests:** - Test Clone trait implementation - Test PartialEq trait for equality and inequality - Test Debug trait output formatting - Test Serialize/Deserialize round-trip **FrontmatterError tests:** - Test Display trait for all error variants - Test Debug trait output formatting Overall SDK library coverage improved from 76.80% to 77.43%, with 90 tests passing. metadata/frontmatter.rs coverage increased from 79.73% to 90.80%. Generated with https://claude.com/claude-code Co-Authored-By: Assistant <noreply@anthropic.com>
Add comprehensive integration tests for `RecipeConfig::from_recipe_directory`: **New tests:** - test_from_recipe_directory: Tests loading Polkadot SDK recipe - Creates temp directory with README frontmatter - Creates Cargo.toml and pallets/ directory - Verifies correct recipe type detection and pathway mapping - test_from_recipe_directory_solidity: Tests loading Solidity recipe - Creates temp directory with README frontmatter - Creates package.json with hardhat dependency - Verifies Solidity recipe type and Contracts pathway **Coverage improvements:** - config/recipe.rs: 69.84% → 86.56% (+16.72pp) - Overall SDK library: 77.43% → 80.05% (+2.62pp) - Total tests: 90 → 92 SDK library coverage now exceeds the 80% CI threshold! Generated with https://claude.com/claude-code Co-Authored-By: Assistant <noreply@anthropic.com>
Fixed incorrect path 'cli' -> 'dot/cli' in both release workflows. This was causing all release builds to fail with "cd: cli: No such file or directory". Fixes the v0.4.0 release workflow failure.
Pathway integration tests were failing because the parachain runtime requires WASM compilation target to be installed. This adds the wasm32-unknown-unknown target to the CI Rust toolchain setup.
The parachain integration test failed because WASM compilation requires the rust-src component to access standard library sources. Error: Cannot compile the WASM runtime: no standard library sources found Solution: Add rust-src to toolchain components alongside rustfmt and clippy
The parachain template was using hardcoded 'pallet_parachain_template'
instead of the template variable. This caused compilation errors when
generating recipes with different slugs.
Fixed by replacing hardcoded references with {{slug | replace("-", "_")}}
template variable in:
- runtime/src/lib.rs: TemplatePallet type definition
- runtime/src/configs/mod.rs: pallet Config implementation
This allows the pallet name to be correctly substituted based on the
recipe slug (e.g., 'parachain-example' -> 'pallet_parachain_example').
The runtime source files need the .template extension so the template
engine processes them and substitutes variables like {{slug}}.
Without .template extension, these files are copied as-is and the
template syntax appears literally in the generated code, causing
compilation errors.
Renamed:
- runtime/src/lib.rs.template
- runtime/src/configs/mod.rs.template
This allows proper substitution of pallet names based on recipe slug.
The scaffolding system uses simple string replacement, not full Tera
template processing. Added a new {{slug_underscore}} variable that
converts hyphens to underscores for use in Rust identifiers like
pallet names and module names.
Updated runtime templates to use {{slug_underscore}} instead of the
Tera filter syntax {{slug | replace("-", "_")}}.
The test was looking for `parachain-example_runtime.compact.compressed.wasm` but Cargo converts all hyphens to underscores in WASM output filenames, so the actual file is `parachain_example_runtime.compact.compressed.wasm`. Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
The template builds a custom node binary at target/release/{{slug}}-node,
not polkadot-omni-node. Updated scripts to use the correct binary path.
Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Reverted the previous change that tried to use the custom node binary. The template is designed to work with polkadot-omni-node, which is a generic node that can run any parachain runtime WASM. Added installation step in CI workflow to install polkadot-omni-node before running the integration tests. Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
The workflow was failing because RUSTFLAGS="-D warnings" was treating all warnings as errors during polkadot-omni-node installation. External crates from crates.io may have warnings with newer compiler versions. Override RUSTFLAGS to empty string for the installation step. Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
The litep2p dependency of polkadot-omni-node requires the protobuf compiler (protoc) to be available during compilation. Add installation step in CI before building polkadot-omni-node.
Changes: - Replace polkadot-omni-node with chain-spec-builder for chain spec generation - Fix WASM file path to use slug_underscore template variable - Add rust-src component and wasm32-unknown-unknown target to rust-toolchain - Add chain-spec-builder installation and caching to CI workflow
… flag The new version of polkadot-omni-node no longer supports the --runtime flag. Instead, it requires a chain specification file. Updated start-dev-node.sh to use --chain flag with the generated chain-spec.json file.
The integration test was failing because it wasn't generating the TypeScript types from the chain spec before running the tests. Added 'npm run generate:types' step between npm install and npm test.
Multiple fixes for PAPI type generation workflow: 1. PAPI Configuration: - Removed manual papi.json configuration file - Changed to use `papi add` command which properly fetches metadata - Updated package.json to use `papi` instead of `papi generate --config papi.json` - PAPI creates `.papi/polkadot-api.json` with both wsUrl and cached metadata 2. Pallet Name Fixes: - Fixed parachain-example to use correct pallet name `pallet_parachain_example` - Previously used `pallet_parachain_template` which caused compilation errors 3. Integration Test Updates: - Changed from `npm run generate:types` to `npx papi add dot -w ws://localhost:9944` - This properly fetches metadata from running node and generates TypeScript types - Cached metadata allows type generation to work even after node stops The correct PAPI workflow is: 1. Start node 2. Run `papi add` to fetch and cache metadata from running node 3. PAPI generates TypeScript descriptors and caches metadata to .papi/metadata/ 4. Subsequent `papi` commands use cached metadata This resolves the TypeError: Cannot read properties of undefined (reading 'lookup') error that was occurring because PAPI was trying to read metadata from a chain spec file instead of connecting to a running node. Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
…th filtering Reduces CI time from 15-20 minutes to ~2 minutes for most PRs: 1. Path-based triggers - Only run when relevant template files change - Skip tests for docs/readme changes - Skip tests when unrelated templates change - Always run for toolchain/workflow/SDK core changes 2. Runtime WASM caching - Avoid 15+ minute rebuilds - Cache compiled runtime artifacts (wbuild/) - Cache key based on runtime/pallet source files - Rebuilds only when runtime code actually changes 3. Better path specificity for each template type - polkadot-sdk-template (parachain/pallet) - basic-interaction-template (PAPI) - solidity-template (contracts) - xcm-template (XCM/Chopsticks) - testing-template (infra/config) Result: Most PRs skip this workflow entirely, and when it runs, cached builds complete 10x faster. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
brunopgalvao
added a commit
that referenced
this pull request
Nov 14, 2025
Updated all documentation to use the current simplified CLI commands after PR #53 removed the 'recipe' subcommand. Command Changes (Old → New): - `dot recipe create` → `dot create` - `dot recipe test` → `dot test` - `dot recipe submit` → `dot submit` Files Updated (10 files, ~80 replacements): - docs/getting-started/first-recipe.md - docs/developers/cli-reference.md (extensive updates) - docs/contributors/workflow.md - docs/contributors/troubleshooting.md - docs/contributors/README.md - docs/developers/README.md - docs/developers/architecture.md - dot/cli/README.md - install.sh (help text) - .github/workflows/test-sdk.yml (test commands) All documentation now correctly reflects the simplified CLI structure introduced in v0.5.0.
brunopgalvao
added a commit
that referenced
this pull request
Nov 14, 2025
* refactor: decouple CLI to work standalone without repository dependency
Major refactoring to make the dot CLI work as a standalone tool similar to
create-react-app, removing dependency on being run from the polkadot-cookbook
repository root.
Key Changes:
**1. Removed Repository Validation**
- Deleted `validate_working_directory()` function that required ./recipes/ and ./Cargo.toml
- Removed validation calls from interactive and non-interactive modes
- CLI now works from any directory
**2. Embedded Templates at Compile Time**
- Added `include_dir` dependency to embed all recipe templates
- Templates are now compiled into the binary using `include_dir!()` macro
- No longer reads templates from filesystem at runtime
- ~2.7MB of templates embedded for all recipe types
**3. Updated Output Directory**
- Changed default destination from "./recipes/" to "./" (current directory)
- Projects now created as `./{slug}/` instead of `./recipes/{slug}/`
- Updated all CLI output and tree displays to reflect new structure
**4. Fixed Rust Toolchain Version Handling**
- Replaced `read_rust_version()` that read from ./rust-toolchain.toml
- Now uses `get_rust_version()` with hardcoded default "1.91"
- Ensures CLI works without access to repository's rust-toolchain.toml
**5. Restructured CLI Commands**
- Flattened command structure from nested to top-level:
- `dot recipe create` → `dot create`
- `dot recipe test` → `dot test`
- `dot recipe submit` → `dot submit`
- Updated help text to reference "projects" from user perspective
- Maintained "recipe" terminology for submission to cookbook
**Testing**
- Successfully built CLI in release mode
- Tested from /tmp directory outside repository
- Verified project creation with correct file structure
- Confirmed template variable replacement working correctly
**Remaining Work**
- TODO: Enhance `dot submit` to automatically fork/clone cookbook repo
- TODO: Implement smart PR workflow for standalone usage
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
* feat: implement standalone submit workflow for dot CLI
Implemented complete fork/clone/submit workflow to allow users to submit
projects from anywhere without needing the polkadot-cookbook repository.
**How It Works**
When users run `dot submit` from a standalone project:
1. Detects standalone mode (no ./recipes/ or ./Cargo.toml)
2. Forks paritytech/polkadot-cookbook to user's GitHub account
3. Clones the fork to a temporary directory
4. Copies the project to recipes/{slug}/ in the cloned repo
5. Creates a branch (feat/recipe-{slug})
6. Commits and pushes changes to user's fork
7. Creates a PR to paritytech/polkadot-cookbook
8. Cleans up temporary directory
**Implementation Details**
- Added `tempfile` dependency for temporary directory management
- Split submit logic into two functions:
- `handle_standalone_submit()` - New workflow for standalone projects
- `handle_cookbook_repo_submit()` - Legacy workflow for cookbook repo
- Implemented `copy_dir_recursive()` with boxing for async recursion
- Uses GitHub API (octocrab) for forking and PR creation
- Skips hidden files and .git directory during copy
**User Experience**
```bash
# Create a project anywhere
cd ~/projects
dot create my-parachain
# Work on it...
cd my-parachain
# Submit directly from project directory
dot submit
```
The CLI automatically:
- Detects it's a standalone project
- Forks the cookbook repo
- Handles all git operations
- Creates PR with generated title and description
- Shows PR URL when complete
**Backward Compatibility**
The original workflow still works when running `dot submit` from within
the polkadot-cookbook repository.
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: auto-generate slug from title, remove slug prompt
Simplified the interactive workflow by automatically generating the slug
from the title instead of prompting the user for it.
**Changes**
- Removed slug input prompt from interactive mode
- Slug is now auto-generated using `title_to_slug()`
- Slug is still displayed in the configuration summary
- Users can see the generated slug before confirming
**User Experience**
Before:
```
What is your recipe title? My Custom Pallet
Recipe slug: my-custom-pallet ← User had to confirm/edit this
```
After:
```
What is your recipe title? My Custom Pallet
Configuration Summary:
Title: My Custom Pallet
Slug: my-custom-pallet ← Auto-generated, shown in summary
```
This makes the workflow simpler while still giving users visibility
into the generated slug.
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: make git branch creation default, remove prompt
Simplified the interactive workflow by making git branch creation the
default behavior instead of prompting the user.
**Changes**
- Removed "Create a git branch for this recipe?" prompt
- Git branch creation is now always enabled by default
- Users can skip git with the existing `--no-git` flag
**User Experience**
Before:
```
Brief description: ...
Create a git branch for this recipe? [Y/n] ← Removed this prompt
Install npm dependencies? [Y/n]
```
After:
```
Brief description: ...
Install npm dependencies? [Y/n]
Configuration Summary:
Git Branch: feat/my-recipe ← Auto-enabled (use --no-git to skip)
```
If users want to skip git operations:
```bash
dot create --no-git
```
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: make npm install default and show verbose output
Made npm package installation the default behavior and improved transparency
by showing real-time install output similar to create-react-app.
**Changes**
1. **Removed npm install prompt**
- npm install now runs by default
- Users can skip with `--skip-install` flag
- No more "Install npm dependencies?" prompt
2. **Verbose npm output**
- Changed from `.output()` to `.status()` with `Stdio::inherit()`
- npm install progress now shows in real-time
- Users can see package installation progress
- Similar UX to create-react-app
**Updated Modules**
- `bootstrap.rs`: Updated `run_command()` to inherit stdio
- `scaffold/mod.rs`: Updated npm install for Solidity and Parachain recipes
**User Experience**
Before (hidden output):
```
Install npm dependencies? [Y/n] y
✅ Recipe created successfully!
```
After (verbose output):
```
Configuration Summary:
...
Continue? [Y/n] y
npm install
added 245 packages in 12s
✅ Recipe created successfully!
```
Users see exactly what's being installed, like create-react-app:
```bash
dot create --skip-install # Skip npm install
dot create # Install by default (verbose)
```
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
* feat: organize recipes by pathway in folder structure
Implemented pathway-based organization for recipes in the cookbook repository
to improve discoverability and maintainability.
**Changes**
1. **Added pathway folder helper**
- Added `to_folder_name()` method to RecipePathway enum
- Converts pathway to folder names: "parachain", "contracts", etc.
2. **Updated standalone submit workflow**
- Prompts user to select which pathway the recipe belongs to
- Copies project to `recipes/{pathway}/{slug}/` instead of `recipes/{slug}/`
- Shows pathway in project info display
3. **Updated cookbook repo submit workflow**
- Updated `get_recipe_path()` to search in pathway subdirectories
- Searches all pathway folders: parachain, contracts, basic-interaction, xcm, testing
- Maintains backward compatibility with legacy location (recipes/{slug}/)
- Supports running from pathway subdirectory structure
**Folder Structure**
Before:
```
recipes/
├── my-parachain/
├── my-contract/
└── my-xcm-recipe/
```
After:
```
recipes/
├── parachain/
│ └── my-parachain/
├── contracts/
│ └── my-contract/
├── basic-interaction/
├── xcm/
│ └── my-xcm-recipe/
└── testing/
```
**User Experience**
When submitting a standalone project:
```
dot submit
→ Which pathway does this recipe belong to?
• Custom Parachain
• Smart Contract
• Basic Interaction
• Cross-chain Interaction
• Polkadot Network
Project Info:
Name: My NFT Pallet
Slug: my-nft-pallet
Type: Polkadot SDK
Pathway: parachain
✅ Project copied to recipes/parachain/my-nft-pallet
```
**Backward Compatibility**
- `dot test` and `dot submit` still work with legacy recipe locations
- Searches both pathway subdirectories and legacy location
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: implement smart contract-first CLI with improved UX
Major CLI improvements to better align with user priorities and improve
overall experience:
## Smart Contract-First Approach
- Reorder pathway selection to prioritize smart contracts over parachains
- Update pathway ordering in both `dot create` and `dot submit` commands
- Rename "Custom Pallet" to "Parachain (Polkadot SDK)" for clarity
## Pathway Naming Improvements
- Rename Testing pathway to Networks throughout codebase
- Update XCM pathway from "Cross-chain Interaction" to "Cross-chain Transactions"
- Rename folders: recipes/testing → recipes/networks
- Rename templates: testing-template → networks-template
- Update all enum variants: RecipeType::Testing → RecipeType::Networks
- Update serialization from "testing" to "networks"
## Test Requirement for Submissions
- Add pre-submission test requirement to ensure recipe quality
- Create run_recipe_tests() helper function
- Tests must pass before `dot submit` will proceed
- Works for both Rust (cargo test) and TypeScript (npm test) recipes
- Clear error messages with instructions if tests fail
## CLI Restructuring
- Move create-specific options from root CLI to `dot create` subcommand
- Clean up root `dot --help` to show only global commands
- Add example commands to root help for better discoverability
- Improve help text organization and clarity
## Template and Recipe Organization
- Reorganize recipes into pathway-specific folders
- Rename basic-interaction-template → transactions-template
- Update all references in SDK, CLI, and tests
- Update CI workflow paths for new folder structure
Files changed:
- dot/cli/src/main.rs - CLI restructuring and pathway reordering
- dot/sdk/src/config/recipe.rs - Enum renames and pathway mapping
- dot/sdk/src/scaffold/mod.rs - Template constant updates
- All tests updated for new pathway names
- CI workflows updated for new folder structure
* refactor: improve CLI UX and update documentation
## Description Prompt Simplification
- Remove SEO hint text from description prompt
- Change label from "Brief description" to "Description"
- Simplify user interaction
## Configuration Summary Improvements
- Update parachain pathway directory structure to match reality
- Add template source information:
- Based on: polkadot-sdk-parachain-template
- Polkadot SDK: v2503.0.1
- Release link to GitHub
- Change "Full tutorial" to "README" for accuracy
- Include all actual files (zombienet configs, Dockerfile, LICENSE, etc.)
- Add build.rs files in runtime and node directories
## Documentation Updates
- Update pathway names across all documentation
- Ensure consistency with CLI changes:
- "Custom Parachain" → "Parachain"
- "Basic Interaction" → "Chain Transactions"
- "Cross-chain Interaction" → "Cross-chain Transactions"
- "Polkadot Network" → "Polkadot Networks"
- "testing" → "networks"
- Update pathway ordering to reflect smart contract-first approach
Files updated:
- dot/cli/src/main.rs - Description prompt and Configuration Summary
- README.md - Pathway list
- docs/developers/cli-reference.md - Pathway options
- docs/getting-started/first-recipe.md - Interactive prompts
* refactor: add pathway-specific commands and remove RequestNew pathway
## Pathway-Specific Command Aliases
- Add `dot contract` command for creating smart contract projects
- Add `dot parachain` command for creating parachain projects
- These provide convenient shortcuts instead of `dot create --pathway <type>`
## Remove RequestNew Pathway
- Remove "None of these - Request new template" option
- Remove RecipePathway::RequestNew enum variant
- Remove all associated match arms and unreachable code
- Remove RequestNew test cases
- Simplifies CLI and removes unused functionality
## CLI Text Updates
- Change "Polkadot Cookbook" to "dot CLI" in intro
- Change "Let's create your new Polkadot recipe" to "Let's create your new Polkadot project"
- Consistent terminology throughout
## Help Output
Now shows pathway-specific commands:
```
Commands:
create Create a new project (interactive)
contract Create a new smart contract project
parachain Create a new parachain project
test Run project tests
submit Submit a project as a pull request
```
Files updated:
- dot/cli/src/main.rs - Add commands, remove RequestNew, update text
- dot/sdk/src/config/recipe.rs - Remove RequestNew enum variant
- dot/sdk/src/dependencies/mod.rs - Remove RequestNew dependencies
- dot/sdk/src/scaffold/mod.rs - Remove RequestNew match arm
* refactor: change 'Recipe Setup' to 'Polkadot Project Setup'
Update the note title in the CLI interactive flow to better reflect
that users are creating a Polkadot project rather than a recipe.
Updated:
- dot/cli/src/main.rs - Change note title from 'Recipe Setup' to 'Polkadot Project Setup'
* feat: skip pathway prompt for dot contract and dot parachain commands
When using pathway-specific commands (dot contract, dot parachain),
skip the 'What would you like to build?' prompt and go directly to
asking for the project title.
This provides a more streamlined experience:
- `dot create` - Shows pathway selection prompt (interactive)
- `dot contract` - Skips prompt, goes directly to title
- `dot parachain` - Skips prompt, goes directly to title
Implementation:
- Check if pathway parameter is provided in handle_create()
- If provided, parse it and skip the interactive selection
- If not provided, show the full pathway selection menu
Updated:
- dot/cli/src/main.rs - Add conditional pathway selection logic
* refactor: capitalize 'Chain' in 'Cross-Chain Transactions'
Update capitalization from 'Cross-chain Transactions' to 'Cross-Chain
Transactions' for consistency with other pathway names like 'Chain
Transactions' and 'Smart Contract'.
Note: Kept lowercase 'cross-chain' in descriptions (e.g., 'Cross-chain
asset transfers') as these are mid-sentence descriptive text.
Updated across:
- dot/cli/src/main.rs - Pathway selection and configuration summary
- README.md - Pathway list
- docs/developers/cli-reference.md - Pathway options
- docs/getting-started/first-recipe.md - Interactive prompt example
* refactor: comprehensive terminology change from 'recipe' to 'project'
This large refactoring updates the codebase to use 'project' terminology
instead of 'recipe' for user-created projects, while preserving 'recipe'
references in contexts related to cookbook contributions.
Key Changes:
===========
SDK (dot/sdk):
- Renamed config/recipe.rs → config/project_types.rs
- RecipeType → ProjectType
- RecipePathway → ProjectPathway
- RecipeConfig → ProjectMetadata
- detect_recipe_type() → detect_project_type()
- from_recipe_directory() → from_project_directory()
- Renamed template directory: recipe-templates/ → project-templates/
- Updated all comments and documentation
CLI (dot/cli):
- Updated all command descriptions and help text
- handle_recipe_test() → handle_project_test()
- handle_recipe_submit() → handle_project_submit()
- run_recipe_tests() → run_project_tests()
- get_recipe_path() → get_project_path()
- Updated user-facing messages throughout
- Kept 'recipe' in PR/commit contexts (cookbook submissions)
Tests:
- Updated all test function names
- Updated variable names (recipe_path → project_path, etc.)
- Kept references to recipes/ folder as-is (actual directory)
Configuration:
- Updated keywords in CLI Cargo.toml
Rationale:
=========
Users create a PROJECT using the CLI, then optionally submit that
project as a RECIPE to the polkadot-cookbook repository. This change
clarifies that distinction.
What stayed as 'recipe':
- Physical recipes/ folder path
- References to submitting to cookbook
- Git commit messages for cookbook PRs
- Documentation about recipe contributions
Breaking Changes:
================
- Type names changed (RecipeType → ProjectType, etc.)
- Function names changed (detect_recipe_type → detect_project_type)
- Serde serialization keys updated (clean break, no backward compatibility)
- Template directory path changed
All tests passing. Build successful.
* docs: update CONTRIBUTING.md, README.md and source comments
Updated key documentation files and source code comments to reflect
the recipe→project terminology refactoring:
Documentation Updates:
- CONTRIBUTING.md: Updated CLI commands (dot recipe X → dot X)
- README.md: Updated CLI commands and examples
- Modernized quickstart instructions
- Clarified project vs recipe distinction
Source Code Updates:
- Updated comments in Rust source files
- Changed "recipe type" → "project type" in debug messages
- Updated test comments and assertions
- Changed "Solidity/Parachain recipe" → "project"
Note: Kept "recipe" references in:
- CI workflow files (test actual cookbook recipes)
- Git commit messages for submissions
- PR body templates (submitting to cookbook)
- References to the recipes/ directory
* fix: initialize git repository instead of creating branch for projects
Changed project creation to initialize a fresh git repository in the
project directory instead of creating a git branch in the cookbook repo.
Breaking Changes:
- ProjectInfo.git_branch: Option<String> → git_initialized: bool
- GitOperations now calls init() instead of create_branch() during project creation
Changes:
- SDK: Updated scaffold to call GitOperations::init() for new projects
- CLI: Changed display from "Git Branch: feat/xyz" to "Git Init: Yes/No"
- CLI: Updated --no-git flag description to "Skip git repository initialization"
- Tests: Updated all references from git_branch to git_initialized
Rationale:
Users create standalone projects that should have their own git repos,
not branches in the cookbook repository. The create_branch() function
is still used by `dot submit` for creating PR branches.
All tests passing.
* docs: fix all outdated CLI command references
Updated all documentation to use the current simplified CLI commands
after PR #53 removed the 'recipe' subcommand.
Command Changes (Old → New):
- `dot recipe create` → `dot create`
- `dot recipe test` → `dot test`
- `dot recipe submit` → `dot submit`
Files Updated (10 files, ~80 replacements):
- docs/getting-started/first-recipe.md
- docs/developers/cli-reference.md (extensive updates)
- docs/contributors/workflow.md
- docs/contributors/troubleshooting.md
- docs/contributors/README.md
- docs/developers/README.md
- docs/developers/architecture.md
- dot/cli/README.md
- install.sh (help text)
- .github/workflows/test-sdk.yml (test commands)
All documentation now correctly reflects the simplified CLI structure
introduced in v0.5.0.
* feat(sdk): add lock file validation for project submissions
Add comprehensive lock file validation to ensure reproducible builds
for all project types. The CLI now validates that required lock files
are present before allowing submission.
Changes:
- Add validate_lock_files() function to SDK validation module
- Validates Cargo.lock for Rust projects
- Validates package-lock.json for TypeScript projects
- Detects full parachains (both locks required) vs pallet-only
- Integrate validation into both submit workflows (cookbook & standalone)
- Fix template .gitignore files to allow lock files to be committed
- Add comprehensive test coverage (11 new tests)
- Update documentation to reflect lock file requirements
Fixes:
- Solidity and XCM template .gitignore incorrectly ignored package-lock.json
- Existing test had undefined 'branch' variable reference
Documentation updates:
- CONTRIBUTING.md: Add lock file requirement to code quality checklist
- docs/contributors/workflow.md: Update submit workflow description
- docs/getting-started/first-recipe.md: Add lock files to PR checklist
* refactor: reorganize recipes folder structure
Move parachain-example into dedicated parachains directory and rename
xcm folder to better reflect its purpose.
Changes:
- Create recipes/parachains/ directory for parachain projects
- Move parachain-example from recipes/ to recipes/parachains/
- Rename recipes/xcm/ to recipes/cross-chain-transactions/ for clarity
This improves organization by grouping similar project types together
and using more descriptive naming.
* feat(sdk): add chopsticks config and enhance project structure descriptions
Add Chopsticks configuration template for parachain projects and improve
the Configuration Summary display with detailed file/folder descriptions.
Changes:
- Add chopsticks.yml.template for parachain generation
- Pre-configured with Paseo relay chain and Asset Hub
- Includes usage instructions and customization notes
- Skipped in pallet-only mode (like XCM zombienet config)
- Enhance Configuration Summary with descriptions for all pathways
- Full Parachain: Descriptions for runtime, node, pallets, scripts, etc.
- Pallet-only: Clear explanations of pallet structure
- Contracts: Hardhat and Solidity project structure
- Transactions: PAPI transaction building setup
- XCM: Cross-chain testing with Chopsticks
- Networks: Infrastructure testing configurations
Benefits:
- Developers can immediately test parachains with Paseo Asset Hub
- New users understand the purpose of each file and folder
- Better onboarding experience with clear project structure explanations
* docs: replace remaining 'recipe' with 'project' in user-facing text
Update all remaining user-facing references from "recipe" to "project"
to maintain consistency with the refactoring. This affects documentation,
CLI help text, and command descriptions.
Note: References to "recipe" are intentionally kept when referring to:
- Submissions to the cookbook (which are called "recipes")
- The recipes/ folder structure
- Recipe configuration/metadata for cookbook entries
Changes:
- docs/developers/architecture.md: Update command descriptions and examples
- docs/developers/cli-reference.md: Update create command documentation
- docs/getting-started/first-recipe.md: Update tutorial step descriptions
- docs/contributors/troubleshooting.md: Update section headers and examples
- dot/cli/src/main.rs: Update CLI help examples
Examples of changes:
- "Create a new recipe" → "Create a new project"
- "Test a recipe" → "Test a project"
- "Recipe title" → "Project title"
- "Recipe creation" → "Project creation"
- "Submit recipe as pull request" → "Submit project as a recipe to the cookbook"
* docs: fix SDK guide terminology and rename first-recipe.md
Update SDK guide to use correct API terminology and rename tutorial file
to better reflect the project vs recipe distinction.
Changes:
- docs/developers/sdk-guide.md:
- Replace RecipeConfig → ProjectConfig (actual SDK API)
- Replace RecipeScaffold → Scaffold (actual SDK API)
- Update section headers and descriptions
- Fix code examples to match actual API
- Note: Full API documentation rewrite needed in future
- Rename first-recipe.md → first-project.md:
- Better reflects that users create "projects" locally
- Projects become "recipes" when submitted to cookbook
- Update title and description
- Update all links to renamed file:
- docs/contributors/workflow.md
- docs/getting-started/README.md
- docs/getting-started/installation.md
This resolves remaining terminology inconsistencies found in search results.
* docs: comprehensive fix of user-facing recipe to project terminology
Update all user-facing documentation to use "project" terminology when
referring to what developers create locally with `dot create`. The term
"recipe" is now consistently reserved for:
- Submitted content in the cookbook repository
- The `recipes/` folder and its contents
- `recipe.config.yml` configuration files
- Backend/internal references
This distinction clarifies that users create "projects" locally, which
become "recipes" when submitted to the cookbook.
Files updated:
- docs/README.md: First project tutorial references
- docs/contributors/README.md: Create a project command
- docs/contributors/commit-conventions.md: Example commit messages
- docs/contributors/troubleshooting.md: PR creation examples
- docs/contributors/workflow.md: All workflow steps and examples
- docs/developers/README.md: Create command description
- docs/developers/cli-reference.md: Command examples
- docs/developers/sdk-guide.md: Code example titles
- docs/getting-started/README.md: Tutorial descriptions
- docs/getting-started/first-project.md: Step descriptions and examples
- docs/getting-started/installation.md: Tutorial references
- docs/reference/recipe-config-schema.md: Example titles
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: remove tutorial/guide distinction, recipe config, and difficulty
This commit removes several deprecated concepts from the codebase:
1. **Removed tutorial vs guide distinction:**
- Deleted all README.guide.md.template files
- Renamed README.tutorial.md.template → README.md.template (or README.full.md.template for polkadot-sdk)
- Updated scaffold code to use the simplified template names
- Removed content_type field from all templates and code
2. **Removed recipe-config-schema.md:**
- Deleted docs/reference/recipe-config-schema.md
- Removed all references to this file from docs
- We no longer have a separate recipe config file schema
3. **Removed difficulty concept:**
- Removed difficulty field from readme template generator
- Removed difficulty references from template frontmatter
- Cleaned up related documentation
4. **Template cleanup:**
- Simplified template generation code
- Updated tests to match new simplified format
- Removed obsolete template files
Files changed:
- docs/developers/cli-reference.md
- docs/reference/README.md
- docs/reference/manifest-schema.md
- docs/reference/recipe-config-schema.md (deleted)
- dot/sdk/src/scaffold/mod.rs
- dot/sdk/src/templates/readme.rs
- 10 template files deleted (guide versions)
- 3 template files renamed
All tests pass after these changes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* test: fix pathway integration and parallel test issues
- Fix project_path() to include pathway folder structure (recipes/{pathway}/{slug})
- Update pathway search list: replace "testing" with "networks"
- Fix all CLI tests to expect pathway-based folder structure
- Fix smoke test to run from repo root instead of nested directory
- Add serial_test dependency to prevent test interference
- Mark git and scaffold tests with #[serial] to run sequentially
- Update README template test to check for heading instead of frontmatter
All 161 tests now passing (91 SDK + 13 CLI + 7 pathway + 36 integration + 6 template + 15 doc tests)
Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* ci: fix CLI test to expect pathway folder structure
* ci: optimize pathway integration test caching and timeouts
- Increase timeout from 60 to 90 minutes for cold cache scenarios
- Add sccache for faster Rust compilation caching
- Use version-based cache keys for polkadot tools instead of Cargo.lock hash
- Update template paths from recipe-templates to project-templates
- Add sccache statistics reporting
These optimizations should reduce pathway test time from 60+ minutes to ~15-20 minutes with warm cache.
* ci: make sccache optional to handle GitHub cache service outages
- Add continue-on-error to sccache setup
- Only configure sccache if setup succeeds
- Remove sccache from cargo install steps (already cached by version)
This prevents build failures when GitHub's Actions Cache service has temporary issues.
* ci: remove sccache due to GitHub Actions Cache service outage
GitHub's Actions Cache service is experiencing ongoing outages causing pathway tests to fail immediately. Removing sccache for now and relying on:
1. Version-based polkadot tools caching (30-40 min savings)
2. 90-minute timeout for cold cache scenarios
3. Runtime WASM caching
4. Standard Rust/Cargo caching
Can re-add sccache later when GitHub's service is stable.
---------
Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR implements a major refactor of the CLI with significant simplifications and improvements to the user experience, test coverage, and documentation.
Key Changes
1. Configuration Simplification
--pallet-only) for advanced users2. UI/UX Improvements
3. Comprehensive Integration Tests
tokioandserial_testdependencies for async testingTestNodestruct with automatic cleanup viaDroptraitwait_for_node_ready()helper for node readiness polling4. Documentation Updates
docs/getting-started/first-recipe.mdTesting
Breaking Changes
--with-xcmflag (XCM always enabled in full parachain mode)config.enable_xcmfieldRelated Issues
Part of the CLI refactor initiative to simplify user experience and improve developer workflow.