Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
77 lines (63 loc) · 4.59 KB

CONTRIBUTING.md

File metadata and controls

77 lines (63 loc) · 4.59 KB
Raw

Contributing

Prerequisites

  • Rust stable, from rustup, with two more targets: rustup target add wasm32-unknown-unknown wasm32-wasip2. The build script of dm-web builds the browser reader for the first target. Thus each build of amem needs it. The second target builds the taps. make check lints the taps, and the tests of the tap host build them. Thus the gate needs the second target.
  • The build script of dm-web runs a second cargo for the reader. That cargo reads the cargo config files and the environment. It does not get the command line of the first cargo: --config, --offline and --frozen do not reach it. Put such a setting, for example a vendored source replacement, in a cargo config file. For a build without the network, set CARGO_NET_OFFLINE=true, or net.offline = true in a config file. The build script sets its own rustflags (--remap-path-prefix) for this cargo. So the rustflags in a cargo config file do not reach the reader build.
  • A C toolchain for the bundled SQLite: build-essential on Debian and Ubuntu, or the Visual Studio Build Tools on Windows.
  • make. On Windows, run the targets from Git Bash or WSL.
  • python3, for scripts/conformance.py and its test. make check and the tests of the binary run them. The script uses only the standard library.
  • For the tests of the browser reader: Chrome or Chromium, or Podman or Docker. If no Chrome is installed, the tests use the browser in the Playwright image, through scripts/chrome-container.sh. This script pulls the image on its first use. The test has two minutes. To keep the pull out of these two minutes, run podman pull mcr.microsoft.com/playwright:v1.61.1-noble before the test. To select a browser directly, set CHROME=<path>.

Setup

git clone git@github.com:apache/tooling-memory.git
cd tooling-memory
make init        # installs the pre-commit hook
make check       # format, clippy, tests, guard, docs-only and conformance tests

Day to day

Command What it runs
make check cargo fmt --check, cargo clippy -D warnings, cargo test, the guard, docs-only and conformance tests. It is the pre-commit gate. A commit that has only Markdown, outside crates/ and taps/, runs the guard tests instead
make conformance scripts/conformance.py: the seven M0 steps over MCP, against a new record that this build serves. URL=<mcp endpoint> points it at a different server. OPERATOR=<command> gives it the export, import and reindex of that server, for the last two steps
make test only cargo test
make fmt cargo fmt, which changes the files in place
make run ARGS='...' the amem binary, for example ARGS='init --root /tmp/m --domain dom-me'
make verify check, and also cargo deny, cargo machete, coverage against COVERAGE_MIN, and the browser builds of dm-core, dm-policy and dm-reader. CI runs this target
make msrv-check cargo check of the workspace and of the browser builds, with the Rust release that rust-version in Cargo.toml names. It needs that toolchain: rustup toolchain install <rust-version> --profile minimal --target wasm32-unknown-unknown. It is not part of check or verify. CI runs it as a separate job
make e2e the browser tests in e2e/. Chromium in the Playwright image drives the pages. The tests put screenshots in e2e/screenshots/. It needs Podman or Docker, not Node. It is not part of check or verify. Run it for a change to the pages. See e2e/README.md
make coverage cargo llvm-cov over the workspace. It writes an lcov report to target/lcov.info

verify needs three cargo extensions. Install them one time:

cargo install cargo-binstall
cargo binstall cargo-llvm-cov cargo-deny cargo-machete

rust-toolchain.toml pins the channel. It also adds rustfmt, clippy, the llvm tools and the wasm targets. Thus rustup sets up the rest on its first use.

Use one worktree for each topic. Then several people and sessions can work at the same time:

git worktree add ../durable-memory-<topic> -b feat/<topic> origin/main

Pull requests

Make your branch from main. make check must pass before each commit. The hook enforces this. Write the commit subject with a conventional-commit prefix. Open the PR against main. In its description, say what changed and why. For a new test, also say what the test reported against the code before the change.

AGENTS.md is the contract for AI agents that work in this repository. Most of it is also good advice for people.