Community
Una is developed in the open. Questions, reports and contributions go through the repository: issues, the code of conduct and security reports.
Thank you for your interest in Una. Reports from people who use the language are the most useful contribution right now: a program the compiler gets wrong, a diagnostic that misleads, a guide that is unclear.
Reporting
Open an issue and pick the template that fits:
- Bug report: the compiler crashes, rejects a valid program, or prints the wrong output.
- Soundness report:
una checkaccepts a program that breaks a guarantee Una claims to prove (types, authority, information flow, contracts). These are the most valuable reports. - Question: anything about the language, the tools or the documentation.
Include the smallest program that shows the problem, the command you ran, what you expected, and the output of una --version. If a report could hurt users before it is fixed, such as a way for a program to escape its grants at run time, follow SECURITY.md instead of opening a public issue.
How work flows
- An issue first. Every change starts as an issue, so its scope is agreed before code is written. One issue per branch and per pull request.
- The specification first.
docs/spec/defines the language, and when the code and the specification disagree, the specification wins. A change to the language starts as an architecture decision record: copydocs/adr/0000-template.mdtodocs/adr/NNNN-short-title.mdwith statusProposed. It is implemented only once it isAccepted, and the specification is updated in the same change as the implementation. Accepted records are not edited; later changes are appended as a dated amendment. - Tests first. Write the tests that encode the rule before implementing it. A language rule gets conformance cases in
tests/conformance/, positive and negative, in the format ofdocs/compiler/testing.md. A fix gets a regression test that fails before the fix. - Implement, following
docs/compiler/conventions.md. - Validate locally, then open the pull request.
Branches are named dev/<issue>-<topic>, for example dev/6-integration-rule. Every commit references its issue (Refs #6), and the pull request closes it (Closes #6, one keyword per issue). Each pull request adds one changelog fragment, changelog.d/<issue>-<slug>.md: a single line that is one bullet, - **What changed** (#<issue>, …). Details., and never edits CHANGELOG.md itself (#744). Two pull requests then never change the same lines. The release assembles the fragments (scripts/changelog-assemble.sh), and the tests check every fragment's shape and that ## Unreleased stays empty.
Validation
Validation runs locally. A pull request is merged after scripts/local-ci.sh passes on its final commit:
eval "$(scripts/z3-library.sh --export)" # the Z3 library that una links, as in the README's "Build from source"
scripts/local-ci.sh # solver check, formatting, clippy, every test, the release archive
scripts/local-ci.sh --linux # the same steps in a Linux containerA pull request that changes scripts/local-ci.sh, its Docker image under scripts/local-ci/, or a script that one of its steps calls also needs scripts/local-ci.sh --linux-arm64 to pass on its final commit, since a tool the image lacks fails only there (docs/release-gates.md §1). Each run ends with PASS, or with FAIL and the step that failed. One step, scripts/doc-links.py, checks that every link of the repository's documents names a tracked file and every #fragment a heading of its document; it needs Python 3. The website is built from the repository's documents by the release gate site (docs/release-gates.md). During development, the usual commands are:
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo insta review # review each snapshot change; never accept one blindlyTests that reach the solver need a una built with UNA_Z3_LIB set, in the same shell, to the Z3 library that scripts/z3-library.sh --export builds from the source supply-chain/z3.lock pins (the README's Build from source); una uses no z3 on PATH. Without it the build makes a una with no solver, and those tests fail with U5003 rather than skip.
Releases are checked the same way: scripts/release-gates.sh runs every gate on one commit from a fresh clone, and each release's summary is in docs/validation/, as docs/release-gates.md describes.
Rules for the code
The full list is in docs/compiler/conventions.md. The most important:
- No
unsafe, except in the documented boundary module of the native runtime. - No
unwrap,expectorpanic!in library crates, except for internal invariants marked// INVARIANT: <reason>. Problems a user can cause are diagnostics with a registered code. - Library crates never print; only
una-cliwrites to the terminal. - Output is deterministic: no hash-map iteration, timestamps or randomness in anything a user sees.
- Every public item has a doc comment, and every diagnostic code has an entry in the specification and an
una explaintext. - Choose the algorithm with the best average-case complexity, and state it.
Writing
Documentation and messages are in English, with American spelling. Normative text uses MUST, MUST NOT, SHOULD and MAY. A diagnostic message is one sentence with a lowercase start and no trailing period, and it names the construct: capability @audit is not in scope.
Conduct
Everyone who takes part in the project follows the Code of Conduct.
License
By contributing, you agree that your contributions are licensed under the Apache License, Version 2.0, the license of the project.