From 19d7d2ff39477de53810c1642f577961ba48be8f Mon Sep 17 00:00:00 2001 From: James Villarrubia Date: Sat, 20 Jun 2026 13:58:24 -0400 Subject: [PATCH 1/2] docs: restructure user nav into groups; move developer docs to the repo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs site is the product manual for people USING Pipecraft. Flatten-list of 18 items -> 5 intent-based groups (Get started / Guides / Reference / Understand / Help), and remove developer/internal material from the user nav. User nav: - Get started: Introduction, Quickstart (recast cli-reference β€” 0 inbound links) - Guides: Workflow generation, Workflow patterns, Versioning, Examples - Reference: CLI reference (was Commands), Configuration, Action modes - Understand: Architecture (kept β€” it's user-facing) - Help: Troubleshooting, Error reference (de-prefixed), FAQ, Roadmap, Security Developer/internal -> repo (linked from README): - testing-guide.md -> docs-dev/testing.md - ast-operations.md -> docs-dev/ast-operations.md (internals) - contributing.md removed (CONTRIBUTING.md already exists at root) - removed orphan docs-index.md / readme.md (README is canonical) - API Reference (generated typedoc) dropped from the nav; pages kept so the ~11 inbound cross-links still resolve (fully relocating generated output is a follow-up) Sidebar uses custom labels so heavily-linked file ids (commands x16, api x11) are unchanged β€” no broken links. docs build passes; the 2 real broken links from the moves (faq->contributing, error-reference->testing) repointed. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 12 +- {docs/docs => docs-dev}/ast-operations.md | 0 .../testing-guide.md => docs-dev/testing.md | 0 docs/docs/cli-reference.md | 2 +- docs/docs/commands.md | 2 +- docs/docs/contributing.md | 81 -- docs/docs/docs-index.md | 280 ---- docs/docs/error-handling.md | 4 +- docs/docs/faq.md | 2 +- docs/docs/readme.md | 1179 ----------------- docs/sidebars.ts | 76 +- docs/src/pages/index.tsx | 2 +- 12 files changed, 60 insertions(+), 1580 deletions(-) rename {docs/docs => docs-dev}/ast-operations.md (100%) rename docs/docs/testing-guide.md => docs-dev/testing.md (100%) delete mode 100644 docs/docs/contributing.md delete mode 100644 docs/docs/docs-index.md delete mode 100644 docs/docs/readme.md diff --git a/README.md b/README.md index 9c6c21d7..4a1d7c3c 100644 --- a/README.md +++ b/README.md @@ -21,11 +21,17 @@ Skip the debugging cycles. Generate battle-tested CI/CD workflows into your repo --- -## πŸ“š Complete Documentation +## πŸ“š Documentation -**[Read the full documentation at pipecraft.thecraftlab.dev β†’](https://pipecraft.thecraftlab.dev)** +**For users β€” [pipecraft.thecraftlab.dev β†’](https://pipecraft.thecraftlab.dev)** -The documentation site includes comprehensive guides, real-world examples, configuration references, and troubleshooting help. +The documentation site is the product manual: get-started + quickstart, guides (workflow generation, patterns, versioning, examples), reference (CLI, configuration, action modes), how-it-works, and help (troubleshooting, error reference, FAQ). + +**For contributors β€” develop Pipecraft itself:** + +- [CONTRIBUTING.md](./CONTRIBUTING.md) β€” setup, workflow, and how to contribute +- [docs-dev/testing.md](./docs-dev/testing.md) β€” testing philosophy and how to run/write tests +- [docs-dev/ast-operations.md](./docs-dev/ast-operations.md) β€” how the generator manipulates YAML (AST path operations) --- diff --git a/docs/docs/ast-operations.md b/docs-dev/ast-operations.md similarity index 100% rename from docs/docs/ast-operations.md rename to docs-dev/ast-operations.md diff --git a/docs/docs/testing-guide.md b/docs-dev/testing.md similarity index 100% rename from docs/docs/testing-guide.md rename to docs-dev/testing.md diff --git a/docs/docs/cli-reference.md b/docs/docs/cli-reference.md index e010491b..fbfa7f20 100644 --- a/docs/docs/cli-reference.md +++ b/docs/docs/cli-reference.md @@ -1,4 +1,4 @@ -# CLI Reference +# Quickstart PipeCraft is a command-line tool that generates CI/CD workflows for your project. This guide covers the essential commands you'll use day-to-day. diff --git a/docs/docs/commands.md b/docs/docs/commands.md index 3ac46b6f..dc76bfdd 100644 --- a/docs/docs/commands.md +++ b/docs/docs/commands.md @@ -2,7 +2,7 @@ sidebar_position: 2 --- -# Commands +# CLI Reference PipeCraft provides a focused set of commands designed to get you from zero to a working CI/CD pipeline with minimal friction. Each command serves a specific purpose in your workflow, from initial setup through ongoing maintenance and troubleshooting. diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md deleted file mode 100644 index db5845fc..00000000 --- a/docs/docs/contributing.md +++ /dev/null @@ -1,81 +0,0 @@ -# Contributing - -PipeCraft is an open source project that welcomes contributions. Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated. - -## Getting set up - -Start by cloning the repository and installing dependencies: - -```bash -git clone https://github.com/the-craftlab/pipecraft.git -cd pipecraft -pnpm install -pnpm run build -pnpm test -``` - -The project uses pnpm for package management, TypeScript for the source code, and Vitest for testing. After running these commands, you should see all tests passing. If something fails, check that you're using Node.js 18 or higher. - -## Making your first contribution - -When you're ready to make changes, create a new branch from `develop`: - -```bash -git checkout develop -git pull origin develop -git checkout -b feat/your-feature-name -``` - -Branch names should follow the conventional commit format: `feat/` for new features, `fix/` for bug fixes, `docs/` for documentation changes. - -Make your changes in the codebase. PipeCraft uses TypeScript with strict mode enabled, so you'll need to maintain proper typing throughout. Every public function should have JSDoc comments explaining what it does, its parameters, and its return value. - -Write tests for your changes. The test suite is organized into unit tests (test individual functions), integration tests (test components working together), and end-to-end tests (test complete workflows). New features should include all three types of tests when appropriate. - -## Committing changes - -PipeCraft uses conventional commits for all commit messages. This format enables automatic version calculation and changelog generation. Your commits should look like: - -```bash -git commit -m "feat: add GitLab CI support" -git commit -m "fix: correct version calculation for pre-release tags" -git commit -m "docs: update CLI reference" -``` - -The commit type (`feat`, `fix`, `docs`, etc.) determines how the version number is bumped. Features increment the minor version, fixes increment the patch version, and breaking changes (marked with `!`) increment the major version. - -## Opening a pull request - -Push your branch to your fork and open a pull request against the `develop` branch (not `main`). The PR title should also follow conventional commit format since it's used in the merge commit. - -In your PR description, explain what you changed and why. If you're fixing a bug, describe how to reproduce it. If you're adding a feature, explain the use case. Include screenshots for UI changes. - -Your PR will be reviewed by maintainers. They may ask questions or request changes. This is normal and helps maintain code quality. Don't be discouraged - every contributor goes through this process. - -## Code style - -PipeCraft enforces strict TypeScript typing. Never use `any` types - always provide specific types: - -```typescript -// βœ… Good - proper typing -function generate(config: PipecraftConfig): string { - return generateWorkflow(config) -} - -// ❌ Bad - using any -function generate(config: any): any { - return generateWorkflow(config) -} -``` - -When you need to type something complex, define an interface in `src/types/index.ts` rather than using inline types. This keeps type definitions centralized and reusable. - -## Getting help - -If you're stuck or have questions: - -**GitHub Discussions** is the best place for open-ended questions about contributing, architecture decisions, or feature ideas. - -**GitHub Issues** is for specific bugs or feature requests. Check if someone else has already reported your issue before opening a new one. - -The maintainers are happy to help new contributors get started. Don't hesitate to ask questions. diff --git a/docs/docs/docs-index.md b/docs/docs/docs-index.md deleted file mode 100644 index c49d331e..00000000 --- a/docs/docs/docs-index.md +++ /dev/null @@ -1,280 +0,0 @@ -# PipeCraft Documentation Index - -Welcome to PipeCraft documentation! This index helps you find the right documentation for your needs. - -## πŸ“š Documentation Overview - -PipeCraft documentation is organized into user-facing guides, contributor resources, and planning documents. - ---- - -## πŸš€ Getting Started - -### For New Users - -1. **[Main README](https://github.com/the-craftlab/pipecraft#readme)** - Start here! Installation, quick start, and basic usage -2. **[Current Trunk Flow](/docs/flows/trunk-flow)** - Understand how the trunk-based workflow works -3. **[Examples](https://github.com/the-craftlab/pipecraft/tree/main/examples)** - Example configurations for different use cases - - `basic-config.json` - Simple single-repo configuration - - `monorepo-config.json` - Multi-domain monorepo configuration - - `usage.md` - Detailed usage examples - -### Quick Links - -- πŸ“¦ [Installation](https://github.com/the-craftlab/pipecraft#installation) -- ⚑ [Quick Start](https://github.com/the-craftlab/pipecraft#quick-start) -- βš™οΈ [Configuration Options](https://github.com/the-craftlab/pipecraft#configuration-options) -- πŸ› [Troubleshooting](error-handling.md) - ---- - -## πŸ“– User Documentation - -### Core Concepts - -- **[Current Trunk Flow](/docs/flows/trunk-flow)** - The ONE currently implemented workflow pattern - - - How promotions work (develop β†’ staging β†’ main) - - Auto-promote configuration - - Domain-based testing - - Semantic versioning integration - -- **[Architecture](architecture.md)** - System design and how PipeCraft works - - Component overview - - Data flow diagrams - - Design decisions explained - - Extension points - -### Guides & References - -- **[Error Handling](error-handling.md)** - Complete error types, causes, and solutions - - - Configuration errors - - Pre-flight check failures - - Git operation errors - - GitHub API errors - - File system errors - - Recovery strategies - -- **[AST Operations](https://github.com/the-craftlab/pipecraft/blob/main/docs/AST_OPERATIONS.md)** - YAML manipulation internals - - How comment preservation works - - Path-based operations - - Advanced YAML AST manipulation - ---- - -## πŸ› οΈ Contributor Documentation - -### Getting Started with Contributing - -- **[Repository Cleanup Plan](https://github.com/the-craftlab/pipecraft/blob/main/docs/REPO_CLEANUP_PLAN.md)** - Understanding the repo structure - - Directory organization - - Where to add new code/tests/docs - - File categorization - -### Development Guides - -- **[Architecture](architecture.md)** - Required reading for contributors - - - System components in detail - - How everything fits together - - Performance considerations - - Security considerations - -- **[Test Documentation](https://github.com/the-craftlab/pipecraft/blob/main/tests/README.md)** - How to run and write tests - - - Test structure and categories - - Running tests locally - - Writing good tests - - Debugging test failures - -- **[AST Operations](https://github.com/the-craftlab/pipecraft/blob/main/docs/AST_OPERATIONS.md)** - Deep dive into YAML manipulation - - Required for working on template generation - - Comment preservation implementation - - Path operation implementation - -### Contributing Workflow - -1. Read [Architecture](architecture.md) to understand the system -2. Read [Test Documentation](https://github.com/the-craftlab/pipecraft/blob/main/tests/README.md) to understand testing -3. Pick an issue or feature to work on -4. Write tests first (TDD approach) -5. Implement the feature/fix -6. Ensure all tests pass -7. Submit pull request - ---- - -## πŸ—ΊοΈ Planning & Roadmap - -### Future Plans - -- **[Roadmap](https://github.com/the-craftlab/pipecraft/blob/main/TRUNK_FLOW_PLAN.md)** - Future features and enhancements - - ⚠️ **Note**: This describes FUTURE plans, not current implementation - - Temporary branches (planned) - - Multiple flow patterns (planned) - - GitLab support (planned) - - Environment deployments (planned) - -### Historical/Planning Documents - -- **[User Journey Errors Planning](https://github.com/the-craftlab/pipecraft/blob/main/docs/USER_JOURNEY_ERRORS_PLANNING.md)** - Comprehensive error scenario planning - - This is a planning/design document - - Maps every possible error scenario - - Reference for error handling implementation - ---- - -## πŸ“‹ Document Categories - -### Production Documentation (User-Facing) - -| Document | Purpose | Audience | -| ------------------------------------------------------------------------ | -------------------------------- | ------------------- | -| [Main README](https://github.com/the-craftlab/pipecraft#readme) | Installation, quick start, usage | All users | -| [Current Trunk Flow](/docs/flows/trunk-flow) | Current implementation details | Users, contributors | -| [Error Handling](error-handling.md) | Troubleshooting guide | Users | -| [Examples](https://github.com/the-craftlab/pipecraft/tree/main/examples) | Configuration examples | Users | - -### Technical Documentation (Contributor-Facing) - -| Document | Purpose | Audience | -| -------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------- | -| [Architecture](architecture.md) | System design | Contributors | -| [AST Operations](https://github.com/the-craftlab/pipecraft/blob/main/docs/AST_OPERATIONS.md) | YAML manipulation internals | Advanced contributors | -| [Test Documentation](https://github.com/the-craftlab/pipecraft/blob/main/tests/README.md) | Testing guide | Contributors | -| [Repository Cleanup Plan](https://github.com/the-craftlab/pipecraft/blob/main/docs/REPO_CLEANUP_PLAN.md) | Repo organization | Contributors | - -### Planning Documentation (Reference) - -| Document | Purpose | Audience | -| ------------------------------------------------------------------------------------------------------------------------ | ----------------------- | -------------------- | -| [Roadmap](https://github.com/the-craftlab/pipecraft/blob/main/TRUNK_FLOW_PLAN.md) | Future features | Product planning | -| [User Journey Errors Planning](https://github.com/the-craftlab/pipecraft/blob/main/docs/USER_JOURNEY_ERRORS_PLANNING.md) | Error scenario planning | Development planning | - ---- - -## πŸ” Finding What You Need - -### I want to... - -**Use PipeCraft** -β†’ Start with [Main README](https://github.com/the-craftlab/pipecraft#readme) -β†’ Then read [Current Trunk Flow](/docs/flows/trunk-flow) -β†’ Check [Examples](https://github.com/the-craftlab/pipecraft/tree/main/examples) for your use case - -**Troubleshoot an error** -β†’ Read [Error Handling](error-handling.md) -β†’ Search for your error message -β†’ Follow the recovery steps - -**Understand how PipeCraft works** -β†’ Read [Architecture](architecture.md) -β†’ Read [Current Trunk Flow](/docs/flows/trunk-flow) -β†’ Study [AST Operations](https://github.com/the-craftlab/pipecraft/blob/main/docs/AST_OPERATIONS.md) for template internals - -**Contribute code** -β†’ Read [Architecture](architecture.md) first -β†’ Read [Test Documentation](https://github.com/the-craftlab/pipecraft/blob/main/tests/README.md) -β†’ Check [Repository Cleanup Plan](https://github.com/the-craftlab/pipecraft/blob/main/docs/REPO_CLEANUP_PLAN.md) for structure -β†’ Write tests, then code -β†’ Submit PR - -**Add a new feature** -β†’ Check [Roadmap](https://github.com/the-craftlab/pipecraft/blob/main/TRUNK_FLOW_PLAN.md) for planned features -β†’ Read [Architecture](architecture.md) for extension points -β†’ Discuss in GitHub issues first -β†’ Follow contributor workflow above - -**Write tests** -β†’ Read [Test Documentation](https://github.com/the-craftlab/pipecraft/blob/main/tests/README.md) -β†’ Look at existing tests for examples -β†’ Follow test best practices documented there - ---- - -## πŸ“Š Documentation Status - -### βœ… Complete & Up-to-Date - -- Main README -- Architecture -- Current Trunk Flow -- Error Handling -- AST Operations (moved from src/utils/) -- Test Documentation -- Repository Cleanup Plan - -### 🚧 Needs Creation/Update - -- CHANGELOG.md (create) -- CONTRIBUTING.md (create) -- tests/CONTRIBUTING_TESTS.md (create) -- Main README (update to remove unimplemented features) - -### πŸ“‹ Planning Documents - -- Roadmap (marked as future) -- User Journey Errors Planning (reference) - ---- - -## 🀝 Contributing to Documentation - -Documentation is code! When contributing: - -1. **Keep It Current**: Update docs when you change code -2. **Be Specific**: Use examples, code snippets, exact commands -3. **Test Your Docs**: Ensure commands work, examples run -4. **Link Liberally**: Cross-reference related docs -5. **Update This Index**: When adding new docs, add them here - -### Documentation Guidelines - -- Use clear, simple language -- Include code examples -- Add diagrams where helpful -- Show both the command AND expected output -- Explain "why" not just "what" -- Keep file sizes reasonable (< 500 lines per doc) - -### Where to Put New Documentation - -- **User guides**: `/docs/` directory -- **API docs**: JSDoc comments in code -- **Test docs**: `/tests/` directory -- **Planning docs**: `/docs/` with clear "PLANNING" or "ROADMAP" marker -- **Examples**: `/examples/` directory - ---- - -## πŸ“ž Getting Help - -If you can't find what you need: - -1. **Search this index** for keywords -2. **Check [Main README](https://github.com/the-craftlab/pipecraft#readme)** for quick answers -3. **Search GitHub issues** for similar questions -4. **Ask in GitHub Discussions** -5. **Create a new issue** with the "documentation" label - ---- - -## πŸ”„ Recently Updated - -- 2025-01-19: Created documentation index -- 2025-01-19: Moved AST operations docs from src/utils/ -- 2025-01-19: Created ARCHITECTURE.md -- 2025-01-19: Created CURRENT_TRUNK_FLOW.md -- 2025-01-19: Created ERROR_HANDLING.md -- 2025-01-19: Updated TRUNK_FLOW_PLAN.md to mark as future roadmap - ---- - -## πŸ“œ License - -All documentation is licensed under the same license as PipeCraft (see [LICENSE](https://github.com/the-craftlab/pipecraft/blob/main/LICENSE)). - ---- - -**Happy building! πŸš€** diff --git a/docs/docs/error-handling.md b/docs/docs/error-handling.md index 5c505400..95b3628f 100644 --- a/docs/docs/error-handling.md +++ b/docs/docs/error-handling.md @@ -1,4 +1,4 @@ -# PipeCraft Error Handling Guide +# Error Reference ## Overview @@ -784,4 +784,4 @@ If you encounter an error not covered in this guide: - [Architecture](/docs/architecture) - System design and components - [Current Trunk Flow](/docs/flows/trunk-flow) - Implementation details - [Getting Started](intro) - User guide and examples -- [Testing Guide](/docs/testing-guide) - Testing guidelines +- [Troubleshooting](/docs/troubleshooting) - Symptom-based fixes for common issues diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 10d34299..0d4b3713 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -547,7 +547,7 @@ Your customizations will be preserved during regeneration. ### How can I contribute? -We welcome contributions! See the [Contributing guide](contributing.md) for: +We welcome contributions! See the [Contributing guide](https://github.com/the-craftlab/pipecraft/blob/main/CONTRIBUTING.md) for: - Development setup - Code architecture diff --git a/docs/docs/readme.md b/docs/docs/readme.md deleted file mode 100644 index 737ff0f8..00000000 --- a/docs/docs/readme.md +++ /dev/null @@ -1,1179 +0,0 @@ -![PipeCraft Logo](https://raw.githubusercontent.com/the-craftlab/pipecraft/main/assets/logo_banner.png) - -# PipeCraft - -[![npm version](https://badge.fury.io/js/pipecraft.svg)](https://www.npmjs.com/package/pipecraft) -[![License](https://img.shields.io/npm/l/pipecraft.svg)](https://github.com/the-craftlab/pipecraft/blob/main/LICENSE) -[![NPM downloads](https://img.shields.io/npm/dm/pipecraft.svg)](https://www.npmjs.com/package/pipecraft) -[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/en/) -[![codecov](https://codecov.io/gh/the-craftlab/pipecraft/branch/main/graph/badge.svg)](https://codecov.io/gh/the-craftlab/pipecraft) - -**Pipeline Status:** -[![develop](https://img.shields.io/github/actions/workflow/status/the-craftlab/pipecraft/pipeline.yml?branch=develop&label=develop)](https://github.com/the-craftlab/pipecraft/actions/workflows/pipeline.yml?query=branch%3Adevelop) -[![staging](https://img.shields.io/github/actions/workflow/status/the-craftlab/pipecraft/pipeline.yml?branch=staging&label=staging)](https://github.com/the-craftlab/pipecraft/actions/workflows/pipeline.yml?query=branch%3Astaging) -[![main](https://img.shields.io/github/actions/workflow/status/the-craftlab/pipecraft/pipeline.yml?branch=main&label=main)](https://github.com/the-craftlab/pipecraft/actions/workflows/pipeline.yml?query=branch%3Amain) - -PipeCraft is a powerful CLI tool for automating trunk-based development workflows with GitHub Actions. It generates intelligent CI/CD pipelines that adapt to your codebase structure, support multiple domains (monorepos), handle semantic versioning, and manage branch flows with fast-forward merging strategies. - -## Table of Contents - -- [Features](#features) -- [Prerequisites](#prerequisites) -- [Quick Start](#quick-start) -- [Installation](#installation) -- [Usage](#usage) - - [CLI Examples](#cli-examples) - - [Configuration](#configuration) -- [Commands](#commands) -- [Pre-Flight Checks](#pre-flight-checks) -- [GitHub Actions Setup](#github-actions-setup) -- [Configuration Options](#configuration-options) -- [Domain-Based Workflows](#domain-based-workflows) -- [Version Management](#version-management) -- [Examples](#examples) -- [Documentation](#documentation) -- [Roadmap & Future Features](#roadmap--future-features) -- [Troubleshooting](#troubleshooting) -- [Contributing](#contributing) -- [License](#license) -- [Acknowledgments](#acknowledgments) - -## Features - -- **Automatic CI/CD Pipeline Generation** - Generate GitHub Actions workflows tailored to your branch flow -- **Pre-Flight Checks** - Validates prerequisites before generating workflows with helpful error messages -- **Domain-Based Change Detection** - Smart path-based detection for monorepo architectures -- **Semantic Versioning** - Automatic version bumping based on conventional commits -- **Branch Flow Management** - Support for custom branch flows (develop β†’ staging β†’ main) -- **Fast-Forward Merging** - Automatic branch management with configurable merge strategies -- **Idempotent Regeneration** - Only regenerate when configuration or templates change -- **User Job Preservation** - Regenerates pipelines while preserving your custom jobs and comments -- **Customizable Actions** - Define actions per branch merge (tests, deploys, version bumps) -- **GitHub Setup Automation** - Automated token and repository setup validation - -> **Note**: This release focuses on GitHub Actions workflows. GitLab CI/CD support is [planned](#roadmap--future-features) for a future release. Currently, the `ciProvider` field accepts `'gitlab'` but generates GitHub Actions syntax. - -## Prerequisites - -- **Git** - Version control system -- **GitHub Account** - For GitHub Actions workflows -- **Node.js 18.0.0 or higher** - For npm installation - -## Quick Start - -1. Initialize PipeCraft in your project: - - ```bash - npx pipecraft init - ``` - -2. Generate your CI/CD workflows: - - ```bash - npx pipecraft generate - ``` - -3. Commit the generated files: - ```bash - git add .github/workflows .pipecraftrc.json - git commit -m "chore: add PipeCraft workflows" - git push - ``` - -That's it! Your trunk-based development workflow is now automated. - -## Installation - -### Option 1: Using npx (recommended for trying it out) - -No installation required! Just run commands with `npx`: - -```bash -npx pipecraft init -``` - -### Option 2: Global installation via npm - -```bash -npm install -g pipecraft -``` - -### Option 3: Local project installation - -```bash -npm install --save-dev pipecraft -``` - -Then add to your `package.json` scripts: - -```json -{ - "scripts": { - "workflow:init": "pipecraft init", - "workflow:generate": "pipecraft generate", - "workflow:validate": "pipecraft validate" - } -} -``` - -## Usage - -### CLI Examples - -PipeCraft provides several commands to manage your trunk-based development workflows: - -#### 1. Initialize Configuration - -Create a basic configuration with default settings: - -```bash -pipecraft init -``` - -Force overwrite existing configuration: - -```bash -pipecraft init --force -``` - -> **Note**: The `init` command currently generates a default configuration file with standard trunk flow settings (develop β†’ staging β†’ main). You can then edit the `.pipecraftrc.json` file to customize branch names, domains, and other settings. - -#### 2. Generate Workflows - -Generate CI/CD workflows based on your configuration: - -```bash -pipecraft generate -``` - -The generate command automatically runs pre-flight checks to validate: - -- Configuration file exists and is valid -- Required fields are present (ciProvider, branchFlow, domains) -- Current directory is a git repository -- Git remote is configured -- .github/workflows directory is writable - -If any check fails, you'll see helpful error messages with suggestions. Example output: - -``` -πŸ” Running pre-flight checks... - -βœ… Configuration found: /path/to/.pipecraftrc.json -βœ… Configuration is valid -❌ Not in a git repository - πŸ’‘ Initialize git: 'git init' or clone an existing repository -``` - -**Output verbosity levels:** - -Normal mode (default) - Clean, actionable output: - -```bash -pipecraft generate -``` - -Shows only essential information: pre-flight checks and completion status. - -Verbose mode - Shows file operations: - -```bash -pipecraft generate --verbose -``` - -Includes file merge status, config paths, and workflow generation details. - -Debug mode - Full internal details: - -```bash -pipecraft generate --debug -``` - -Includes everything from verbose mode plus internal debugging information like branch flow context, job ordering, and template operations. - -**Other options:** - -Skip pre-flight checks (not recommended): - -```bash -pipecraft generate --skip-checks -``` - -Force regeneration (bypass cache): - -```bash -pipecraft generate --force -``` - -Preview what would be generated (dry run): - -```bash -pipecraft generate --dry-run -``` - -Use custom config and output paths: - -```bash -pipecraft generate --config custom-config.json --output-pipeline .github/workflows/custom.yml -``` - -#### 3. Validate Configuration - -Check if your configuration is valid: - -```bash -pipecraft validate -``` - -Validate a custom config file: - -```bash -pipecraft validate --config custom-config.json -``` - -#### 4. Verify Setup - -Verify that PipeCraft is properly configured: - -```bash -pipecraft verify -``` - -This checks: - -- Configuration file exists and is valid -- GitHub Actions workflows exist (for GitHub projects) -- Repository structure is correct - -#### 5. Version Management - -Check current and next version: - -```bash -pipecraft version --check -``` - -Bump version based on conventional commits: - -```bash -pipecraft version --bump -``` - -Create a release: - -```bash -pipecraft version --release -``` - -#### 6. Branch Setup - -Create all branches defined in your branch flow: - -```bash -pipecraft setup -``` - -This automatically creates and pushes all branches to your remote repository. - -### Configuration - -PipeCraft uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) for flexible configuration discovery. It will look for configuration in the following order: - -1. Command-line options -2. `.pipecraftrc.json` file -3. `.pipecraftrc` file -4. `pipecraft` key in `package.json` -5. Default values - -Example `.pipecraftrc.json`: - -```json -{ - "ciProvider": "github", - "mergeStrategy": "fast-forward", - "requireConventionalCommits": true, - "initialBranch": "develop", - "finalBranch": "main", - "branchFlow": ["develop", "staging", "main"], - "semver": { - "bumpRules": { - "feat": "minor", - "fix": "patch", - "breaking": "major" - } - }, - "domains": { - "api": { - "paths": ["apps/api/**"], - "description": "API application changes" - }, - "web": { - "paths": ["apps/web/**"], - "description": "Web application changes" - } - } -} -``` - -## Commands - -PipeCraft provides the following commands: - -| Command | Description | Key Options | -| -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ | -| `init` | Initialize PipeCraft configuration | `--force` | -| `generate` | Generate CI/CD workflows with pre-flight checks | `--skip-checks`, `--force`, `--dry-run`, `--config`, `--output-pipeline`, `--verbose`, `--debug` | -| `validate` | Validate configuration file | `--config` | -| `setup-github` | Configure GitHub Actions workflow permissions | `--apply`, `--force` | -| `verify` | Verify PipeCraft setup | None | -| `version` | Version management commands | `--check`, `--bump`, `--release` | -| `setup` | Create branches from branch flow | `--force` | - -> **Note**: All commands support global options like `--verbose` and `--debug` for detailed output. - -### Global Options - -Available for all commands: - -- `-c, --config ` - Path to config file (default: `.pipecraftrc.json`) -- `-p, --pipeline ` - Path to existing pipeline file for merging -- `-o, --output-pipeline ` - Path to output pipeline file -- `-v, --verbose` - Verbose output (shows file operations and merge status) -- `--debug` - Debug output (includes verbose output plus internal debugging details) -- `--force` - Force operation even if unchanged -- `--dry-run` - Show what would be done without making changes - -### Command Examples - -```bash -# Initialize configuration (creates .pipecraftrc.json with defaults) -pipecraft init - -# Generate workflows with custom paths -pipecraft generate --config .pipecraft.json --output-pipeline workflows/ci.yml - -# Generate with verbose output to see file operations -pipecraft generate --verbose - -# Generate with debug output to see internal details -pipecraft generate --debug - -# Setup GitHub Actions permissions (interactive mode) -pipecraft setup-github - -# Setup GitHub Actions permissions (auto-apply mode) -pipecraft setup-github --apply - -# Validate configuration before committing -pipecraft validate && git commit -am "chore: update workflow config" - -# Check what version would be bumped to -pipecraft version --check - -# Bump version based on conventional commits -pipecraft version --bump - -# Create a full release with tag and changelog -pipecraft version --release - -# Setup all branches for new repository -pipecraft setup -``` - -## Pre-Flight Checks - -PipeCraft includes comprehensive pre-flight validation to catch common errors before generating workflows. This helps new users avoid frustration and ensures your project is properly configured. - -### What Gets Checked - -When you run `pipecraft generate`, the following checks are automatically performed: - -1. **Configuration File Discovery** - - - Searches for config using [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) - - Looks in: `.pipecraftrc.json`, `.pipecraftrc`, `package.json` (pipecraft key) - - Searches parent directories recursively - - Shows the exact path where config was found - -2. **Configuration Validation** - - - Verifies JSON syntax is valid - - Checks all required fields are present: - - `ciProvider` (github or gitlab) - - `branchFlow` (array of branch names) - - `domains` (at least one domain configured) - - Validates domain configuration has paths defined - -3. **Git Repository Check** - - - Verifies current directory is a git repository - - Suggests running `git init` if not - -4. **Git Remote Check** - - - Verifies git remote is configured - - Shows the remote URL - - Suggests adding a remote if missing - -5. **Write Permissions** - - Tests that `.github/workflows` directory can be created/written to - - Checks file system permissions - -### Example Pre-Flight Output - -**All checks passing:** - -``` -πŸ” Running pre-flight checks... - -βœ… Configuration found: /path/to/project/.pipecraftrc.json -βœ… Configuration is valid -βœ… Current directory is a git repository -βœ… Git remote configured: https://github.com/user/repo.git -βœ… .github/workflows directory is writable - -βœ… All pre-flight checks passed! -``` - -**Checks failing with helpful suggestions:** - -``` -πŸ” Running pre-flight checks... - -❌ No PipeCraft configuration found - πŸ’‘ Run 'pipecraft init' to create a configuration file - -❌ Not in a git repository - πŸ’‘ Initialize git: 'git init' or clone an existing repository - -❌ No git remote configured - πŸ’‘ Add a remote: 'git remote add origin ' - -❌ Pre-flight checks failed. Fix the issues above and try again. - Or use --skip-checks to bypass (not recommended) -``` - -### Skipping Pre-Flight Checks - -While not recommended, you can skip pre-flight checks if needed: - -```bash -pipecraft generate --skip-checks -``` - -**When you might skip checks:** - -- CI/CD environment with non-standard setup -- Using PipeCraft in a script/automation -- Advanced users who know the risks - -**Why you shouldn't skip:** - -- Prevents cryptic errors during generation -- Saves time by catching issues early -- Provides actionable error messages -- Ensures consistent behavior across environments - -## GitHub Actions Setup - -PipeCraft requires specific GitHub Actions permissions and repository settings to function correctly. The `setup-github` command helps you configure everything automatically. - -### What Gets Configured - -The `setup-github` command configures: - -1. **Workflow Permissions** - - - Default workflow permissions: **write** (for creating tags and pushing changes) - - Can create/approve pull requests: **Yes** (for automated PR creation) - -2. **Repository Auto-Promote** - - - Enables auto-merge feature at repository level - - Required for automatic promotion between branches - -3. **Branch Protection Rules** (for branches with auto-merge enabled) - - Status checks enabled (no specific checks required) - - Required linear history (prevents messy merges) - - No force pushes or branch deletion - - These rules are required for GitHub's auto-merge feature to work - -### Usage - -**Interactive Mode (Default)** - -Prompts you for each permission change: - -```bash -pipecraft setup-github -``` - -The command will: - -1. Check your current repository permissions -2. Enable repository-level auto-merge if needed -3. Configure branch protection for branches with `autoPromote: true` in config -4. Prompt you to apply each change -5. Update the settings if you accept - -**Auto-Apply Mode** - -Automatically applies all required changes without prompting: - -```bash -pipecraft setup-github --apply -# or -pipecraft setup-github --force -``` - -This mode is useful for: - -- CI/CD pipeline setup scripts -- Automated repository initialization -- Batch configuration of multiple repositories - -### Example Output - -**Interactive mode:** - -``` -πŸ” Checking GitHub repository configuration... - -πŸ“¦ Repository: user/repo -βœ… GitHub token found -πŸ” Fetching current workflow permissions... - -πŸ“‹ Current GitHub Actions Workflow Permissions: - Default permissions: read - Can create/approve PRs: No - -⚠️ PipeCraft requires the following permissions: - β€’ Default permissions: write (for creating tags and pushing) - β€’ Can create/approve PRs: Yes (for automated PR creation) - -? Change default workflow permissions from "read" to "write"? (Y/n) Yes - -πŸ” Checking auto-merge configuration... -βœ… Enabled auto-merge for repository -πŸ“‹ Branches with auto-merge enabled: staging -? Enable branch protection for 'staging' to support auto-merge? (Y/n) Yes -πŸ”§ Configuring branch protection for staging... -βœ… Branch protection enabled for staging - -✨ Setup complete! -``` - -**Auto-apply mode:** - -``` -πŸ” Checking GitHub repository configuration... - -πŸ“¦ Repository: user/repo -βœ… GitHub token found -πŸ” Fetching current workflow permissions... - -βœ… Workflow permissions are already configured correctly! - -πŸ” Checking auto-merge configuration... -βœ… Enabled auto-merge for repository -πŸ“‹ Branches with auto-merge enabled: staging -πŸ”§ Configuring branch protection for staging... -βœ… Branch protection enabled for staging - -✨ Setup complete! - -πŸ’‘ You can verify the changes at: - https://github.com/user/repo/settings/actions -``` - -### Authentication - -The command requires a GitHub token with admin access to your repository. It will automatically use: - -1. `GITHUB_TOKEN` environment variable -2. `GH_TOKEN` environment variable -3. GitHub CLI (`gh`) authentication - -To authenticate with GitHub CLI: - -```bash -gh auth login -``` - -Or set an environment variable: - -```bash -export GITHUB_TOKEN=ghp_your_token_here -``` - -### Manual Configuration - -You can also configure these settings manually: - -**Workflow Permissions:** - -1. Go to your repository on GitHub -2. Navigate to **Settings** β†’ **Actions** β†’ **General** -3. Under "Workflow permissions": - - Select **Read and write permissions** - - Check **Allow GitHub Actions to create and approve pull requests** -4. Click **Save** - -**Repository Auto-Promote:** - -1. Navigate to **Settings** β†’ **General** -2. Scroll to "Pull Requests" -3. Check **Allow auto-merge** -4. Click **Save** - -**Branch Protection (for branches with auto-merge):** - -1. Navigate to **Settings** β†’ **Branches** -2. Click **Add branch protection rule** or edit existing rule -3. In "Branch name pattern", enter the branch name (e.g., `staging`) -4. Configure the following: - - Check **Require status checks to pass before merging** - - Leave status checks empty (or add your own) - - Check **Require linear history** - - Leave other options as needed -5. Click **Create** or **Save changes** - -Note: Branch protection rules are required for auto-merge to work in GitHub. - -## Configuration Options - -### Core Configuration - -| Option | Type | Required | Default | Description | -| ---------------------------- | --------------------------- | -------- | ---------------- | ---------------------------- | -| `ciProvider` | `'github' \| 'gitlab'` | Yes | `'github'` | CI/CD provider | -| `mergeStrategy` | `'fast-forward' \| 'merge'` | Yes | `'fast-forward'` | Branch merge strategy | -| `requireConventionalCommits` | `boolean` | No | `true` | Enforce conventional commits | -| `initialBranch` | `string` | Yes | `'develop'` | First branch in flow | -| `finalBranch` | `string` | Yes | `'main'` | Final production branch | -| `branchFlow` | `string[]` | Yes | - | Ordered list of branches | - -### Semantic Versioning - -| Option | Type | Description | -| --------------------------- | ------------------------------- | --------------------------------- | -| `semver.bumpRules.feat` | `'major' \| 'minor' \| 'patch'` | Version bump for features | -| `semver.bumpRules.fix` | `'major' \| 'minor' \| 'patch'` | Version bump for fixes | -| `semver.bumpRules.breaking` | `'major' \| 'minor' \| 'patch'` | Version bump for breaking changes | - -### Domains (Monorepo Support) - -Define multiple domains for path-based change detection: - -```json -{ - "domains": { - "api": { - "paths": ["apps/api/**", "libs/api-utils/**"], - "description": "API application and utilities" - }, - "web": { - "paths": ["apps/web/**", "libs/ui-components/**"], - "description": "Web application and UI components" - }, - "mobile": { - "paths": ["apps/mobile/**"], - "description": "Mobile application" - } - } -} -``` - -Each domain can have: - -- `paths` (required): Array of glob patterns for file matching -- `description` (optional): Human-readable description - -### Versioning Configuration - -```json -{ - "versioning": { - "enabled": true, - "releaseItConfig": ".release-it.cjs", - "conventionalCommits": true, - "autoTag": true, - "autoPush": true, - "changelog": true, - "bumpRules": { - "feat": "minor", - "fix": "patch", - "breaking": "major" - } - } -} -``` - -### Rebuild/Idempotency Configuration - -Control when workflows are regenerated: - -```json -{ - "rebuild": { - "enabled": true, - "skipIfUnchanged": true, - "forceRegenerate": false, - "watchMode": false, - "hashAlgorithm": "sha256", - "cacheFile": ".pipecraft-cache.json", - "ignorePatterns": ["*.md", "docs/**"] - } -} -``` - -## Domain-Based Workflows - -PipeCraft excels at managing monorepo workflows with multiple domains. The generated workflows automatically detect which domains have changes and run appropriate jobs. - -### How It Works - -1. **Change Detection**: The `changes` job uses GitHub's `paths-filter` action to detect which domains have modifications -2. **Conditional Jobs**: Domain-specific jobs only run if changes are detected in their paths -3. **Parallel Execution**: Independent domains run in parallel for faster CI times -4. **Dependency Management**: Jobs can depend on specific domain changes - -### Example Generated Workflow - -```yaml -name: Pipeline - -on: - pull_request: - branches: - - develop - - staging - - main - -jobs: - changes: - runs-on: ubuntu-latest - outputs: - api: ${{ steps.changes.outputs.api }} - web: ${{ steps.changes.outputs.web }} - steps: - - uses: actions/checkout@v4 - - uses: dorny/paths-filter@v3 - id: changes - with: - filters: | - api: - - 'apps/api/**' - web: - - 'apps/web/**' - - test-api: - needs: changes - if: needs.changes.outputs.api == 'true' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Run API tests - run: npm test --workspace=api - - test-web: - needs: changes - if: needs.changes.outputs.web == 'true' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Run Web tests - run: npm test --workspace=web -``` - -## Version Management - -PipeCraft integrates with [release-it](https://github.com/release-it/release-it) for automated semantic versioning. - -### Setup Version Management - -```bash -pipecraft init --with-versioning -``` - -This creates: - -- `.release-it.cjs` - Release-it configuration -- `commitlint.config.js` - Commit message linting -- `.husky/commit-msg` - Git hook for commit validation - -### Version Commands - -Check what the next version would be: - -```bash -pipecraft version --check -``` - -Output: - -``` -πŸ“¦ Current version: 1.2.3 -πŸ“¦ Next version: 1.3.0 (minor) -πŸ“ Conventional commits: βœ… Valid -``` - -Bump version based on commits: - -```bash -pipecraft version --bump -``` - -Create a full release: - -```bash -pipecraft version --release -``` - -### Conventional Commits - -PipeCraft works best with conventional commits: - -- `feat:` - New feature (minor bump) -- `fix:` - Bug fix (patch bump) -- `feat!:` or `BREAKING CHANGE:` - Breaking change (major bump) -- `chore:`, `docs:`, `style:`, `refactor:`, `test:` - No version bump - -Example: - -```bash -git commit -m "feat: add user authentication" # Bumps to 1.3.0 -git commit -m "fix: resolve login bug" # Bumps to 1.3.1 -git commit -m "feat!: redesign API structure" # Bumps to 2.0.0 -``` - -## Examples - -### Example 1: Simple Project with Linear Branch Flow - -Configuration for a project with develop β†’ main flow: - -```json -{ - "ciProvider": "github", - "mergeStrategy": "fast-forward", - "initialBranch": "develop", - "finalBranch": "main", - "branchFlow": ["develop", "main"], - "domains": { - "app": { - "paths": ["src/**"], - "description": "Application code" - } - } -} -``` - -### Example 2: Enterprise Monorepo with Multiple Environments - -Configuration for staging environment: - -```json -{ - "ciProvider": "github", - "mergeStrategy": "fast-forward", - "requireConventionalCommits": true, - "initialBranch": "develop", - "finalBranch": "production", - "branchFlow": ["develop", "staging", "uat", "production"], - "semver": { - "bumpRules": { - "feat": "minor", - "fix": "patch", - "breaking": "major" - } - }, - "domains": { - "api": { - "paths": ["services/api/**", "libs/api-core/**"], - "description": "API services and core libraries" - }, - "web": { - "paths": ["apps/web/**", "libs/ui/**"], - "description": "Web application and UI libraries" - }, - "mobile": { - "paths": ["apps/mobile/**"], - "description": "Mobile application" - }, - "shared": { - "paths": ["libs/shared/**", "packages/**"], - "description": "Shared libraries and packages" - } - }, - "versioning": { - "enabled": true, - "conventionalCommits": true, - "autoTag": true, - "changelog": true - } -} -``` - -### Example 3: GitLab CI Project - -Configuration for GitLab: - -```json -{ - "ciProvider": "gitlab", - "mergeStrategy": "merge", - "initialBranch": "develop", - "finalBranch": "main", - "branchFlow": ["develop", "main"], - "domains": { - "backend": { - "paths": ["backend/**"], - "description": "Backend services" - }, - "frontend": { - "paths": ["frontend/**"], - "description": "Frontend application" - } - } -} -``` - -### Example 4: Custom Branch Names - -Configuration with non-standard branch names: - -```json -{ - "ciProvider": "github", - "mergeStrategy": "fast-forward", - "initialBranch": "alpha", - "finalBranch": "release", - "branchFlow": ["alpha", "beta", "gamma", "release"], - "domains": { - "core": { - "paths": ["core/**"], - "description": "Core functionality" - } - } -} -``` - -## Documentation - -PipeCraft provides comprehensive documentation for different aspects of the project: - -### Core Documentation - -- **[Architecture](/docs/architecture)** - System architecture overview, design patterns, and component interactions -- **[Current Trunk Flow](/docs/flows/trunk-flow)** - Current implemented trunk-based development workflow -- **[Error Handling](/docs/error-handling)** - Error handling strategies and common error scenarios -- **[Testing Guide](/docs/testing-guide)** - Complete testing guide with examples and best practices - -### Development Documentation - -- **[Test Structure](https://github.com/the-craftlab/pipecraft/tree/main/tests)** - Test structure and organization on GitHub -- **[Repository Structure](https://github.com/the-craftlab/pipecraft)** - Repository organization and structure - -### Planning Documents - -- **[Trunk Flow Roadmap](https://github.com/the-craftlab/pipecraft/blob/main/TRUNK_FLOW_PLAN.md)** - Future roadmap for trunk flow variations _(future plans, not current implementation)_ - -### Quick Links - -- **Architecture**: Understand how PipeCraft works internally -- **Current Trunk Flow**: See what's implemented in this release -- **Testing Guide**: Learn how to test PipeCraft or contribute tests -- **Error Handling**: Debug issues and understand error messages - -## Roadmap & Future Features - -PipeCraft is actively being developed with plans for additional features and improvements. - -### Current Release (v1.x) - -This release focuses on a **solid, working trunk-based development workflow** for GitHub Actions with: - -βœ… **Develop β†’ Staging β†’ Main** branch flow -βœ… **Domain-based change detection** for monorepos -βœ… **Semantic versioning** with conventional commits -βœ… **User job preservation** during regeneration -βœ… **Pre-flight checks** for smooth setup -βœ… **Comprehensive documentation** and testing - -See [Current Trunk Flow](/docs/flows/trunk-flow) for details on what's implemented. - -### Planned Features - -The roadmap is documented in [TRUNK_FLOW_PLAN.md](https://github.com/the-craftlab/pipecraft/blob/main/TRUNK_FLOW_PLAN.md). Key planned features include: - -#### Short Term (v2.x) - -- **Enhanced GitLab Support** - Full GitLab CI/CD pipeline generation -- **Interactive Configuration** - Interactive `init` command with prompts -- **Additional Flow Variations** - Gitflow, release branches, hotfix workflows -- **CLI Improvements** - Better error messages, configuration migration tools - -#### Medium Term (v3.x) - -- **Extended CI/CD Providers** - Azure DevOps, Jenkins, CircleCI, Bitbucket -- **Advanced Branch Management** - Conflict resolution, PR templates -- **Visual Workflow Editor** - Web-based workflow configuration tool - -#### Long Term (v4.x+) - -- **Enterprise Features** - Team templates, policy enforcement, audit logging -- **Plugin System** - Custom workflow patterns and extensions -- **Multi-Repository** Support - Manage pipelines across multiple repos - -For the complete roadmap and feature comparison, see [TRUNK_FLOW_PLAN.md](https://github.com/the-craftlab/pipecraft/blob/main/TRUNK_FLOW_PLAN.md). - -### Contributing to the Roadmap - -Have a feature request? We'd love to hear from you! - -1. Check existing [feature requests](https://github.com/the-craftlab/pipecraft/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) -2. [Open a new feature request](https://github.com/the-craftlab/pipecraft/issues/new?labels=enhancement) -3. Vote on existing feature requests with πŸ‘ -4. Consider contributing! See [Contributing](#contributing) - -## Troubleshooting - -### Common Issues - -#### 1. Workflows Not Generating - -**Problem**: Running `pipecraft generate` doesn't create files. - -**Solutions**: - -- PipeCraft now runs automatic pre-flight checks that will catch most issues -- Review the pre-flight check output for specific problems -- Check if configuration is valid: `pipecraft validate` -- Use `--force` to bypass cache: `pipecraft generate --force` -- Use `--verbose` for detailed output: `pipecraft generate --verbose` -- Use `--debug` for full debugging output: `pipecraft generate --debug` -- Verify file permissions in `.github/workflows/` - -#### 2. Configuration Validation Errors - -**Problem**: Getting validation errors when running commands. - -**Solutions**: - -- Ensure all required fields are present (ciProvider, branchFlow, domains) -- Check that `initialBranch` and `finalBranch` are in `branchFlow` -- Verify domain paths are valid glob patterns -- Use `pipecraft validate` to see specific errors - -#### 3. Branch Flow Not Working - -**Problem**: Branches aren't being created or fast-forwarded. - -**Solutions**: - -- Run `pipecraft setup` to create missing branches -- Verify GitHub token has push permissions -- Check that branch protection rules allow fast-forward merges -- Ensure branches exist on remote: `git push origin branch-name` - -#### 4. Version Management Not Working - -**Problem**: Version bumps aren't happening automatically. - -**Solutions**: - -- Initialize version management: `pipecraft init --with-versioning` -- Ensure commits follow conventional format -- Check that `package.json` exists with version field -- Verify `release-it` is configured: check `.release-it.cjs` - -#### 5. Cache Issues - -**Problem**: Changes not being detected after config update. - -**Solutions**: - -- Force regeneration: `pipecraft generate --force` -- Delete cache file: `rm .pipecraft-cache.json` -- Check cache file permissions -- Verify `rebuild.enabled` is `true` in config - -### Getting Help - -If you encounter issues not covered here: - -1. Check the [GitHub Issues](https://github.com/the-craftlab/pipecraft/issues) -2. Enable verbose logging: `pipecraft generate --verbose` -3. Enable debug logging for more detail: `pipecraft generate --debug` -4. Validate your configuration: `pipecraft validate` -5. [Open a new issue](https://github.com/the-craftlab/pipecraft/issues/new) with: - - PipeCraft version: `pipecraft --version` - - Node version: `node --version` - - Your configuration (sanitized) - - Full error output with `--debug` - -## Contributing - -Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/the-craftlab/pipecraft/blob/main/CONTRIBUTING.md) for details on: - -- Code of conduct -- Development setup -- Running tests -- Submitting pull requests -- Coding standards - -### Development Setup - -```bash -# Clone the repository -git clone https://github.com/the-craftlab/pipecraft.git -cd pipecraft - -# Install dependencies -npm install - -# Run tests -npm test - -# Run in development mode -npm run dev -- init --interactive -``` - -### Running Tests - -```bash -# Run all tests -npm test - -# Run with coverage -npm run test:coverage - -# Run in watch mode -npm run test:watch - -# Run specific test file -npm test tests/unit/config.test.ts -``` - -## License - -This project is licensed under the MIT License - see the [LICENSE](https://github.com/the-craftlab/pipecraft/blob/main/LICENSE) file for details. - -## Acknowledgments - -- **PullCraft** - Sister project for automated PR generation -- **Pinion** - Template generation framework by FeathersCloud -- **Commander** - CLI framework -- **release-it** - Version management and releases -- All contributors who have helped improve PipeCraft - ---- - -
- -**Built with ❀️ for trunk-based development teams** - -[Report Bug](https://github.com/the-craftlab/pipecraft/issues) · [Request Feature](https://github.com/the-craftlab/pipecraft/issues) · [Documentation](https://github.com/the-craftlab/pipecraft/wiki) - -
diff --git a/docs/sidebars.ts b/docs/sidebars.ts index f3974dcc..9128aefc 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -3,48 +3,62 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs' // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) /** - * Creating a sidebar enables you to: - - create an ordered group of docs - - render a sidebar for each doc of that group - - provide next/previous navigation - - The sidebars can be generated from the filesystem, or explicitly defined here. - - Create as many sidebars as you want. + * User-facing documentation sidebar. + * + * Organized by DiΓ‘taxis-style intent: get started β†’ guides (do) β†’ reference (look up) β†’ + * understand (concepts) β†’ help. Developer/internal material (contributing, testing the + * project itself, the generated source API) lives with the repo README, not here. */ const sidebars: SidebarsConfig = { tutorialSidebar: [ - 'intro', - 'commands', - 'configuration-reference', - 'action-modes', - 'cli-reference', - 'workflow-generation', - 'architecture', { type: 'category', - label: 'Workflow Patterns', + label: 'Get started', collapsed: false, - items: ['flows/trunk-flow', 'flows/github-flow', 'flows/gitflow', 'flows/custom-flow'] + items: ['intro', { type: 'doc', id: 'cli-reference', label: 'Quickstart' }] }, - 'version-management', - 'examples', - 'troubleshooting', - 'error-handling', - 'testing-guide', - 'faq', - 'security', - 'roadmap', - 'contributing', { type: 'category', - label: 'API Reference', - collapsed: true, + label: 'Guides', + collapsed: false, items: [ + 'workflow-generation', { - type: 'autogenerated', - dirName: 'api' - } + type: 'category', + label: 'Workflow patterns', + collapsed: true, + items: ['flows/trunk-flow', 'flows/github-flow', 'flows/gitflow', 'flows/custom-flow'] + }, + 'version-management', + 'examples' + ] + }, + { + type: 'category', + label: 'Reference', + collapsed: false, + items: [ + { type: 'doc', id: 'commands', label: 'CLI reference' }, + 'configuration-reference', + 'action-modes' + ] + }, + { + type: 'category', + label: 'Understand', + collapsed: true, + items: ['architecture'] + }, + { + type: 'category', + label: 'Help', + collapsed: true, + items: [ + 'troubleshooting', + { type: 'doc', id: 'error-handling', label: 'Error reference' }, + 'faq', + 'roadmap', + 'security' ] } ] diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index fdd4d56e..9a69b1d0 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -36,7 +36,7 @@ function HomepageHeader({ version }: HomepageHeaderProps) { />
- + Get Started - 5min ⏱️
From fe6c2d629c5ce76aea3181b2291e9d7172b87cd0 Mon Sep 17 00:00:00 2001 From: James Villarrubia Date: Wed, 24 Jun 2026 22:58:15 -0400 Subject: [PATCH 2/2] docs: fix Quickstart tutorial inaccuracies (found via example testing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - init is non-interactive by default (--interactive opts into the wizard); drop the stale package-manager auto-detection prompts (packageManager is deprecated) - add the missing 'pipecraft setup' step (creates the branch flow on the remote) β€” its absence is why promotions fail with 'Base ref must be a branch' - clarify setup (branches) vs setup-github (permissions); fix example step numbering - minimal config example: add required mergeStrategy/requireConventionalCommits/semver and use prefixes instead of deprecated testable/deployable Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/docs/cli-reference.md | 49 +++++++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 19 deletions(-) diff --git a/docs/docs/cli-reference.md b/docs/docs/cli-reference.md index fbfa7f20..4bdb5667 100644 --- a/docs/docs/cli-reference.md +++ b/docs/docs/cli-reference.md @@ -27,23 +27,19 @@ cd your-project npx pipecraft init ``` -This launches an interactive setup that asks you about your project structure. It will ask questions like: +By default `init` is **non-interactive**: it writes a starter `.pipecraftrc` using sensible defaults, which you can override with flags: -- Which branches you want to use (develop, staging, main) -- Which package manager you use (npm, yarn, or pnpm) - auto-detected from lockfiles -- What domains exist in your codebase (api, web, etc.) -- Which paths belong to each domain - -The init command automatically detects your package manager by checking for lockfiles: +```bash +npx pipecraft init --initial-branch develop --final-branch main --ci-provider github +``` -- `pnpm-lock.yaml` β†’ pnpm -- `yarn.lock` β†’ yarn -- `package-lock.json` β†’ npm -- No lockfile β†’ defaults to npm +Prefer to be walked through it? Use the interactive wizard: -You can confirm or override the detected package manager during the interactive prompts. +```bash +npx pipecraft init --interactive +``` -Once complete, you'll have a `.pipecraftrc` file that contains your configuration (format can be JSON, YAML, or JavaScript). +Once complete, you'll have a `.pipecraftrc` file you can edit to define your branch flow and domains (format can be JSON, YAML, or JavaScript). Domain change detection is path-based, so any project β€” including monorepos β€” is configured by pointing each domain at its file globs. ## Generating workflows @@ -224,20 +220,28 @@ npx pipecraft init # 3. Generate workflows npx pipecraft generate -# 5. Review the generated files +# 4. Review the generated files ls -la .github/workflows/ cat .github/workflows/pipeline.yml -# 6. Commit the changes +# 5. Commit the changes git add .github/ .pipecraftrc git commit -m "chore: add pipecraft workflows" git push -# 7. Set up GitHub (requires a token) -export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx +# 6. Create the branch flow (develop, staging, main, ...) on the remote pipecraft setup + +# 7. Configure GitHub Actions permissions (requires a token) +export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx +pipecraft setup-github --apply ``` +Two distinct setup commands, both needed before promotions work: + +- **`pipecraft setup`** creates the branches in your `branchFlow` on the remote (e.g. `staging`, `production`). Promotion opens PRs into these branches, so they must exist first. +- **`pipecraft setup-github`** configures the repository's Actions permissions (read/write, allow PR creation) so the version/tag/promote jobs can run. + ## Configuration file PipeCraft looks for configuration in several places, in this order: @@ -254,19 +258,26 @@ Most projects use `.pipecraftrc` because it's simple and can be either JSON or Y ```json { "ciProvider": "github", + "mergeStrategy": "fast-forward", + "requireConventionalCommits": true, "branchFlow": ["develop", "staging", "main"], "initialBranch": "develop", "finalBranch": "main", + "semver": { + "bumpRules": { "feat": "minor", "fix": "patch", "breaking": "major" } + }, "domains": { "app": { "paths": ["src/**"], - "testable": true, - "deployable": true + "description": "Application code", + "prefixes": ["test", "deploy"] } } } ``` +`mergeStrategy`, `requireConventionalCommits`, and `semver` are required β€” `pipecraft validate` will tell you if any are missing. Use `prefixes` to choose which jobs a domain generates (e.g. `["test", "deploy"]`); the older `testable`/`deployable` flags are deprecated. + This configuration tells PipeCraft to: - Generate GitHub Actions workflows