Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
102 lines (77 loc) · 5.69 KB

CONTRIBUTING.md

File metadata and controls

102 lines (77 loc) · 5.69 KB
Raw

Contributing

Changes must preserve ARM64 guest correctness and leave a repeatable test. Read ARCHITECTURE.md, VALIDATION.md and LIMITATIONS.md before changing translated execution, memory, signals or host integration.

Prepare the checkout

git submodule update --init --recursive
CC=clang make build-arm64-linux

Use an AArch64 Linux host for the command-line build. The supported build uses Clang's integrated assembler.

Source changes

  • Keep the decoder in asbestos/guest-arm64/gen.c consistent with the operand format consumed by its gadget.
  • Reject reserved encodings instead of accepting a wider mask for convenience.
  • Preserve guest architectural state when source and destination registers alias.
  • Check width, upper-lane, flags, alignment, rounding and fault semantics.
  • Put host differences behind platform/ when the abstraction has more than one caller or prevents duplicated conditional code.
  • Do not hide a guest fault with a rootfs patch, binary patch or synthetic success result when the instruction or syscall is wrong.
  • Bound guest-controlled lengths before allocating host buffers or copying data.
  • Keep cooperative contexts/task/token references on the owning guest thread; never abandon live workers or change process-wide CWD/shared nonblocking flags. Follow offload contracts, including partial-output policy.
  • Keep acceleration disabled in reference app configurations. Test matching translations, signing, error recovery and workloads on the target device before distributing an accelerated build.

Tests

Add the smallest fixture that fails before the fix and passes after it. Low-level examples live under tests/arm64/atomics/, tests/arm64/fp/, tests/arm64/loadstore/ and tests/arm64/signals/; broader rows are generated by tests/arm64/runtime-coverage.sh.

Run the focused fixture and the relevant broad check. For most runtime changes:

CC=clang make build-arm64-linux-all
make test-arm64-runtime-coverage \
  ROOTFS_LANES="alpine=$PWD/alpine-arm64-fakefs" \
  REPORT_DIR=/workspace/tmp \
  TIMEOUT_S=180 \
  INSTALL_TIMEOUT_S=1200

Memory, signal, synchronisation and translated-execution changes also need the debug runtime check. Network and package-manager changes need the CLI or package lane that exercises them.

A timeout, safety valve, unexpected diagnostic or skipped row is not a pass. Hash source and runners before launch, wait for completion, and verify hashes before using the evidence. Do not reuse stale return-code files or edit a runner while its shell is still reading it. Record package and rootfs failures separately from emulator results.

For performance-only changes, the correctness fixture should pass both the baseline and candidate; use a deliberate negative mutation to show it detects the invariant being protected, then restore and rebuild. Keep paired timing separate from correctness runs, use identical commands and input bytes, and reject changes whose benefit does not repeat. Preserve native-oracle failures and record the exact paths exercised by each test.

Documentation

The maintained guides describe current master:

  • README.md for project scope and first use;
  • docs/ARCHITECTURE.md for durable design;
  • docs/LINUX_DEVELOPMENT.md and docs/IOS_APPLICATION.md for procedures;
  • docs/NATIVE_AOT_BUILD_PLAN.md, docs/NATIVE_AOT_ARTIFACT_KIT.md and docs/NATIVE_AOT_IOS.md for AOT recording, reusable inputs and Apple integration;
  • docs/NATIVE_OFFLOAD.md for legacy/cooperative ownership and I/O contracts;
  • docs/NETLINK_TAILSCALE.md for opt-in interface discovery;
  • docs/VALIDATION.md for tests;
  • docs/LIMITATIONS.md for known constraints;
  • docs/RELEASES.md for version and tag changes.

Put a dated investigation or benchmark under docs/reports/ when its values depend on a revision, host, rootfs or package set. Do not turn a dated report into current guidance by linking it without its date and scope.

Lead with the fact. Use British English, concrete nouns and active verbs. Keep commands, paths and identifiers exact. Put the revision, hardware and test scope beside measured results. Link to detailed evidence instead of repeating it.

Remove inflated adjectives, rhetorical questions, sincerity claims, manufactured contrasts and commentary about what a document proves or implies. State the operation, failure or missing test directly. Avoid repeated warnings and closing summaries. Keep safety requirements and uncertainties when shortening prose. Dated evidence and upstream/third-party text retain their original wording.

Write for the reader's task. Avoid internal work tracking, development play-by-play, team shorthand and unexplained project jargon in documentation or release notes. Retain commands, requirements, failure conditions and known limitations. Explain necessary technical terms where they first appear.

When moving a document, update relative links in the moved file and every maintained guide. Preserve upstream translations under docs/legacy/; do not silently rewrite them as current fork documentation.

Before commit

git diff --check
git status --short
git diff --stat
git diff

Run make check-docs check-docs-style test-docs-style, then confirm that commands in changed procedures match the Makefile, Meson files, Xcode schemes or scripts that implement them. The style scanner skips code, quotations and tables; review those and multi-line prose manually.

Commit source, its regression fixture and the relevant documentation together. Push only after the local branch is based on the intended remote tip. Create release tags from a clean, pushed commit after the app version and Apple build number match the release guide.