COMMUNITY

Contributing to Floww

How to contribute code, report issues, and help improve Floww.

Floww is an open project and contributions are welcome. Whether you're fixing a typo, reporting a bug, or building a major feature, this guide will help you get started.

Getting Started

1. Fork the repository — go to the Floww GitHub page and click "Fork" to create your own copy.
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/floww.git
   cd floww

3. Add the upstream remote so you can pull future changes:

   git remote add upstream https://github.com/floww-app/floww.git

4. Create a branch for your work. Use a descriptive name:

   # Feature
   git checkout -b feat/add-csv-export-node
   
   # Bug fix
   git checkout -b fix/edge-rendering-on-zoom
   
   # Documentation
   git checkout -b docs/update-plugin-guide

Branch naming convention

Prefix	Use for	Example
feat/	New features and capabilities	feat/add-slack-node
fix/	Bug fixes	fix/variable-resolve-crash
docs/	Documentation changes	docs/update-api-reference
refactor/	Code restructuring (no behavior change)	refactor/canvas-renderer
test/	Adding or fixing tests	test/node-execution-lifecycle
chore/	Build scripts, CI, dependencies	chore/upgrade-electron

Repository Structure

Here is a high-level overview of the Floww repository:

floww/
  src/
    main/               # Shell process (Electron/Tauri)
      ipc.js            # IPC handlers
      menu.js           # Native menu definitions
      window.js         # Window management
    renderer/           # Renderer process
      canvas/           # Canvas engine (wires, viewport, spatial index)
      nodes/            # Built-in node definitions
      ui/               # UI components (panels, dialogs, palette)
      runtime/          # Execution runtime (scheduler, state machine)
      themes/           # Built-in themes
    shared/             # Code shared between main and renderer
      file-format.js    # .floww file parser and serializer
      types.js          # Shared type definitions
  plugins/              # Bundled plugins
  test/                 # Test suites
    unit/               # Unit tests
    integration/        # Integration tests
    fixtures/           # Test .floww files and mock data
  scripts/              # Build and release scripts
  docs/                 # Documentation site (this site)
  package.json
  floww.config.js       # Build configuration

Development Setup

Prerequisites

• Node.js 18 or later
• npm 9 or later (ships with Node.js)
• Git 2.30 or later
• Linux only: libwebkit2gtk-4.1-dev and libgtk-3-dev for the Tauri shell

Install dependencies

npm install

Run the dev server

# Start Floww in development mode with hot reload
npm run dev

# Run only the renderer (in a browser, without the shell)
npm run dev:renderer

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint and format
npm run lint
npm run format

Coding Style

Floww uses consistent coding conventions enforced by ESLint and Prettier. The linter runs automatically as a pre-commit hook, so you will be alerted to issues before they are committed.

Formatting rules

• Indentation — 2 spaces, no tabs.
• Semicolons — always. const x = 1;
• Quotes — single quotes for strings. 'hello'
• Trailing commas — yes, in multi-line structures.
• Line length — 100 characters maximum.
• Braces — always, even for single-line if statements.

Naming conventions

Type	Convention	Example
Variables, functions	camelCase	getNodeById
Classes	PascalCase	CanvasRenderer
Constants	UPPER_SNAKE_CASE	MAX_ZOOM_LEVEL
File names	kebab-case	canvas-renderer.js
CSS classes	BEM-style	.node__header--active
Events	namespace:action	node:executed

Commit messages

Use Conventional Commits format:

feat: add streaming support for Ollama nodes
fix: resolve cycle detection in nested groups
docs: update plugin API reference
refactor: simplify canvas viewport calculations
test: add integration tests for workflow execution

Comments

• Use JSDoc comments for all exported functions and classes.
• Inline comments should explain why, not what. The code itself should be clear about what it does.
• Mark temporary workarounds with // TODO: or // HACK: and include a tracking issue number.

Pull Request Process

When your changes are ready, push your branch and open a pull request against the main branch.

PR checklist

Every pull request should include:

• A clear title that describes the change (e.g., "Add CSV export node" not "Update code").
• A description explaining what changed and why.
• A link to a related issue (if applicable).
• Tests for any new functionality or bug fixes.
• No unrelated changes (keep PRs focused on a single concern).

PR description template

## What
Brief description of the change.

## Why
Motivation — what problem does this solve?

## How
Implementation approach and key decisions.

## Testing
How you tested the change. Include screenshots for UI changes.

## Related
Links to related issues: Closes #123

Review criteria

Reviewers will evaluate your PR against these criteria:

1. Correctness — does it work? Do tests pass?
2. Code quality — is it readable, well-structured, and consistent with the codebase?
3. Test coverage — are there sufficient tests for the changes?
4. Performance — does it avoid unnecessary re-renders, allocations, or computation?
5. Backwards compatibility — does it break existing workflows or plugin APIs?

CI checks

The following checks run automatically on every PR:

Check	Must pass	Description
Lint	Yes	ESLint with the project config
Unit tests	Yes	All unit tests in test/unit/
Integration tests	Yes	End-to-end workflow execution tests
Build	Yes	Production build completes without errors
Bundle size	Warning only	Flags if the bundle size increases significantly

Issue Guidelines

Good issue reports help us fix problems faster. Please follow these guidelines when opening issues.

Bug reports

Include the following in every bug report:

• Summary — one-sentence description of the problem.
• Steps to reproduce — numbered steps to trigger the bug.
• Expected behavior — what should happen.
• Actual behavior — what actually happens (include error messages, screenshots).
• Environment — Floww version, OS, Node.js version.
• Workflow file — attach a minimal .floww file that reproduces the issue (if applicable).

Feature requests

• Problem statement — describe the problem you are trying to solve.
• Proposed solution — describe your ideal solution.
• Alternatives — mention any workarounds you have considered.
• Use case — explain how this would be used in practice.

Labels

Maintainers will triage and label issues. Common labels include:

Label	Meaning
bug	Confirmed bug
enhancement	Feature request or improvement
good first issue	Suitable for new contributors
help wanted	Maintainers welcome community contributions
documentation	Documentation improvements
won't fix	Out of scope or by design
duplicate	Already reported
needs-info	More information needed from the reporter

Code of Conduct

The Floww community is committed to providing a welcoming and inclusive environment for everyone. We expect all participants to follow these principles:

• Be respectful. Treat everyone with dignity and consideration. Disagreements about code are fine; personal attacks are not.
• Be inclusive. Welcome people of all backgrounds, experience levels, and perspectives. Avoid language that excludes or marginalizes.
• Be constructive. Provide actionable feedback. When reviewing code, explain the reasoning behind your suggestions. When receiving feedback, assume good intent.
• Be patient. Maintainers and contributors are often volunteers. Response times may vary.
• Be collaborative. Share knowledge, help others learn, and celebrate contributions of all sizes — from major features to documentation fixes.

Harassment, discrimination, and disruptive behavior will not be tolerated. Violations should be reported to the maintainers at conduct@floww.pro. All reports are reviewed confidentially.

By participating in this project, you agree to abide by these principles and help maintain a positive, productive community.