Thank you for your interest in contributing to FerrisKey! 🦀
FerrisKey is an open-source Identity and Access Management (IAM) system written in Rust and React. We welcome contributions from anyone willing to help improve it.
- 📖 Read the FerrisKey Docs
- 🐞 Look at the open issues
- 💬 Join discussions on Discord
- 📝 Check our GOVERNANCE.md
We use GitHub pull requests for code review.
Prerequisites:
- Fork the repository
- Install pre-commit
npm install -g pnpm
pre-commit install
cd front
pnpm install- Create a branch (
feat/...,fix/...,docs/...) - Implement your changes
- Run tests with
cargo test - Open a PR and fill in the description
Make sure to follow Rust best practices, and try to include unit tests when relevant.
Ferris key uses feature flags to enable experimental features. For now they are only available on the frontend.
To enable a feature, add the following to your .env file at /front :
VITE_FEATURES="realm-settings"To look for the features in the code, please refer to the lib/features.ts file.
FerrisKey is built with a clean architecture mindset.
Each layer has a clear responsibility:
core-> domain & business logicapi-> transport & HTTP concernsfront-> user interfaceoperator-> deployment & infrastructure
We expect pull requests to respect this separation.
A Pull Request must:
- Address one concern
- Modify one architectural layer whenever possible
- Be small enough to review in < 20 minutes
✅ Good Examples
- Add PKCE validation in
core - Add
/introspectroute inapi - Add TOTP setup UI in
front - Fix SQL constraint in
corerepository
❌ Bad Examples
- Add PKCE support + modify DB schema + update frontend + refactor token logic
- "Refactor OAuth + improve performance + fix tests"
If your change touches multiples layers: ➡️ Split it into multiple PRs
Prefer:
PR 1 → Core: Add domain support
PR 2 → API: Expose route using new domain feature
PR 3 → Frontend: UI integration
Instead of:
❌ One massive PR touching core + api + frontend
A PR will likely be refused if:
- It changes too many files
- It mixes refactor + feature
- It introduces unrelated formatting changes
- It includes multiple features
Rule of thumb:
If your PR title needs “and”, it should probably be split.
Before opening a PR, ask yourself:
- Can someone understand this in 10–20 minutes?
- Does it introduce hidden side effects?
- Is it scoped clearly?
If not → split.
We reserve the right to reject PRs that:
- Break architectural boundaries
- Mix domain and transport logic
- Introduce large unscoped refactors
- Bundle multiple responsibilities
Even if the code works.
We encourage:
- Small commits
- Clear commit messages
- Conventional commit style (recommended)
For large changes, open an issue first and discuss the proposal with the maintainers. We may ask you to write an RFC if it's an architectural change.
- Rust:
rustfmtandclippy - Frontend: TypeScript + Prettier
- Use meaningful commit messages (see Conventional Commits)
All contributions must be made under the Apache 2.0 License.
By submitting code, you agree to license it under this license.
Thanks for contributing to FerrisKey!