Contributing

Watchfire is open source under Apache-2.0, and contributions of every size are appreciated — a typo fix, a sharper sentence in the docs, a reproducible bug report, or a fully-baked feature PR. If you've used Watchfire enough to notice something off, you already have everything you need to contribute.

Ways to contribute

You don't have to write Go to help out. Pick whichever of these fits the energy you have today:

• Report a bug — open an issue from the bug report template. Steps to reproduce + what you expected to happen are enough.
• Suggest a feature — start a thread in GitHub Discussions so the idea can be shaped before it becomes an issue.
• Improve the docs — every page on this site has an "Edit this page on GitHub" link in the right sidebar that drops you straight into the MDX source on GitHub. The docs live in the website repo under content/docs/.
• Write code — the good first issue label marks issues that are scoped small enough to land without deep daemon knowledge. The help wanted label is the next step up.
• Help others — answering a question in Discussions or triaging a stale issue is just as load-bearing as code.

Code contribution workflow

Quick version of the flow — for the canonical version see CONTRIBUTING.md in the repo:

1. Fork watchfire-io/watchfire and clone your fork locally.
2. Branch off main: git checkout -b my-feature.
3. Change the code, run make test and make lint, commit with a meaningful message.
4. Push the branch to your fork.
5. Open a PR against main. Fill out the PR template, link the issue if there is one, and request review.

Development setup

Watchfire is written in Go. To build it from source you need:

• Go 1.23+
• Make
• Protocol Buffers compiler (protoc)

The three Make targets that cover day-to-day work:

make build   # Build daemon + CLI into ./build/
make test    # Run the test suite
make lint    # Run golangci-lint

For the rest — installing dev tools, running the daemon under air, generating protobuf code, packaging — see the CONTRIBUTING.md and the Makefile in the repo. The Installation page also has a short build-from-source block aimed at users rather than contributors.

Code guidelines

• Run gofmt (or goimports) before committing.
• Keep functions focused and small; favour readability over cleverness.
• Write meaningful commit messages — explain the why, not just the what.
• Add tests for new functionality, especially anything touching the daemon or the agent runner.
• make lint must pass before you open a PR.

Website performance budget

The marketing and docs site (this site, in the website repo) has a small set of performance targets. They are targets, not promises — measured at build time on a production build, and they will drift slowly as the site grows.

Surface	Target
Landing page (/) initial JS	≤ 210 KB gzipped (≤ 700 KB raw)
Long doc page (e.g. /docs/changelog) initial JS	≤ 260 KB gzipped (≤ 830 KB raw)
Largest Contentful Paint on /	< 2.5 s on simulated Slow 4G
Cumulative Layout Shift on /, /docs, /docs/recipes	< 0.05
Public PNG screenshots	None — use WebP via <img> with explicit width and height

Run npm run perf from the website repo to print the per-route initial JS payload from a clean production build. The script wraps next build, boots the production server, and tallies the unique /_next/static/chunks/*.js files referenced by each route's HTML — so adding a new client component, eagerly importing a heavy library, or swapping a server component for a client one will surface in the diff.

When working on the site:

• Keep components server-rendered by default. Reach for "use client" only when you need state, effects, or browser APIs.
• Defer heavy client components below the fold with next/dynamic (ssr: false if no SEO content depends on the component).
• New images go in public/ as WebP, referenced via <img> (or next/image) with explicit width and height to keep CLS at zero.
• Wrap any new continuous animation in a @media (prefers-reduced-motion: reduce) opt-out.
• The site has no runtime dependencies beyond what's in package.json today. If you genuinely need a build-time tool to measure or analyze, add it as a devDependency only and call it out in the PR description.

Code of Conduct

Watchfire follows the Contributor Covenant v2.1. The pledge in one sentence:

We as members, contributors, and leaders pledge to make participation in our community a positive experience for everyone, regardless of background or identity.

Conduct concerns can be reported privately to info@watchfire.io.

Community

Watchfire's project conversations happen on GitHub:

• GitHub Issues — bug reports and tracked work.
• GitHub Discussions — open-ended questions, design conversations, and Q&A.

There is no Discord, Slack, or mailing list yet. If those become useful they'll be linked from this page.

Where to find me

Watchfire is primarily authored by Nuno Coração. Every PR opened against the repo gets a response — even a small one — so don't worry about whether your change is "big enough." If something is blocking you, ping the PR or open a discussion and it will get picked up.