Skip to main content

Contributing

Thank you for helping improve Faberio. This documentation site and the protocol specifications are the current public artefacts. Reference Runtime source code will be published separately under Apache-2.0 when available.

Current status: specifications are draft. See the Implementation Roadmap.

By participating, you agree to follow the project Code of Conduct (Contributor Covenant). Reports of unacceptable behaviour: info@faberio.dev.

Ways to contribute​

  • Clarify or correct protocol specifications under Specs
  • Improve architecture and roadmap documentation
  • Fix typos, broken links, diagrams, and consistency issues
  • Report issues that block implementers or operators from understanding the design

Source repository: github.com/faberio-platform/faberio-docs. Open an issue or pull request there.

Before you start​

  1. Read How to read these docs, then the Introduction and the Specs reading order.
  2. Skim the Glossary for shared terminology.
  3. Check the Implementation Roadmap so proposals match current scope versus Out of scope / Phase 4.
  4. Prefer small, focused changes over large mixed pull requests.

Spec and docs guidelines​

  • Protocol specs describe normative Runtime behaviour. Use clear MUST / SHOULD / MAY language where requirements matter.
  • Keep the reference MVP distinct from the full protocol target when scope differs — see Specs — Reference MVP coverage.
  • Do not invent APIs or milestone deliverables that contradict the roadmap without calling that out explicitly.
  • Match existing tone and structure; avoid drive-by reformatting of unrelated sections.
  • Diagrams: prefer Mermaid; keep labels consistent with defined terms (information space, node, Runtime, and so on).

Pull requests​

  1. Fork the repository (or use a branch if you have write access).

  2. Make your change on a topic branch.

  3. Preview the documentation site locally when the change affects rendered pages:

    npm install
    npm run start

  4. Open a pull request that states:

    • What changed
    • Why (spec gap, clarity, roadmap alignment, typo, etc.)
    • Links to related issues or spec sections, if any

Maintainers may ask for wording adjustments so the public specs stay implementable and consistent.

The same guidance is also in CONTRIBUTING.md in the repository.

Licensing of contributions​

By contributing to this documentation repository, you agree that your contributions to the documentation and specifications are licensed under CC BY 4.0, consistent with the project’s documentation license. The full license text is in LICENSE.

Security reports​

Do not file public issues for security-sensitive findings. Email info@faberio.dev or follow SECURITY.md. High-level assumptions: Threat Model.

Contact​