|
| 1 | +# Contributing to VyManager |
| 2 | + |
| 3 | +**Thanks for contributing! This document explains how we work so we can move fast without breaking things.** |
| 4 | + |
| 5 | +**[Development setup instructions](https://github.com/Community-VyProjects/VyManager?tab=readme-ov-file#development-setup)** |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## Pull Requests |
| 10 | + |
| 11 | +### Before you open a PR |
| 12 | + |
| 13 | +- **Check the issue tracker first.** If you're building something that doesn't have an issue yet, open one. Even a quick "I'm going to work on X" issue helps avoid duplicate effort and gives others a chance to weigh in on approach before you write code. |
| 14 | +- **One feature per PR.** Don't bundle a firewall fix, a sidebar tweak, and a new DHCP field into one PR. Keep them separate. Smaller PRs get reviewed faster and are easier to roll back if something goes wrong. |
| 15 | +- **Branch from `main`.** Name your branch something descriptive: `feat/openvpn-support`, `fix/nat-modal-width`, `refactor/sidebar-responsive`. Not `my-changes` or `update`. |
| 16 | + |
| 17 | +### What a good PR looks like |
| 18 | + |
| 19 | +**Title:** Use conventional commit style. `feat: add OpenVPN server configuration`, `fix: NAT modal overflow on mobile`, `refactor: extract shared table scroll wrapper`. This keeps the changelog readable. |
| 20 | + |
| 21 | +**Description:** Explain what you changed and why. Not a novel — a few sentences is fine. If it's a UI change, include a screenshot or short recording. If it changes behavior, say what the old behavior was and what the new behavior is. |
| 22 | + |
| 23 | +**Testing:** Say what you tested. "Tested on VyOS 1.4 and 1.5" or "Tested on desktop and mobile" or "Verified with 3 DHCP pools and 15 static mappings." We don't have automated E2E tests yet, so manual testing notes are how we maintain quality. |
| 24 | + |
| 25 | +**Scope:** If your PR touches more than ~400 lines of meaningful code (not counting generated files), consider whether it can be broken into smaller PRs. Large PRs sit in review longer and are harder to reason about. |
| 26 | + |
| 27 | +### Review process |
| 28 | + |
| 29 | +- Every PR needs at least one review before merge. |
| 30 | +- Maintainers aim to do initial review within 48 hours. If it's taking longer, ping in Discord — it probably just got buried. |
| 31 | +- Review comments are suggestions, not commands. If you disagree, say so and explain your reasoning. We're all learning. |
| 32 | +- Don't take review personally. A "this could be simpler" comment is about the code, not about you. |
| 33 | +- Once approved, the author merges. |
| 34 | + |
| 35 | +### What will get a PR sent back |
| 36 | + |
| 37 | +- No description or testing notes |
| 38 | +- Multiple unrelated changes bundled together |
| 39 | +- Breaking changes to the database schema without a migration |
| 40 | +- Hardcoded values that should be configurable |
| 41 | +- New features that only work on one VyOS version when both are feasible |
| 42 | +- UI changes that break mobile responsiveness (once we have it) |
| 43 | +- Skipping the capability endpoint pattern for version-aware features |
| 44 | + |
| 45 | +### Commit messages |
| 46 | + |
| 47 | +We use conventional commits. This isn't bureaucracy — it's what generates our changelog and helps us understand the git history six months from now. |
| 48 | + |
| 49 | +- `feat:` — new feature or capability |
| 50 | +- `fix:` — bug fix |
| 51 | +- `refactor:` — code restructuring without behavior change |
| 52 | +- `docs:` — documentation only |
| 53 | +- `chore:` — build, CI, dependency updates |
| 54 | +- `style:` — formatting, whitespace, no logic change |
| 55 | + |
| 56 | +Squash your commits before merging if you have a messy history. The merge commit should tell a clean story. |
| 57 | + |
| 58 | +--- |
| 59 | + |
| 60 | +## Architecture & Code Guidelines |
| 61 | + |
| 62 | +### The three-layer pattern |
| 63 | + |
| 64 | +Every VyOS configuration feature follows the same structure. Don't invent a new pattern — follow the existing one: |
| 65 | + |
| 66 | +**Router** (API endpoint) → **Builder** (batch operations) → **Mapper** (version-specific VyOS commands) |
| 67 | + |
| 68 | +Mappers have v1.4 and v1.5 implementations. The router calls the builder, the builder calls the mapper, the mapper returns the actual VyOS CLI paths. Every feature exposes a `/capabilities` endpoint so the frontend knows what's available for the connected version. |
| 69 | + |
| 70 | +If you're adding a new feature, look at an existing one that's similar in complexity and follow its structure. The firewall module is a good reference for complex features. The dummy interface module is a good reference for simple ones. |
| 71 | + |
| 72 | +### Frontend conventions |
| 73 | + |
| 74 | +- Components live in `src/components/{feature}/`. One directory per feature area. |
| 75 | +- API client functions live in `src/lib/api/{feature}.ts`. |
| 76 | +- Every modal should have a create, edit, and delete variant. |
| 77 | +- Use shadcn/ui components. Don't pull in new UI libraries without discussing it first. |
| 78 | +- All new layouts must be responsive. Use Tailwind breakpoints (`sm:`, `md:`, `lg:`, `xl:`). If a table has more than 4 columns, it needs a horizontal scroll wrapper. |
| 79 | +- State management through Zustand stores for global state, React state for local UI state. |
| 80 | + |
| 81 | +### Backend conventions |
| 82 | + |
| 83 | +- Routers go in `routers/{feature}/`. |
| 84 | +- Builders go in `vyos_builders/{feature}/`. |
| 85 | +- Mappers go in `vyos_mappers/{feature}/` with version subdirectories. |
| 86 | +- Use the RBAC permission decorators on every endpoint. No unprotected configuration endpoints. |
| 87 | +- Async everywhere. No blocking calls. |
| 88 | +- Sensitive data (API keys, SSH keys, passwords) must be encrypted at rest using the existing encryption utilities. |
| 89 | + |
| 90 | +### Database changes |
| 91 | + |
| 92 | +- All schema changes go through Prisma migrations. |
| 93 | +- Never edit a migration that's already been applied in production. Create a new one. |
| 94 | +- If your feature needs new tables or columns, include the migration in your PR. |
| 95 | +- Think about the upgrade path. Someone running the previous version should be able to run `prisma migrate deploy` and have everything work without manual steps. |
| 96 | + |
| 97 | +--- |
0 commit comments