2b6f30d348
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]>
77 lines
3.5 KiB
Markdown
77 lines
3.5 KiB
Markdown
# 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](https://developercertificate.org): 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|