Start here

Features start with a specification: a document that describes the expected behavior and how to tell whether it works.

SpecDoc is where we draft, discuss and approve specs. Approved specs are published to netfyr/specs. Code changes go to the repository that implements them, such as netfyr/netfyr for the core.

  • Implement an existing feature: use the planning page to find work. Read its published spec, check that its dependencies are implemented, and coordinate with the assigned implementer or, if nobody is assigned, the spec owner.
  • Propose or change behavior: read Spec format, then create or revise a proposal in SpecDoc. The lifecycle below explains how it reaches implementation.
  • Fix a bug or improve documentation: start with the relevant repository's issue or PR discussion. For a bug, describe the expected behavior and provide a reproducer. You can also contribute by reviewing a spec in SpecDoc.

Before writing a spec or code, read the project philosophy and the target repository's contribution guide. For core, use Contributing to netfyr, then follow Working on code for local setup.

Spec format

SpecDoc offers two templates when you create a spec: a feature spec for a bounded piece of behavior, and a top-level spec for rules that apply across features.

Feature specs

Feature specs use GitHub Spec Kit's feature specification format, adapted for SpecDoc. Start with the board's template. Open with the problem, scope and exclusions, and record feature dependencies in depends-on. The main sections cover:

  • Prioritized user stories, each with an independent test and Given / When / Then acceptance scenarios. Cover errors and edge cases.
  • Specific requirements with stable FR-nnn IDs, and the entities or data the feature needs.
  • Measurable success criteria with SC-nnn IDs, plus assumptions that affect the expected behavior.

Keep implementation task lists and review transcripts out of the published spec. Its requirements should remain useful after the feature ships.

Top-level specs

Top-level specs act as the project's constitution. They define shared rules for architecture, compatibility, design and other concerns. Feature specs inherit them without a depends-on entry. Give each rule a stable ID, explain why it exists and state where it applies.

Aim to make these rules enforceable by deterministic checks: schemas, dependency checks, static analysis or tests with a defined pass or fail result. Name the check for each rule where one exists. If enforcement still depends on human judgment or a check has not been implemented, say so.

For example, a rule about layer boundaries can name forbidden crate dependencies and link to the check that rejects them. Reviewers still need to assess whether responsibilities sit in the right layer. An LLM review can help find conflicts; it does not establish compliance.

Development lifecycle

Feature lifecycle
  1. Draft spec
  2. Review and approve
  3. Bot publication
  4. Implement and test
  5. Review and merge code
  6. Implemented

Requirements changed during implementation? Revise the spec and repeat review.

  1. Propose the behavior

    Ask a maintainer in the relevant GitHub issue or PR to add your account to the contributor inventory. This is required before SpecDoc can publish your specs or run review automation on them.

    Create a spec using the appropriate template, or revise the existing spec if its scope already covers the change. Approved specs are locked; ask the owner shown in the spec header to reopen one for revision.

  2. Review and approve the spec

    Move the draft to ready for review. Use inline comments for specific passages and the editor's Discussion panel for questions about the whole spec. Resolve inline threads and accept or reject suggestions before approving. Authorized approvers approve through the editor controls; later changes to the spec or its review policy need fresh approvals.

    General discussion threads block publication until they are resolved.

    Once approval and discussion checks pass, SpecDoc opens a publication PR in netfyr/specs. SpecDoc merges it after the required repository checks pass. Spec content is reviewed in SpecDoc; contributors do not edit the published files or repeat the review in GitHub.

  3. Implement and verify

    Work against the merged requirements and implemented dependencies. Keep each feature PR focused on one governing spec. Build in reviewable increments, map tests to acceptance scenarios, and report a missing dependency instead of silently taking over its implementation.

  4. Review and merge the code

    Follow Submitting a change, address review findings, and preserve the spec references when merging so the resulting history records what shipped.

  5. Record completion

    When the completing commit reaches a configured implementation repository's default branch, SpecDoc detects its implements reference and marks the feature implemented. Partial work does not claim completion. Top-level principles remain approved; they are not closed as implemented.

    If implementation reveals a requirement that needs changing, revise the spec through review. Corrections retain its identity and path; a replacement spec records what it supersedes.

    Update affected user documentation and review any documentation follow-up linked from the implementation PR.

