# Contributor workflow

This page is for changes to the V2 engine, not ordinary handbook authoring. Start from the actual source checkout and record the revision. A public site built with the engine does not prove its repository, deployment or asset versions match yours.

# Classify the change

Do not fix a content mistake by changing the engine without deciding that scope. Preserve unrelated work, use a focused branch and inspect the final diff. Keep real identities, credentials and private account data out of fixtures, screenshots and issue reports.

# Establish a baseline

Read package.json, the lockfile and relevant tests. The pinned package requires Node 24+. Verify the actual running version rather than assuming the default terminal’s Node is suitable. In a disposable checkout, install locked dependencies and run the package test command before changing behavior.

node --version
npm --version
npm ci
npm test

The first two commands read versions; npm ci replaces installed dependencies and may contact package sources. Run it only in the intended checkout. npm test executes code and can create temporary fixtures, not a read-only repository audit. A missing prerequisite or failed baseline is evidence to keep, not a reason to rewrite the result as passing.

For a build reproduction, use a small synthetic content tree and a unique disposable output path through the documented flags. Direct build clears output. Never point parallel fixtures at shared dist/, private runtime data or an important existing directory. Commands gives exact supported flags.

# Reproduce before changing

Keep the smallest reproducible fixture that shows the problem. Test title changes, duplicate routes, repeated/non-Latin anchors and prefix deployments with resulting files rather than hand-computed paths. For security work, test direct server requests as well as the UI; hidden controls alone prove nothing about authorization.

# Test areas

Read the actual test/ files for assertions, fixtures and concurrency assumptions. Some tests inspect source or generated structure rather than driving a browser. Passing them is useful evidence at their scope, not proof of all devices, deployment settings or compliance. Add focused regression cases for the behavior changed; rerun related tests and then the full suite.

# Browser asset regeneration

Ordinary users consume committed files under static/vendor/; normal build does not regenerate them. Maintainer command npm run assets:bundle removes/recreates that vendor directory, copies font files/CSS, bundles Mermaid and Highlight.js, copies browser markdown-it, and generates notices plus a version/hash manifest.

Run it only in the intended maintainer checkout with development dependencies available. Review the lockfile, generated libraries, all notices and manifest together. The manifest inventories package versions and SHA-256 hashes for vendor files before writing the manifest itself; it is not a signature or a whole-repository provenance guarantee.

The bundler targets ES2022 for its generated JavaScript. Do not turn that setting into a tested-browser compatibility claim. Review real diagrams, code coloring, fonts, delayed loads and both themes on the browser/device set you actually support. Preserve licensing notices when redistributing generated assets.

# Actual visual and task checks

Inspect actual pixels at phone and desktop widths, with longest labels/rows and both themes. Use synthetic data. Check keyboard navigation, focus, readable error messages and touch controls, not only a screenshot of the default success state.

For reader changes, exercise search result navigation, heading reload, missing route, exact code clipboard and diagram rendering. For writer changes, preserve unsaved text through navigation, slow/failed Save, sign-out and draft recovery. For Admin changes, test role denial, unsaved/discard state, stale revisions and session invalidation. For publishing, test failure before switch and failure during switch separately with disposable folders.

Emulated mobile width is not physical Safari testing. DOM checks are not visual inspection. A source comparison is not an infrastructure restore drill. Report each result at its actual scope.

# Review and release evidence

Keep changes reviewable and retain rollback inputs. Follow the repository’s actual license and contribution process; do not assume a contribution file or automation exists without checking. This workflow does not authorize opening, merging or deploying a contribution for someone else.