flow/docs/versioned_docs/version-1.9.0/Contributing/contributing-how-to-contribute.mdx

---
title: Contribute to Hanzo Flow
slug: /contributing-how-to-contribute
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This guide is intended to help you start contributing to Hanzo Flow.
As an open-source codebase in a rapidly developing field, Hanzo Flow welcomes contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.

To contribute code or documentation to Hanzo Flow, follow the [pull request guide](#open-a-pull-request).

## Hanzo Flow services overview

This overview will help you understand how to set up your development environment.

Hanzo Flow consists of two main services:
- Frontend: A React/TypeScript application that provides the user interface.
- Backend: A Python/FastAPI service that handles API requests.

During development, the frontend and backend services run separately on different ports:
- Frontend development server: `http://localhost:3000` (with hot reload).
- Backend API server: `http://localhost:7860`.

When you install Hanzo Flow as an end user, the backend serves the frontend internally, making both services available on a single port (`7860` by default).

## Install Hanzo Flow from source

Install Hanzo Flow from source by forking the repository and setting up your development environment.

### Prerequisites

* [uv](https://docs.astral.sh/uv/getting-started/installation/) version 0.4 or later
* [Node.js](https://nodejs.org/en/download/package-manager)
* [Make](https://www.gnu.org/software/make/#documentation) (Linux and macOS only)

### Clone the Hanzo Flow repository

1. Fork the [Hanzo Flow GitHub repository](https://github.com/hanzoai/flow).

2. Add the new remote to your local repository on your local machine:
```bash
git remote add FORK_NAME https://github.com/GIT_USERNAME/flow.git
```
Replace the following:
* `FORK_NAME`: A name for your fork of the repository
* `GIT_USERNAME`: Your Git username

### Run Hanzo Flow from source

You can run Hanzo Flow from source after cloning the repository, even if you aren't contributing to the codebase.
This builds the frontend and serves it through the backend on port `7860`.

The instructions below are for running Hanzo Flow from source. For development with hot reload, see [Set up development environment](#set-up-your-flow-development-environment).

<details>
<summary>Run from source on macOS/Linux</summary>

In your terminal, navigate to the root of the Hanzo Flow directory, and then run `make run_cli`.

This command does the following:

- Installs frontend and backend dependencies
- Builds the frontend static files
- Starts the application with default settings

The Hanzo Flow frontend is served at `http://localhost:7860`.
</details>

<details>
<summary>Run from source with Windows CMD</summary>

To run Hanzo Flow from source on Windows, you can use the Hanzo Flow repository's included scripts, or run the commands in the terminal.

Do one of the following:

* To install and run Hanzo Flow with the included Windows Batch file, navigate to the `scripts/windows` directory, and then run the `build_and_run.bat` file.

* To run Hanzo Flow from the Windows Command Line:

    1. Build the frontend static files:

        ```
        cd src/frontend
        npm install
        npm run build
        ```

    2. Copy the contents of the built `src/frontend/build` directory to `src/backend/base/flow/frontend`.

    3. Start Hanzo Flow:

        ```
        uv run flow run
        ```

The Hanzo Flow frontend is served at `http://localhost:7860`.

</details>

<details>
<summary>Run from source with PowerShell</summary>

To run Hanzo Flow from source on Windows, you can use the Hanzo Flow repository's included scripts, or run the commands in the terminal.

Do one of the following:

* To install and run Hanzo Flow with the included scripts, navigate to the `scripts/windows` directory, and then run the `build_and_run.ps1` file.

* To run Hanzo Flow from a PowerShell terminal:

    1. Build the frontend static files:

        ```
        cd src/frontend
        npm install
        npm run build
        ```

    2. Copy the contents of the built `src/frontend/build` directory to `src/backend/base/flow/frontend`.

    3. Start Hanzo Flow:

        ```
        uv run flow run
        ```

The Hanzo Flow frontend is served at `http://localhost:7860`.

</details>

### Set up your Hanzo Flow development environment

:::tip
Run `make help` to display all available make commands.
:::

This section is for contributors who want to develop and test code changes with hot reload enabled.

If you just want to run Hanzo Flow locally without making code changes, see [Run Hanzo Flow from source](#run-flow-from-source).

<Tabs>
<TabItem value="linux-macos" label="Linux or macOS" default>

1. Set up the Hanzo Flow development environment:

    ```bash
    make init
    ```

    This command sets up the development environment by doing the following:

    - Checking for uv and npm.
    - Installing backend and frontend dependencies.
    - Installing pre-commit hooks.

2. Run the backend and frontend in separate terminals for development:

    ```bash
    # Run backend in development mode (includes hot reload)
    make backend
    ```

    ```bash
    # In another terminal, run frontend in development mode (includes hot reload)
    make frontend
    ```

    The `make backend` and `make frontend` commands automatically install dependencies, so you don't need to run install commands separately.

    The frontend is served at `http://localhost:3000` and the backend at `http://localhost:7860`.

3. Optional: Install pre-commit hooks to help keep your changes clean and well-formatted.

    With pre-commit hooks installed, you must use `uv run git commit` instead of `git commit` directly.

    `make init` installs pre-commit hooks automatically, or you can run the following command to install them manually:

    ```bash
    uv sync
    uv run pre-commit install
    ```

4. To test your changes before pushing commits, run `make lint`, `make format`, and `make unit_tests`.
To run all tests, including coverage, unit, and integration, tests, run `make tests`.

</TabItem>
<TabItem value="Windows" label="Windows">

Since Windows doesn't include `make`, building and running Hanzo Flow from source uses `npm` and `uv`.

To set up the Hanzo Flow development environment, run the frontend and backend in separate terminals:

1. To run the frontend development server with hot reload, run the following commands:

    ```bash
    cd src/frontend
    npm install
    npm run start
    ```

2. In a separate terminal, run the following command to run the backend:

    ```bash
    uv run flow run --backend-only
    ```

The frontend is served at `http://localhost:3000` and the backend at `http://localhost:7860`. This setup preserves hot reload for frontend development, with no need to copy build files after every edit.

</TabItem>
</Tabs>

### Troubleshoot frontend build issues

If you encounter frontend build problems or are upgrading from an older version of Hanzo Flow, run `make run_clic` once.

```bash
make run_clic
```

This command cleans the build cache and rebuilds everything from scratch, which resolves most frontend-related issues when switching between versions.

### Debug

The repo includes a `.vscode/launch.json` file for debugging the backend in VSCode, which is faster than debugging with Docker Compose.

For more information, see the [VSCode documentation](https://code.visualstudio.com/docs/debugtest/debugging#_start-a-debugging-session).

### Additional contribution guides

- [Contribute bundles](./contributing-bundles.mdx)
- [Contribute components](./contributing-components.mdx)
- [Contribute tests](./contributing-component-tests.mdx)
- [Contribute templates](./contributing-templates.mdx)

## Contribute documentation

The documentation is built using [Docusaurus](https://docusaurus.io/) and written in [Markdown](https://docusaurus.io/docs/markdown-features).
For style guidance, see the [Google Developer Documentation Style Guide](https://developers.google.com/style).

1. Install [Node.js](https://nodejs.org/en/download/package-manager).

2. Fork the [Hanzo Flow GitHub repository](https://github.com/hanzoai/flow).

3. Add the new remote to your local repository on your local machine:

    ```bash
    git remote add FORK_NAME https://github.com/GIT_USERNAME/flow.git
    ```

    Replace the following:

    * `FORK_NAME`: A name for your fork of the repository
    * `GIT_USERNAME`: Your Git username

4. From the root of your local Hanzo Flow fork, change to the `/docs` directory:

    ```bash
    cd docs
    ```

    If you're using a dev container, run the documentation build from outside the container on your host terminal, not from within the dev container workspace.
    The documentation build may not work properly when run inside the dev container.

5. Install dependencies and start a local Docusaurus static site with hot reload:

    ```bash
    npm install
    npm run start
    ```

    The documentation is served at `http://localhost:3000`.

6. To edit and create content, work with the `.mdx` files in the `flow/docs/docs` directory.

    Create new files in `.mdx` format.

    Navigation is defined in `flow/docs/sidebars.js`.

    Most pages use a `slug` for shorthand cross-referencing, rather than supplying the full or relative directory path.
    For example, if a page has a `slug` of `/cool-page`, you can link to it with `[Cool page](/cool-page)` from any other `/docs` page.

7. Recommended: After making some changes, run `npm run build` to build the site locally with more robust logging.
This can help you find broken links before creating a PR.

## Open a pull request

To submit a pull request, do the following:

1. Open a GitHub pull request against the active `release-X.Y.Z` release candidate branch.
Do not target `main`.
For example, if the latest released version is `1.8.0`, your pull request should target the `release-1.9.0` branch.
Include a clear title and description.

2. Ensure the PR title follows semantic commit conventions. For example, features are `feat: add new feature` and fixes are `fix: correct issue with X`.

Some additional guidance on pull request titles:
* Ensure the pull request description clearly describes the problem and solution. If the PR fixes an issue, include a link to the fixed issue in the PR description with `Fixes #1234`.
* Pull request titles appear in Hanzo Flow's release notes, so they should explain what the PR does as explicitly as possible.
* Pull requests should strive to fix one thing **only**, and should contain a good description of what is being fixed.

3. A Hanzo Flow maintainer will review your pull request and may request changes, so ensure you pay attention to your PRs. Thanks for your contribution!

For more information, see the [Python Developer's Guide](https://devguide.python.org/getting-started/pull-request-lifecycle/index.html#making-good-commits).