autodoc/docs/CONTRIBUTING.md

Contributing

Thanks for improving StepForge.

Before You Start

• Open or link the issue that describes the work.
• Keep the change small and focused.
• If the work does not have an issue yet, create one first so the PR can reference it.

Clean-Room Rules

StepForge is an independent reimplementation of publicly documented guide-capture workflow patterns. To keep it legally clean:

• Do not use the names, logos, icons, screenshots, or UI strings of commercial documentation products anywhere in code, assets, or docs.
• Do not copy wording from other products' documentation into the UI.
• Do not decompile, disassemble, or otherwise inspect proprietary binaries to derive behavior.
• Implement behavior from public descriptions and your own design only.
• Keep file formats (.sfgz, .sfglt, guide/step JSON) documented and versioned in docs/ and ARCHITECTURE.md.

Contributions are accepted under MPL-2.0 with a Developer Certificate of Origin sign-off (git commit -s).

Offline Rules

• No network code paths in the application. No telemetry, update checks, license checks, remote fonts, or remote APIs — ever.
• No new runtime dependencies without prior maintainer agreement; prefer internal implementations using Node built-ins.

Branching

• Use a branch name that includes the issue number, such as issue-123-update-readme.
• Keep unrelated cleanup in a separate branch, only have the fix in the branch.

Pull Requests

• Every pull request must reference an issue number in the body with Closes #123, Fixes #123, or Relates to #123.
• Summarize the change clearly and call out anything a reviewer should verify manually.
• Update docs when behavior changes, and add a CHANGELOG entry for every user-visible change.
• Every exporter or storage change requires tests; output changes require updated snapshot fixtures under tests/fixtures/.

Tests

Run the local checks before opening or updating a PR:

bash tests/run_test.sh

Put new shell checks in tests/checks/ so the shared runner picks them up automatically. The shell checks invoke the node --test workflow suites in tests/unit/.

Write tests that exercise real workflows and verify actual output — create a guide, export it, parse the bytes that came out — rather than grepping for magic strings.

The Gitea workflow in .gitea/workflows/tests.yaml runs the same command automatically on pushes and pull requests.

Please add lots of tests to each of your PR's and be descriptive with the tests so that the issue doesn't happen again or the feature doesn't get overwritten.

Review Checklist

• The PR is linked to the correct issue.
• The test suite passes locally.
• Any relevant docs or comments are updated.
• The change stays within the intended scope.
• The PR body explains any manual verification that is still needed.
• No network calls, no new dependencies, no trademarked assets.