Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
71 lines (49 loc) · 3.52 KB

CONTRIBUTING.md

File metadata and controls

71 lines (49 loc) · 3.52 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
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.

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 gate. 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 gate. 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. Record package and rootfs failures separately from emulator results.

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/VALIDATION.md for gates;
  • 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.

Write exact commands, paths and identifiers. State measured results with their revision and environment. Remove unsupported superlatives and third-party deployment claims that the repository cannot verify.

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, then confirm that commands in changed procedures match the Makefile, Meson files, Xcode schemes or scripts that implement them.

Commit source, its regression fixture and the relevant documentation in the same tranche. 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.