How We Work

Before you open a PR

• Check the issue tracker first. If you’re building something without an issue, open one. Even a quick “I’m going to work on X” helps avoid duplicate effort.
• One feature per PR. Don’t bundle a firewall fix, a sidebar tweak, and a new DHCP field into one PR. Smaller PRs get reviewed faster.
• Branch from main. Name your branch descriptively: feat/openvpn-support, fix/nat-modal-width

What a good PR looks like

• Title: Use conventional commit style. feat: add OpenVPN server configuration
• Description: Explain what you changed and why. Include screenshots for UI changes.
• Testing: Say what you tested. “Tested on VyOS 1.4 and 1.5” or “Verified with 3 DHCP pools and 15 static mappings.”
• Scope: If your PR touches more than ~400 lines of meaningful code, consider splitting it.

Review process

• Every PR needs at least one review before merge
• Maintainers aim for initial review within 48 hours. If it’s taking longer, ping in Discord
• Review comments are suggestions, not commands. Disagree? Say so and explain your reasoning
• Once approved, the author merges. You wrote it, you ship it

Commit messages

We use conventional commits. This generates our changelog and keeps git history readable.

The three-layer pattern

Every VyOS configuration feature follows the same structure. Don’t invent a new pattern — follow the existing one:

Mappers have v1.4 and v1.5 implementations. Every feature exposes a /capabilities endpoint so the frontend knows what’s available.

Frontend conventions

• Components in src/components/{feature}/. One directory per feature area.
• Use shadcn/ui components. Don’t pull in new UI libraries without discussion.
• All new layouts must be responsive. Tables with 4+ columns need a horizontal scroll wrapper.
• Zustand for global state, React state for local UI state.

Backend conventions

• Routers in routers/{feature}/, builders in vyos_builders/{feature}/, mappers in vyos_mappers/{feature}/
• RBAC permission decorators on every endpoint. No unprotected configuration endpoints.
• Async everywhere. Sensitive data encrypted at rest.

Database changes

• All schema changes through Prisma migrations. Never edit an applied migration.
• Include migrations in your PR. Think about the upgrade path.

How we prioritize

1. Bugs that break existing functionality — always top priority
2. Work that unblocks other work — if three people are waiting, it comes first
3. Features with community demand — issues with reactions, Discord requests, real deployments
4. Technical debt slowing us down — patterns causing repeated bugs

How we communicate

Claiming work

Comment on the issue to claim it. If your plans change, update the issue so someone else can take it. If an issue has been claimed with no activity for two weeks, it’s fair game. No hard feelings.

Decision making

For day-to-day decisions, the person doing the work decides. For larger decisions — new dependencies, architecture changes, schema redesigns — open a GitHub Discussion first. Maintainers have final say, but the goal is consensus.