Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
209 lines (155 loc) · 6.51 KB

CONTRIBUTING.md

File metadata and controls

209 lines (155 loc) · 6.51 KB
Raw

Contributing To SHAFT Engine

This repository contains the Java 25 Maven reactor for SHAFT Engine. The public user guide lives in ShaftHQ/shafthq.github.io.

1. Check Out The Code

Fork the repository if you are not a maintainer. Then clone your fork:

git clone https://github.com/<your-user>/SHAFT_ENGINE.git
cd SHAFT_ENGINE
git remote add upstream https://github.com/ShaftHQ/SHAFT_ENGINE.git

Maintainers can clone the canonical repository directly:

git clone https://github.com/ShaftHQ/SHAFT_ENGINE.git
cd SHAFT_ENGINE

Start every change from current main:

git fetch --prune origin
git switch main
git pull --ff-only origin main
git switch -c <short-topic-branch>

If you work from a fork, replace the pull command with:

git fetch --prune upstream
git switch main
git merge --ff-only upstream/main
git push origin main
git switch -c <short-topic-branch>

2. Install The Toolchain

Required:

  • JDK 25.x only.
  • Maven 3.9.0 or newer.
  • Git.

The repository includes .java-version and .sdkmanrc for version managers. With SDKMAN:

sdk env install
sdk env

Verify the active tools before building:

java -version
mvn -version

Expected: Java reports version 25.x, and Maven reports 3.9.0 or newer.

Maintainer Agent Tooling (optional)

Agent-assisted maintenance expects this third-party stack. Full install, update, and troubleshooting runbook: Agent tooling.

  • memory CLI — npm install -g @aictx/memory@0.1.55 (pin matches scripts/ci/validate_agent_setup.py); repo store lives in .memory/.

  • graphify — deterministic repository map for pre-search file selection: py -3 -m pip install --user graphifyy==0.9.17, build with graphify . from the repo root (cache in gitignored graphify-out/; see tools/repository-map/README.md). Nightly auto-refresh (Windows): tools/agent-infra/install-agent-tasks.ps1.

  • MCP servers (.mcp.json) — context7 starts on demand through npx. Optional Maven Tools MCP uses a locally verified Java 25/JAR installation discovered by the ChaosEngine installer; default agent configuration does not start Docker.

  • SHAFT MCP, CLI, and skills — Change into the target project first, then install from the current working directory:

    irm "https://raw.githubusercontent.com/ShaftHQ/SHAFT_ENGINE/main/scripts/mcp/install.ps1" | iex
    curl -fsSL "https://raw.githubusercontent.com/ShaftHQ/SHAFT_ENGINE/main/scripts/mcp/install.sh" | bash

  • Claude Code plugins — installed automatically from .claude/settings.json enabledPlugins/extraKnownMarketplaces on first session.

3. Build Locally

PowerShell users should keep Maven -D arguments quoted as shown.

mvn clean install "-DskipTests" "-Dgpg.skip"

This compiles the reactor and installs local artifacts without running the test suite.

4. Make The Change

Working With A Coding Agent

This repository ships its own agent skills, so an agent can follow the same conventions this guide describes instead of guessing at them. Point yours at them before it touches anything:

Read chaos-engine/skills/chaos-engine/SKILL.md and follow it for this task.

Most agents discover that entrypoint on their own. The agent skills map explains how the skills fit together and how each host imports them; which task sends you to which surface is stated once, in the routing table. Read the map once before your first agent-assisted change.

  • Keep the scope tight and follow existing package and module boundaries.
  • Preserve public API compatibility. Deprecate before removing or renaming a public API.
  • Add JavaDocs for every new public class or public method.
  • Use Log4j or SHAFT ReportManager; do not use System.out.println or System.err.println in production code.
  • Use SHAFT fluent assertions in tests where applicable.
  • Do not commit generated reports, binaries, secrets, target/, or local credential files.

The Docusaurus user guide is the canonical location for product, usage, architecture, migration, and maintainer documentation. Do not add public guides or module READMEs to this repository.

5. Validate By Risk

For documentation or agent-guidance changes:

py -3 scripts/ci/validate_agent_setup.py
py -3 scripts/ci/validate_documentation_boundaries.py
git diff --check

For localized code changes, run the affected test first. Always scope the run with -Dtest= and force headless execution, so a browser-capable test cannot open a real window on your machine:

mvn -pl shaft-engine -am test "-Dtest=TestClassName" "-DheadlessExecution=true"

Then run one compile/package pass appropriate to the change. For broad API, concurrency, build, or release changes, run targeted tests and the full compile/package command before opening a pull request.

When public JavaDocs change, also run:

mvn -pl shaft-engine javadoc:javadoc

For visual behavior changes, include image or browser evidence. Run external or credentialed cloud suites only when the required infrastructure is available and the result is necessary.

6. Update Documentation When Needed

If the change affects public behavior, update the user guide in ShaftHQ/shafthq.github.io in the same delivery.

Before the engine PR is ready:

  1. Open the documentation PR.
  2. Verify the documentation deploy preview and affected canonical routes.
  3. Link the documentation PR from the engine PR.
  4. If documentation is not required, state the concrete reason in the engine PR.

7. Open The Pull Request

Push your branch:

git push -u origin <short-topic-branch>

Open a pull request against ShaftHQ/SHAFT_ENGINE:main.

The PR is ready for review when it includes:

  • A clear problem statement and solution summary.
  • Focused tests or evidence for the changed path.
  • Validation commands and results copied into the PR description.
  • JavaDocs for new public APIs.
  • Compatibility preserved, or deprecations added before removals.
  • A linked user-guide PR for user-facing behavior changes, or a clear reason no docs change is needed.
  • No generated reports, binaries, secrets, target/, or credentialed cloud output.

Reviewers should be able to check out the branch, run the listed commands, and see the same result.