Open History in the editor to read saved revisions and compare each with the previous one. For changes since your approval, open the board's changes view. Discussion includes approval activity alongside the threads. Spec checkpoints tag the merged specs at a fixed Git revision for a shared baseline.

Agents and automation

Reviewing a draft
When configured, SpecDoc's LLM review bots check drafts for unclear requirements, missing decisions and contradictions with approved top-level principles or selected related specs. They leave comments in the editor. Advisory cross-spec findings use one shared thread in both specs' Discussion panels, with the same replies and resolution.
Reconciling specs
A configured bot's checkpoint consistency review can flag duplicated responsibilities and incompatible requirements across approved specs. Findings use the same shared threads as draft reviews. An agent can compare the cited requirements and draft a reconciliation. Agree which behavior should govern, then review changes to each affected spec. Resolving the shared thread requires permission on both specs. Record dependencies and replacements explicitly. When moving a requirement, check that the receiving spec actually covers it before retiring the old text.
Context for coding agents
The SpecDoc CLI and MCP adapter provide spec lookup and pinned task context for coding agents. A task can select its governing requirements, inherited rules and dependencies at fixed Git revisions. Agent-assisted changes follow the same review and contribution rules.
Learning from implementation review
A configured feedback bot reads a linked, merged implementation PR's discussion and final changes, then proposes spec amendments in the editor. Accept or reject the suggestions through review. A code bug that violates a clear requirement calls for a code fix.
Updating user documentation
SpecDoc's documentation bot checks PRs merged into the default branches of core, TUI and Cockpit, with or without a spec reference. When selected user guides need an update, it opens a PR in the configured documentation repository, currently netfyr/docs, and comments a link on the source PR for its author to review. The bot does not merge documentation PRs.
Routine automation

Repository hooks and CI run the checks configured for that repository.

SpecDoc opens and merges publication PRs in netfyr/specs after approval, discussion and repository checks pass.

SpecDoc tracks implementation through merged Git references.

Working on code

For core development, use Linux, Git, a Rust toolchain supporting Rust 2024, and Make. Install pre-commit before setting up the repository hooks. Test-specific system dependencies are documented with their suites.

git clone https://github.com/netfyr/netfyr.git
cd netfyr
cargo build
make hooks

The core hooks check formatting on commits touching Rust and run Clippy before pushes touching Rust.

  • Use cargo fmt and keep Clippy clean. New crates inherit the workspace's shared metadata.
  • Prefer standard-library solutions. Justify external dependencies in manifest comments. For low-level networking, check the rust-netlink ecosystem, including rtnetlink, and Nispor before adding custom code, and explain any concrete API gap.
  • For user-facing work, consult the design library and project identity. Cite the applicable design rules and reuse shared components where available.

A requirement mismatch needs an explicit decision: correct the implementation or propose a spec revision. Keep unrelated cleanup in separate work.

Testing and evidence

Before submitting core changes, run the checks required by its contribution guide:

cargo test
make test
cargo fmt --check
make clippy

For focused shell checks, make test TAGS=build,meta selects either tag; make test TAGS=meta+policy requires both. A focused run does not replace the full pre-submission checks.

Pure logic
Place Rust unit tests beside the code in #[cfg(test)] modules. They should not need external tools, network namespaces, or built binaries.
CLI and system behavior
Shell tests live in tests/. Name them for the behavior, put tags within the first ten lines, keep helpers in tests/lib/, and locate built binaries through NETFYR_TARGET_DIR.
Regressions
Reproduce the bug with a test that fails for the reported behavior before applying the fix. Verify that it passes afterward. A compile failure does not reproduce a behavior bug.
Network changes
Verify results against the real kernel. The testing infrastructure spec defines pytest acceptance tiers and independent observations. Privileged candidate execution belongs in a disposable VM, with an outer snapshot and evidence retained outside the guest. Follow the suite instructions in the branch being tested.

Missing prerequisites must fail visibly. Share the exact commands, revision, environment, results, and any checks you could not run separately in chat or review evidence. A merged testing spec describes required behavior; it does not mean every harness is already available on the default branch.

Submitting a change

Use imperative commit subjects and explain why the change is needed. Each commit should be one reviewable increment. The pull request should explain the problem, resulting behavior, and material limitations.

The published spec-reference rules require a Spec: trailer in the final paragraph of each commit and PR description, all naming the same governing spec. Use the spec's published path without .md.

