|
1 | | -# flow Development |
| 1 | +# Contributing to flow |
2 | 2 |
|
3 | 3 | [](https://goreportcard.com/report/github.com/flowexec/flow) |
4 | 4 | [](https://pkg.go.dev/github.com/flowexec/flow) |
5 | | -[](https://github.com/flowexec/flow/actions?query=branch%3Amain) |
| 5 | +[](https://github.com/flowexec/flow/actions?query=branch%3Amain) |
6 | 6 | [](https://app.codecov.io/gh/flowexec/flow) |
7 | 7 |
|
8 | | -Before getting started, please read the [Code of Conduct](../.github/CODE_OF_CONDUCT.md) and [Contributing Guidelines](../.github/CONTRIBUTING.md). |
| 8 | +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. |
9 | 9 |
|
10 | | -flow is written in [Go](https://golang.org/). See the [go.mod](../go.mod) file for the current Go version used in |
11 | | -building the project. |
| 10 | +Before getting started, please read our [Code of Conduct](https://github.com/flowexec/flow/blob/main/.github/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/flowexec/flow/blob/main/.github/CONTRIBUTING.md). |
12 | 11 |
|
13 | | -## Getting Started |
| 12 | +**Ways to Contribute** |
14 | 13 |
|
15 | | -Before developing on this project, you will need to make sure you have the latest `flow` version installed. |
16 | | -Refer to the [Installation](installation.md) section for more information. |
| 14 | +- **Report bugs** - [Open an issue](https://github.com/flowexec/flow/issues/new) with reproduction steps |
| 15 | +- **Suggest features** - Share ideas for new functionality |
| 16 | +- **Improve documentation** - Fix typos, add examples, or clarify explanations |
| 17 | +- **Write code** - Fix bugs, implement features, or optimize performance |
| 18 | +- **Share examples** - Contribute to the [examples repository](https://github.com/flowexec/examples) |
17 | 19 |
|
18 | | -After cloning the repository, you can start using the below commands after registering the repo workspace: |
| 20 | +## Quick Start |
| 21 | + |
| 22 | +**Prerequisites** |
| 23 | + |
| 24 | +- **Go** - See [go.mod](https://github.com/flowexec/flow/blob/main/go.mod) for the required version |
| 25 | +- **flow CLI** - Install the [latest version](installation.md) before developing |
19 | 26 |
|
20 | 27 | ```sh |
21 | | -flow workspace create flow <repo-path> |
| 28 | +# Clone and set up the repository |
| 29 | +git clone https://github.com/flowexec/flow.git |
| 30 | +cd flow |
| 31 | + |
| 32 | +# Register the repo as a flow workspace |
| 33 | +flow workspace add flow . --set |
| 34 | + |
| 35 | +# Install development dependencies |
| 36 | +flow install tools |
| 37 | + |
| 38 | +# Verify everything works |
| 39 | +flow validate |
22 | 40 | ``` |
23 | 41 |
|
24 | | -### Development Executables |
| 42 | +## Development Executables |
25 | 43 |
|
26 | | -The `flow` project contains a few development executables that can be run locally. After registering the repo |
27 | | -workspace, you can run the following commands: |
| 44 | +The flow project uses flow itself for development! Here are the key commands: |
28 | 45 |
|
29 | 46 | ```sh |
30 | | -# Install Go tool dependencies |
31 | | -flow install tools |
32 | | - |
33 | 47 | # Build the CLI binary |
34 | | -flow build binary <output-path> |
| 48 | +flow build binary ./bin/flow |
35 | 49 |
|
36 | | -# Validate code changes (runs tests, linters, codegen, etc) |
| 50 | +# Run all validation (tests, linting, code generation) |
37 | 51 | flow validate |
38 | 52 |
|
39 | | -# Only generate code |
40 | | -flow generate |
| 53 | +# Run specific checks |
| 54 | +flow test all # All tests |
| 55 | +flow generate # Code generation |
| 56 | +flow run lint # Linting only |
41 | 57 |
|
42 | | -# Only run tests |
43 | | -flow test all |
| 58 | +# Install/update Go tools |
| 59 | +flow install tools |
44 | 60 | ``` |
45 | 61 |
|
46 | | -### Working with generated types |
| 62 | +## Project Structure |
47 | 63 |
|
48 | | -The `flow` project uses [go-jsonschema](github.com/atombender/go-jsonschema) with [go generate](https://blog.golang.org/generate) |
49 | | -to generate Go types from JSON schema files (defined in YAML). If you need to make changes to the generated types |
50 | | -(found in the `types` package), you should update the associated `*schema.yaml` file and run the flow `run generate` executable |
51 | | -or go generate directly. |
| 64 | +``` |
| 65 | +flow/ |
| 66 | +├── .execs/ # Development workflows |
| 67 | +├── cmd/ # CLI entry point |
| 68 | +├── docs/ # Documentation |
| 69 | +├── internal/ # Core application logic |
| 70 | +│ ├── cache/ # Executable and workspace caching logic |
| 71 | +│ ├── context/ # Global application context |
| 72 | +│ ├── io/ # Terminal user interface and I/O |
| 73 | +│ ├── runner/ # Executable execution engine |
| 74 | +│ ├── services/ # Business logic services |
| 75 | +│ ├── templates/ # Templating system for workflows |
| 76 | +│ └── vault/ # Secret management |
| 77 | +├── tests/ # CLI end-to-end test suite |
| 78 | +└── types/ # Generated types from schemas |
| 79 | +``` |
52 | 80 |
|
53 | | -Note that go generate alone does not update generated documentation. |
54 | | -Be sure to regenerate the JSON schema files and markdown documentation before submitting a PR. |
| 81 | +_Some directories are omitted for brevity._ |
55 | 82 |
|
56 | | -### Working with tuikit |
| 83 | +## Working with Generated Code |
57 | 84 |
|
58 | | -The `flow` project uses the [tuikit](tuikit.md) framework for building the terminal UI. |
59 | | -Contributions to the components and helpers in `tuikit` are welcome. |
| 85 | +flow uses code generation extensively: |
| 86 | + |
| 87 | +### Go CLI Type Generation <!-- {docsify-ignore} --> |
| 88 | + |
| 89 | +Types are generated from YAML schemas using [go-jsonschema](https://github.com/atombender/go-jsonschema): |
60 | 90 |
|
61 | | -_You should test all tuikit changes with a local flow build before submitting a PR._ |
62 | | - |
63 | 91 | ```sh |
64 | | - go mod edit -replace github.com/flowexec/tuikit=../tuikit |
| 92 | +# Regenerate types after schema changes |
| 93 | +flow generate cli |
| 94 | +``` |
| 95 | + |
| 96 | +**Important**: When modifying types, edit the `schemas/*.yaml` files, not the generated Go files in `types/`. |
| 97 | + |
| 98 | +### Documentation Generation <!-- {docsify-ignore} --> |
| 99 | + |
| 100 | +CLI and type documentation is generated automatically: |
| 101 | + |
| 102 | +```sh |
| 103 | +# Updates both CLI docs and type reference docs |
| 104 | +flow generate docs |
| 105 | +``` |
| 106 | + |
| 107 | +## TUI Development |
| 108 | + |
| 109 | +flow uses [tuikit](tuikit.md) for terminal interface development: |
| 110 | + |
| 111 | +**Local Development** |
| 112 | + |
| 113 | +```sh |
| 114 | +# Link to local tuikit for development |
| 115 | +go mod edit -replace github.com/flowexec/tuikit=../tuikit |
| 116 | + |
| 117 | +# Test TUI changes |
| 118 | +flow build binary ./bin/flow-dev |
| 119 | +./bin/flow-dev browse |
65 | 120 | ``` |
66 | 121 |
|
67 | 122 | ## Development Tools |
68 | 123 |
|
69 | | -Required tools for development: |
| 124 | +### Required Tools <!-- {docsify-ignore} --> |
| 125 | + |
| 126 | +These are installed automatically by `flow install tools`: |
| 127 | + |
| 128 | +- [mockgen](https://github.com/uber-go/mock) - Generate test mocks |
| 129 | +- [golangci-lint](https://golangci-lint.run/) - Code linting |
| 130 | +- [go-jsonschema](https://github.com/atombender/go-jsonschema) - Generate Go types from YAML schemas |
70 | 131 |
|
71 | | -- [mockgen](https://github.com/uber-go/mock) for generating test mocks |
72 | | -- [golangci-lint](https://golangci-lint.run/) for linting |
| 132 | +### Additional Tools <!-- {docsify-ignore} --> |
73 | 133 |
|
74 | | -Other tools used in the project: |
75 | | -- [goreleaser](https://goreleaser.com/) for releasing the project |
76 | | -- [ginkgo](https://onsi.github.io/ginkgo/) and [gomega](https://onsi.github.io/gomega/) for testing |
| 134 | +- [goreleaser](https://goreleaser.com/) - Release automation |
| 135 | +- [ginkgo](https://onsi.github.io/ginkgo/) - BDD testing framework |
0 commit comments