Home

Community

Release v0.4.0

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:

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

  1. 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.
  2. 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: copy docs/adr/0000-template.md to docs/adr/NNNN-short-title.md with status Proposed. It is implemented only once it is Accepted, 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.
  3. 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 of docs/compiler/testing.md. A fix gets a regression test that fails before the fix.
  4. Implement, following docs/compiler/conventions.md.
  5. 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:

bash
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 container

A 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:

bash
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo insta review   # review each snapshot change; never accept one blindly

Tests 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:

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.