Merge, revert, fixup!, squash! and amend! commits are exempt. Bug fixes, documentation, CI and tooling changes still cite the spec governing the affected behavior; repository-wide work cites the applicable meta/ spec.

Put the qualified implements reference in both the completing commit and the completing PR description so SpecDoc can track completion and collect implementation feedback.

Spec: core/004-network-backend
implements netfyr/specs#17

This example refers to the backend spec: #17 is its original spec pull request number, not the 004 in its filename. Include both lines in the completing commit and PR description. Earlier or partial work carries only Spec:. A bare implements #17 would refer to the wrong repository.

  • For a regression with a known introducing commit, add Fixes: HASH12 ("COMMIT SUBJECT").
  • Update affected documentation. Add a core CHANGELOG.md entry under [Unreleased], with the spec path in parentheses, when users or packagers would notice the change.
  • Retain the references in the final merge or squash message. Check that the linked spec and completing reference describe the same work.

Spec-reference rules apply even when hooks and CI do not enforce them.

Tools and infrastructure

Hosted services and test machines have separate access arrangements.

Where to work and what access is needed
ResourcePurpose and access
GitHub Source, merged specs, issues, and pull requests. Public repositories can be read and cloned; use your GitHub account to contribute. Repository permissions govern review and merge access.
SpecDoc The spec board, editor, planning view, and dependency library. Public specs are readable without signing in. Sign in with GitHub to participate; approval rights come from the project's configured roles.
nm-devtools Shared scripts and workflows for development, bug reproduction, review, VM tests, and network transition experiments. These are optional tools; follow the target checkout's actual commands and contribution rules.
SpecDoc CLI Use the specdoc command to read specs, edit notes with conflict checks and submit bot reviews. context pin fixes a task's chosen requirements at selected Git revisions. The CLI also provides spec change previews and build and CI declarations.
SpecDoc MCP Optional access to the CLI's context engine from an agent. Pass a manifest pinned with the CLI to retain the task's chosen requirements, and check reported gaps and omissions. Queries without a manifest read current board text, which may still be under review. The read API supports other integrations.
testvm and vm-test Tools for configured libvirt test environments, snapshots, rollback, and evidence collection. Cloning the tools does not provision a VM or grant host access. Arrange shared-host access with its maintainer, or configure your own disposable environment.
Site hosting The website, user docs, and design library publish through GitHub Actions and Pages. Maintainers manage DNS and hosted services. Contributors can propose content changes through the site repositories without infrastructure credentials.

On a shared test host, claim a VM before a long run and release it afterward. Respect another session's lease. Preserve a recoverable snapshot and collect evidence before rollback; vm-test supports that workflow.

Maintainers follow the onboarding instructions to change contributor access, reviewer eligibility and quorum. The contributor inventory generates repository policies and SpecDoc settings; policy and deployment changes go through reviewed GitHub PRs.

If you need access or cannot run a required check, explain the task and the missing capability in the relevant issue or pull request so a maintainer can help arrange it. Include what you have already verified.

Documentation and publishing

Keep documentation with its audience and source:

  • netfyr/specs holds the reviewed requirements.
  • netfyr/docs publishes user guides and configuration reference at docs.netfyr.io. Its README describes preview and validation commands.
  • Run make docs in the core checkout to build the Rust API reference. Open target/doc/netfyr_state/index.html and use the Crates sidebar to switch libraries.
  • netfyr/design owns the design library, shared assets, and component guidance.
  • netfyr/netfyr.io holds this contributor guide and the project landing page.

Generated schemas and field references stay under the docs repository's deterministic sync. The repository pins the core revision used by its reference and example checks, and its scheduled workflow proposes updates in a PR. The documentation bot handles selected prose pages separately. Maintainers merge reviewed documentation PRs to publish the changes.

Implementation completion, documentation publication, and a software release are separate events. A board card marked implemented means the completing commit landed. Core changes remain in [Unreleased] until released; this guide does not define a release cadence.

For SpecDoc service upgrades, follow its release and rebase guide, which covers editor and board images and updates to the HedgeDoc fork.

Keeping this guide current

Check repository instructions and merged specs when a command, role, or requirement changes. Confirm a tool is present in your checkout before using it.

Propose corrections through this page's source, with a link to the changed rule or implemented workflow.