Contributing

Thanks for helping build the Open Aquarium Project. Contributions of all kinds are welcome: comments on drafts, test data from real tanks, implementations, hardware designs, and new proposals.

Ways to contribute

• Discuss. Open an issue, and choose the form that fits. Each form adds its label: discussion for questions, proposal for new ideas that need discussion before anything is written, spec-change for a specific change to a specification, breadboard for results from the breadboard prototype, and bug for tools that do not work as documented. Issues about one specification also get that specification’s label, such as data-model.
• Propose. For a new specification, a new reference design, or a large change, write a proposal. See proposals/.
• Change a specification. Open a pull request against the spec. Link the issue it resolves, and add a row to the spec’s Revision History table.
• Implement. Build something that reads, writes, or speaks a specification, and tell us how it went. Independent implementations are required before any specification can be approved.

Legal terms

Specifications and proposals

By contributing to anything in specs/ or proposals/, you agree to the Community Specification Contributor License Agreement 1.0. In short, you agree to the Community Specification License 1.0, which grants a copyright license to your contribution and a royalty-free patent license to your claims that are necessary to implement the specification, within the bounds of Scope.

If your employer may have rights in what you contribute, make sure you have their permission first.

Everything

Every commit must be signed off under the Developer Certificate of Origin 1.1, certifying that you have the right to submit it under the license that applies to it. Sign off with:

git commit -s

Commits without a Signed-off-by line cannot be merged, and a check on each pull request fails if any of its commits lacks one. To check your branch before opening a pull request, run python tools/check_signoff.py origin/main..HEAD.

Which license applies

See Licenses. In brief: specifications use the Community Specification License 1.0, code and machine-readable files use Apache-2.0, and hardware design files use CERN-OHL-W-2.0. Add an SPDX-License-Identifier line to new source files.

Writing specifications

• Start from the template and keep its section order.

• Write one sentence per line.

• Use requirement keywords (MUST, SHOULD, MAY) only in capitals and only for real requirements.

• Prefer reusing an existing open standard over inventing a new mechanism.

• Use SI units, plus hobby units where people actually use them (dKH, °F, gallons). Write dates as YYYY-MM-DD.

• Some tables are generated from machine-readable files, such as the data model registry and the device class definitions. Edit the file, not the table, then regenerate the tables.

• Keep examples valid. Before opening a pull request, run:

  pip install -r tools/requirements.txt
            python tools/render_spec_tables.py
            python tools/validate_data_model.py specs/data-model/examples/*.json
            python tools/validate_device_description.py specs/device-classes/examples/*.json

  If you change the module bus data types, also check them against a checkout of the Cyphal standard data types at the commit named in the Module Bus specification:

  python tools/check_dsdl.py path/to/public_regulated_data_types

Hardware contributions

• Provide design files in formats that free tools can open and edit, such as KiCad and FreeCAD, alongside any other formats.
• Include a bill of materials, and give a second source for parts where one exists.
• Designs that switch mains voltage need a certification plan before they are merged. See Proposal 0001.

Pull requests

1. Prefix the title with WIP: while work is in progress.
2. Reviewers use GitHub reviews. “Approve” means the reviewer is satisfied.
3. A change to a specification needs approval from one of its Editors before it is merged.
4. The Maintainer merges once consensus is clear. See Governance.

Code of conduct

Everyone taking part agrees to the Code of Conduct.