Workflow

Branch workflow, local setup, and verification for every contributor.

Executive Summary#

• Local setup — Install Lefthook for pre-commit formatting, then lefthook install
• Branch workflow — Branch from main, implement with implementation principles, critical rules, and code style, add tests, update docs, commit
• Verification — ./build.pas testrunner && ./build/GocciaTestRunner tests before every push

Local setup#

After cloning, install Lefthook so ./format.pas runs on pre-commit:

# macOS
brew install lefthook

# Linux (Snap)
sudo snap install lefthook

# Linux (APT — Debian/Ubuntu)
# See https://github.com/evilmartians/lefthook/blob/master/docs/install.md
curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.deb.sh' | sudo -E bash
sudo apt install lefthook

# Windows (Scoop)
scoop install lefthook

# Windows (Chocolatey)
choco install lefthook

# Any platform with Go installed
go install github.com/evilmartians/lefthook@latest

# Any platform with npm
npm install -g lefthook

Register hooks once per clone:

lefthook install

Formatting, editor integration, and CI behavior are covered in Tooling.

Feature workflow#

Every change should follow this sequence:

1. Create a branch from main with a descriptive name (for example feature/string-prototype-repeat, fix/nan-comparison). 2. Implement on that branch, following Implementation principles, Critical rules, Code style, and the relevant architecture docs for the area you touch. 3. Verify and annotate spec references — For ECMAScript behavior, verify semantics against the current official ECMA-262 text, then add // ESYYYY spec comments as described in ECMAScript spec annotations. 4. Add or update tests — JavaScript tests under tests/ are primary; Pascal units under source/units/*.Test.pas when you touch AST, evaluator, or value types. See testing.md and Critical rules. 5. Update documentation that your change affects (README.md, docs/*, and CONTRIBUTING.md when workflow, rules, or style change). Edit AGENTS.md only when agent-specific guidance changes—not to duplicate CONTRIBUTING. If the change introduces a new architectural or design decision (not just a feature addition), add an entry to decision-log.md following the template there. 6. Commit with a clear message. Do not commit directly to main.

git add .
git commit -m "Short imperative description of the change"

Issues and pull requests#

• Issues: Use .github/ISSUE_TEMPLATE/default.md (Summary, Why, current vs expected behavior, scope).
• Pull requests: Use .github/pull_request_template.md (Summary with constraints and links, testing checklist).

Verify changes#

./build.pas testrunner && ./build/GocciaTestRunner tests

For interpreter/VM internals, also run native Pascal tests as described under Testing.