# 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 <you@example.org>
  ```

  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.