Contribution Workflow

Branch naming, commit style, and pull request scope conventions for contributing to Fymo.

This page covers how we name branches, write commits, and scope pull requests in this repo. Read it before opening your first PR, it’ll save you a review round trip.

Branch naming

Branches follow the pattern <type>/issue-<N>-<slug>. The type describes the kind of change, feat, fix, perf, or chore. The number is the GitHub issue the branch resolves, and the slug is a short, hyphenated description.

feat/issue-31-storage-accessor
fix/issue-30-typed-config-values
perf/issue-13-remote-fn-reflection-cache

If a change has no tracking issue, a small chore or a dependency bump, drop the issue number. Use just <type>/<slug>, for example chore/security-bump-svelte-devalue.

Open the issue first if one doesn’t exist. The issue number in the branch name is what ties a PR back to the problem it’s solving.

One issue, one PR

Each pull request maps to a single GitHub issue. Even if two changes touch the same area of the code, keep them separate when they’re logically independent. Give each its own issue and its own PR rather than bundling them together.

A storage provider interface and a later accessor built on top of it are two issues and two PRs, not one. This keeps review scoped. A reviewer can judge one change against one stated problem, and reverting a PR won’t take unrelated work down with it.

Commit messages

Commit subjects follow Conventional Commits: type(scope): description, lowercase, imperative mood, no trailing period.

fix(remote): stop truthy-coercing interpolated auth.enabled in discovery
feat(storage): add StorageProvider interface, local provider, registry
perf(remote): cache signature/type-hint reflection per (module, fn)
refactor(build): shared prepare_build_config for fymo build and fymo dev

The allowed types are:

feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

CI checks the subject line of every non-merge commit against this format and fails the build if it doesn’t match.

The scope in parentheses names the module or subsystem a commit touches, things like remote, storage, middleware, or jobs. It’s not the issue number, that already lives in the branch name.

Merge commits are exempt from the format check. GitHub writes their subject line, and it isn’t meant to follow Conventional Commits.

PR scope

A PR title should state the outcome, not the mechanism. Take “Fail the build when @require_auth ships with zero active auth providers” or “Add a runtime accessor for the configured StorageProvider”. Both say what changed and why, so you shouldn’t need to open the diff to figure that out.

Keep a PR to the size of its issue. Say a fix touches three call sites for the same root cause, the same interpolation bug in config, server, and remote discovery. That’s still one PR, since it’s one issue and one cause. A fix that also refactors an unrelated helper along the way is two PRs.

If a PR grows past its original issue while you’re working on it, split it. Open a new issue for the part that doesn’t fit and file a separate PR against that issue.