Skip to content

development.md

Latest commit

 

History

History
135 lines (94 loc) · 4.48 KB

development.md

File metadata and controls

135 lines (94 loc) · 4.48 KB

Contributing to flow

Go Report Card Go Reference GitHub branch check runs Codecov

This document provides an overview of how to contribute to the flow project, including setting up your development environment, understanding the project structure, and running tests.

Before getting started, please read our Code of Conduct and Contributing Guidelines.

Ways to Contribute

  • Report bugs - Open an issue with reproduction steps
  • Suggest features - Share ideas for new functionality
  • Improve documentation - Fix typos, add examples, or clarify explanations
  • Write code - Fix bugs, implement features, or optimize performance
  • Share examples - Contribute to the examples repository

Quick Start

Prerequisites

# Clone and set up the repository
git clone https://github.com/flowexec/flow.git
cd flow

# Register the repo as a flow workspace
flow workspace add flow . --set

# Install development dependencies
flow install tools

# Verify everything works
flow validate

Development Executables

The flow project uses flow itself for development! Here are the key commands:

# Build the CLI binary
flow build binary ./bin/flow

# Run all validation (tests, linting, code generation)
flow validate

# Run specific checks
flow test all             # All tests
flow generate             # Code generation
flow run lint             # Linting only

# Install/update Go tools
flow install tools

Project Structure

flow/
├── .execs/             # Development workflows
├── cmd/                # CLI entry point
├── docs/               # Documentation
├── internal/           # Core application logic
│   ├── cache/          # Executable and workspace caching logic
│   ├── context/        # Global application context
│   ├── io/             # Terminal user interface and I/O
│   ├── runner/         # Executable execution engine
│   ├── services/       # Business logic services
│   ├── templates/      # Templating system for workflows
│   └── vault/          # Secret management
├── tests/              # CLI end-to-end test suite
└── types/              # Generated types from schemas

Some directories are omitted for brevity.

Working with Generated Code

flow uses code generation extensively:

Go CLI Type Generation

Types are generated from YAML schemas using go-jsonschema:

# Regenerate types after schema changes
flow generate cli

Important: When modifying types, edit the schemas/*.yaml files, not the generated Go files in types/.

Documentation Generation

CLI and type documentation is generated automatically:

# Updates both CLI docs and type reference docs
flow generate docs

TUI Development

flow uses tuikit for terminal interface development:

Local Development

# Link to local tuikit for development
go mod edit -replace github.com/flowexec/tuikit=../tuikit

# Test TUI changes
flow build binary ./bin/flow-dev
./bin/flow-dev browse

Development Tools

Required Tools

These are installed automatically by flow install tools:

Additional Tools