Transaction-Science/flowrs-engine
Watch
1
0
Fork
You've already forked flowrs-engine
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
flowrs-engine/CONTRIBUTING.md
flowRS 2b6f30d348 flowRS engine, cut from flowRS f907e0756a7c 
Built alone from an empty CARGO_HOME, its tests passed, and flowrsc checked, ran and exported a
document from the conformance corpus; the export built alone.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-10 08:54:33 -05:00

3.5 KiB
Raw Permalink Blame History

Contributing to flowRS

Two sentences settle how this works:

What people make belongs to them.

They are allowed to freely contribute to the project if it is beneficial to the project.

What you build with flowRS is yours, and contributing back is your own free choice. Nothing asks you to. If you do, here is all of it.

The rules

  • You keep your copyright. There is no CLA and nothing to assign.

  • Inbound = outbound. What you contribute is under the licence of the part you contribute to: each crate's Cargo.toml says which (Apache-2.0, or MIT OR Apache-2.0). The prose of spec/flowrs-document-2.md (and of version 1.0.0, spec/flowrs-document-1.md) is under CC BY 4.0.

  • Sign off each commit, certifying the Developer Certificate of Origin: that you wrote it, or otherwise have the right to submit it under that licence. git commit -s adds the line:

    Signed-off-by: Your Name <[email protected]>

    The name can be the one you are known by; the address only needs to reach you or be one you use for git.

  • Maintainers decide by one test: whether it benefits the project. A contribution is accepted when it does, and the answer, with why, is said on the pull request.

How

Open a pull request or an issue on the public repository: https://git.transaction.science/Transaction-Science/flowrs-engine (mirrored at https://codeberg.org/Transaction-Science/flowrs-engine). The editor and the server are not in that repository; an issue is the way to raise something about them.

What the checks are

A change goes in when the checks pass and a maintainer has read it:

make check      # fmt, cargo machete, clippy with warnings as errors (tests included)
make test       # the tests
make audit      # known vulnerabilities, licences, sources

In the engine repository, which has no Makefile: cargo fmt --all -- --check, cargo clippy --locked -p flowrs-core -p flowrs-cli --all-targets -- -D warnings and cargo test --locked -p flowrs-core -p flowrs-cli.

A new test should fail when the rule it guards is broken: break it once and watch. Third-party code or data goes in only under a licence that allows it, with the text beside it and a line in the crate's PROVENANCE.md; a fact from a GPL project is cited to its primary source.

Packages for the registry

The registry takes widgets, drivers, boards and dialects by pull request. No route on the site takes an upload. A package is a crate with a flowrs-package.toml beside its Cargo.toml: its kind, name, version and licence, what it provides, its declared network and filesystem needs, the unit of every port, and the tests that must run. It inherits nothing from a workspace, depends on flowRS crates by name, and its tests read only its own tree and start nothing. https://flowrs.openie.dev/docs/registry/ describes each condition.

Before you open the pull request, run what can run without the signing key:

flowrsc pkg check <dir>

It reads the manifest, packs the archive and checks the five conditions as far as your machine can observe them (the confined runs need macOS's seatbelt; elsewhere those conditions say not run, and nothing has failed).

Then, in this order: the package is verified in the sandbox on flowRS's build host; a person judges whether it benefits the project; and only then is its record signed, on a maintainer's own machine, and published. The signing key is not on the build host, where packages are built, or on the server.