Contributing & Reporting Issues

Contributions are welcome — bug reports, feature ideas, and pull requests all help. This page is the user-facing short version. The canonical contributor reference is the repo’s CONTRIBUTING.md, and the architecture is documented in the Developer Guide.

Reporting bugs

A good bug report is reproducible. Please include:

FlowWM version — flow --version.
Windows version (e.g. Windows 11 23H2).
A log file. FlowWM writes a date-stamped log by default:

%USERPROFILE%\.config\flow\logs\flowd-YYYY-MM-DD.log

(one file per day, appended across restarts).

The cleanest way to capture a bug is to reproduce it with an isolated log:
```
flow start --log-file <path>
```
This redirects all logging to <path> and starts the file empty on each launch, so the file contains only that run. Attach that file to the issue.
Config files if relevant (flow.toml, flow-rules.toml) — but redact any personal or sensitive content first.

Raising the log level

To capture more detail, raise the log level by setting RUST_LOG before starting (default is debug in debug builds, info in release):

:: Windows cmd
set RUST_LOG=trace && flow start --log-file <path>

# PowerShell
$env:RUST_LOG='trace'; flow start --log-file <path>

A note on config location

The config directory resolves in this priority order: --config <dir> flag → FLOW_CONFIG_DIR env var → default %USERPROFILE%\.config\flow\. If you override it, the logs/ folder moves with it — mention your config dir in the report.

Where to file: open an issue at https://github.com/CCpcalvin/flow-wm/issues.

Requesting features

Feature requests are welcome too. The roadmap lives at Roadmap — check there first to see whether your idea is already planned or explicitly out of scope. If it isn’t, open an issue and describe the workflow you’re trying to enable, not just the implementation you imagine. “Here’s the friction I hit” is more useful than “add this flag”.

Pull requests

Before opening a PR, make sure the basics are green:

cargo fmt
cargo clippy --all-targets
cargo test

A few project-wide conventions:

Document public items. #![warn(missing_docs)] is enabled in src/lib.rs, so every public item needs at least a one-line /// doc comment.
Config changes must update two places. Default values live in the Default impls in src/config/types.rs (the single source of truth). If you add or change a field, also update default-config.toml — the default_config_toml_matches_compiled_defaults test enforces that they stay in sync.
Adding dependencies: use cargo add <crate> rather than hand-editing Cargo.toml, so versions and the lockfile stay consistent.

For the full conventions (including the 3-layer documentation model and contributor gates), see CONTRIBUTING.md in the repo root.

Understanding the codebase

For architecture, threading, the layout engine, and subsystem write-ups, see the Developer Guide. Build it locally:

mdbook build docs/

The Building from Source page covers prerequisites, MSVC setup, and the contributor gates in detail.

Keyboard shortcuts