Iisyourdad
70d812007f
- Environment audit and stack decision in build/agent_audit.md (Node + Electron shell over dependency-free core; deviation recorded) - Rewrite README/ARCHITECTURE/CONTRIBUTING for StepForge - Add SECURITY.md threat model, CODE_OF_CONDUCT.md, CHANGELOG.md, MPL-2.0 - Replace template grep checks with structural workflow check Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
# 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
|
|
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.
|