Skip to content

development.md

Latest commit

 

History

History
166 lines (119 loc) · 4.43 KB

development.md

File metadata and controls

166 lines (119 loc) · 4.43 KB
Raw

Development

This repository favors small, verified changes. Read the relevant code first, make the smallest safe diff, and document user-visible behavior changes.

Prerequisites

  • Git
  • Rust toolchain from rust-toolchain.toml
  • curl, tar, and install for installer smoke tests
  • just for repository recipes
  • mise for hk hook/tool provisioning
  • Node.js 24 and pnpm 11 for pi-mark
  • Nix, optional but preferred for a complete local shell

Do not install global tools just to work in the repo when nix develop or the checked-in package manager setup is available.

Setup

Preferred:

nix develop
just setup

Without Nix:

cargo fetch --locked
cargo build -p mark-cli --locked

Install global hk Git hooks:

just hooks

hk's global hooks require Git 2.54 or newer. The Nix development shell provides a new enough Git. The hook command is a no-op in repositories without hk.pkl. This repository's pre-commit hook runs fast staged-file checks and safe fixers; pre-push enables the slower full and pi profiles for affected files.

Common commands

just check
just ci-check
mise x -- hk check --all --plan
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --all-targets --all-features --locked
cargo build -p mark-cli --locked

For the Pi package:

cd pi-mark
pnpm install
pnpm run check

Run the local extension from the repository root with:

pi -e ./pi-mark/extensions/pi-mark.ts

Verification ladder

Use the cheapest check that proves the change first:

  1. rust-analyzer diagnostics .
  2. cargo fmt --all --check
  3. cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
  4. Focused unit test, for example cargo test -p mark-tui filter
  5. Focused integration or smoke test
  6. cargo test --workspace --all-targets --all-features --locked
  7. cargo build --workspace --all-targets --all-features --locked

Full builds are most useful for public API changes, build config changes, dependency changes, generated code, toolchains, release packaging, or broad cross-crate behavior.

Local smoke tests

Installer and update smoke test:

scripts/smoke-installer-update

Interactive error-pane smoke test:

scripts/test-diff-error-pane

The interactive smoke test must run in a terminal.

Profile-guided builds

scripts/build-pgo produces a profile-guided release mark binary: it builds instrumented binaries, trains on the committed engine corpora and bench fixtures, merges the profiles with llvm-profdata (needs rustup component add llvm-tools), and rebuilds with -Cprofile-use. Engine-bound corpora run 15–35% faster than a plain release build (docs/performance-reports/2026-07-12-engine-optimization.md). Retrain whenever the engine or the global allocator changes materially — a stale profile silently forfeits most of the gain.

Release flow

The main mark binary release uses GitHub Releases.

  1. Update the workspace package version in Cargo.toml.
  2. Merge the change.
  3. Push a vX.Y.Z tag, or run the Release workflow manually.

The Release workflow builds macOS and Linux assets named like:

mark-vX.Y.Z-aarch64-apple-darwin.tar.gz
mark-vX.Y.Z-x86_64-apple-darwin.tar.gz
mark-vX.Y.Z-aarch64-unknown-linux-gnu.tar.gz
mark-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz

Those names are part of the installer contract.

Nightly flow

The Nightly workflow publishes the latest main commit to a mutable vnightly GitHub prerelease. The installer treats it as an explicit version channel:

curl -fsSL https://raw.githubusercontent.com/phongndo/mark/main/scripts/install.sh | MARK_VERSION=nightly sh

Nightly replaces the active mark binary. Users switch back to the latest stable semver release with:

mark update

Keep vnightly marked as a prerelease and not latest. The installer only resolves semver tags like v0.8.0 for the default latest channel, so stable updates do not accidentally install nightly.

Nightly builds set MARK_BUILD_CHANNEL=nightly, so mark --version includes the channel and source commit.

pi-mark release flow

pi-mark is published separately to npm.

  1. Update pi-mark/package.json version.
  2. Merge the change.
  3. Run the Publish pi-mark workflow.

The workflow validates the package, publishes with npm provenance, and can create a pi-mark-vX.Y.Z GitHub release.