Contributing to flow

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

• Go - See go.mod for the required version
• flow CLI - Install the latest version before developing

# 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 tests
flow generate             # Code generation
flow 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:

• mockgen - Generate test mocks
• golangci-lint - Code linting
• go-jsonschema - Generate Go types from YAML schemas

Additional Tools

• goreleaser - Binary builds and package distribution
• Docker Buildx - Multi-arch container builds (included with Docker Desktop)
• ginkgo - BDD testing framework

Testing Releases Locally

flow uses a hybrid release system combining goreleaser (for binaries) and Docker buildx (for multi-arch containers):

# Test binary builds locally (no publish)
flow build snapshot

# Test Docker build locally for current platform (no push)
flow build docker-local -p IMAGE_TAG=dev

# Verify release configuration
flow check release

Dry-Run Safety: All build executables are safe to run locally. They create artifacts in dist/ without publishing to GitHub or container registries.

CI-Only Publishing: The publish executables are restricted to CI environments and will refuse to run locally unless explicitly confirmed.