ferrix/docs/content/docs/development/contributing.md

+++ title = "Contributing" description = "Describes the checks that continuous integration performs, the coding conventions, and how to change the documentation." weight = 3 +++

Continuous Integration Checks

Continuous integration runs the following commands on every push and pull request, and fails on any warning:

cargo fmt --all -- --check
cargo clippy --locked --workspace --all-targets -- -D warnings
cargo test --locked --workspace
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --no-deps --document-private-items
for f in testdata/server.textpb docs/examples/*.textpb; do cargo run --locked -p bgp -- --check "$f"; done
zola --root docs build

It also runs the kernel tests, the interoperability lab, and each fuzz target for 1 minute. See Testing. In local builds, warnings are not treated as errors.

Coding Conventions

• Memory safety. unsafe code is forbidden. The lints are configured in [workspace.lints] in the root Cargo.toml, and every crate inherits them.
• Comments. Each module begins with a comment that describes its purpose and the reasons for its design. Comments on code explain why the code is written as it is, not what it does.
• External input. All input from neighbors, RPKI caches, and the kernel is parsed without panicking, and each parser has a fuzz target. Events that a neighbor can trigger repeatedly are counted in a metric and rate-limited in the log.
• Tests. Tests are located next to the code that they test. Each defect fix includes a test with the input that exposed the defect.
• Configuration validation. The daemon validates the configuration at startup and reports each error with its location.

Adding a Configuration Statement

1. Add the field to crates/server/proto/config.proto, with a comment that describes its effect and default value.
2. Validate the field in crates/server/src/config.rs.
3. Describe the field in docs/content/docs/reference/configuration.md. The test the_configuration_reference_has_every_field fails until the field is described.

Changing the Documentation

The documentation is built with Zola from the docs/ directory:

zola --root docs serve     # http://127.0.0.1:1111, rebuilt on every change
zola --root docs build     # output in docs/public

The documentation follows the conventions in docs/STYLE.md, which are based on the technical documentation of network equipment vendors. In addition:

• Each page is a Markdown file in docs/content/docs/. Each subdirectory is a section in the navigation, and pages are ordered by weight.
• Link to other pages with @/docs/...md paths. Zola verifies these links and their anchors at build time.
• Complete configurations are stored in docs/examples/, validated by continuous integration with bgp --check, and included in pages with {{/* example(name="edge") */}}.
• The theme is in docs/templates and docs/sass. The fonts are in docs/static/fonts. The site does not load resources from other hosts.