Community / Contributing

Contributing to Ferrum Edge

We welcome contributions of all kinds — bug fixes, new features, documentation improvements, and plugin development.

Welcome, Contributor!

Ferrum Edge is built on the principle that performance and safety aren't at odds with maintainability. We aim to keep the codebase clean, well-tested, and approachable. Whether you're fixing a typo in the docs or implementing a new plugin, we appreciate the effort.

Before diving in, please read through this guide. It'll save you (and us) time.

Development Setup

Install Rust 1.85+

bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustup update stable
rustc --version  # should be 1.85 or newer

Install protoc

bash

# macOS
brew install protobuf

# Ubuntu/Debian
sudo apt-get install -y protobuf-compiler

# Verify
protoc --version

Fork & Clone

bash

# Fork the repo on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/ferrum-edge.git
cd ferrum-edge
git remote add upstream https://github.com/ferrum-edge/ferrum-edge.git

Build & Test

bash

cargo build
cargo test --test unit_tests
cargo test --test integration_tests
cargo clippy --all-targets -- -D warnings

Contribution Workflow

Create a Branch

Branch from main. Use the naming convention below.

bash

# Feature branches
git checkout -b feature/add-oauth2-plugin

# Bug fixes
git checkout -b fix/rate-limiter-edge-case

# Documentation
git checkout -b docs/improve-kubernetes-guide

Write Code & Tests

Follow the code standards below. Every new feature should include unit tests. Plugins should include integration tests.

Run the Full Test Suite

bash

cargo test
cargo test -- --ignored
cargo clippy --all-targets -- -D warnings
cargo fmt --check

Submit a Pull Request

Push your branch and open a PR against main. Fill out the PR template. One of the maintainers will review within a few business days.

Commit Message Convention

We use Conventional Commits. This enables automatic changelog generation and semantic versioning.

text — format

<type>(<scope>): <short description>

[optional body]

[optional footer]

Type	When to Use	Example
`feat`	New feature	`feat(plugins): add oauth2_auth plugin`
`fix`	Bug fix	`fix(rate_limiting): handle clock skew in token bucket`
`docs`	Documentation only	`docs(kubernetes): add HPA configuration example`
`perf`	Performance improvement	`perf(routing): replace Vec with DashMap for O(1) lookup`
`refactor`	Code cleanup, no behavior change	`refactor(proxy): extract connection pool to separate module`
`test`	Test additions or fixes	`test(jwt_auth): add edge cases for expired tokens`
`chore`	Build, CI, dependencies	`chore(deps): update tokio to 1.36`

Code Standards

Lock-Free Hot Paths

Never introduce a Mutex on a code path that executes per-request. Use ArcSwap, AtomicX, or DashMap instead. If you need a lock, document why it's acceptable and ensure it's held for microseconds, not milliseconds.

Result Types

Use Result<T, Error> everywhere. Never unwrap() or expect() in production code paths. Panics in an async context kill the whole task.

No Panics in Production

Panics are acceptable in tests and startup validation. Never in request handling code. Use the ? operator and propagate errors gracefully.

Rust Edition 2024

The codebase targets Rust Edition 2024. Use modern idioms: async/await, pattern matching, and iterator chains over manual loops.

Clippy Compliance

All code must pass cargo clippy --all-targets -- -D warnings. No clippy warnings allowed in merged code. Check before opening a PR.

Formatting

Run cargo fmt before committing. The CI will reject non-formatted code. We use default rustfmt settings.

Adding a New Plugin

Read the Custom Plugins guide first.
See CUSTOM_PLUGINS.md for the full plugin development guide.
Add unit tests and integration tests for your plugin.
Document config options with inline doc comments (///) on public APIs.
Open an issue first for significant features to discuss the design with maintainers.

Code Review Process

All contributions go through code review before merging. Here's what to expect:

Reviewer will check for correctness, performance, and adherence to standards
Automated CI must pass (build, test, clippy, fmt)
Performance-sensitive changes may request benchmark results
Security-related changes (auth plugins, TLS) get additional scrutiny
We aim to respond to PRs within 3 business days

Community & Support

🐞 GitHub Issues

Bug reports and feature requests. Use the issue templates.

Open Issue

💬 GitHub Discussions

Questions, ideas, and community conversation.

Discussions

💌 Discord (Coming Soon)

Real-time community chat. Join us when we launch.

Coming Soon