Contributing

Contributing

This is an alpha project. Review the canonical contribution guide, release policy, and security and support. Alpha1 contains the integrated branch history; main remains the public default. Released tags are retained. Keep feature branches temporary and remove them once their work is included in both standing branches and no open pull request or worktree needs them.

Contributions should make .SYSTEMX clearer, more reliable, or easier to adopt while preserving its stack-neutral scope.

Useful contributions

• Corrections to instructions, examples, links, or error explanations.
• Focused fixes supported by a reproducible failure and relevant verification.
• Improvements to task consistency, context loading, or project portability.
• Simpler standards and templates that solve a demonstrated project need.

Discuss changes that introduce a new runtime, hosted service, mandatory provider, or major coordination model before implementing them. Keep application-specific features and individual project records out of the reusable base.

Development workflow

1. Inspect the current standard, relevant code, and existing tests.
2. Use a branch or fork for the scoped change.
3. Keep reusable project records blank. Exercise task and agent workflows in temporary copies rather than adding sample work to the distributed ledger.
4. Update affected documentation alongside behavior.
5. Run the relevant verification and explain the result in the pull request.

python3 -I -B .SYSTEMX/scripts/release.py
bash .SYSTEMX/SYSTEMX.sh validate
python3 -I -B .SYSTEMX/scripts/release.py --check
python3 -I -B -m unittest discover -s .SYSTEMX/tests -v
git diff --check

For documentation changes, also check the actual links, command examples, and rendered GitHub page. Do not add a test merely to repeat static prose. Review FORMAT.md when changing canonical fields or lifecycle rules. Update blank seed hashes only for deliberately reviewed prompt changes; never rebaseline populated project records. Validate the extracted, tracked-file export before publication so ignored runtime artifacts are not shipped.

Rebuild the distribution manifest after intentional source edits, then review it. Keep the blank-seed fingerprint review separate. GitHub Actions is disabled; maintainers run release checks locally and retain the evidence. Check applicable Python and operating-system combinations, validate wheel contents, and test a real installation from the built package before publishing a tagged release. Put release IDs and change history in Versions and changelog, leaving the README focused on public adoption and the current alpha notice. The publication builders anchor outputs to an opened POSIX directory and reject linked final paths. Build a separate draft; a published same-edition PDF cannot be replaced in place. Run the publication security tests when changing the white-paper tools.

Pull requests and bug reports

Describe the concrete problem, resulting behavior, and evidence that the change works. Include reproduction steps, the affected template version, operating system/runtime where relevant, and sanitized output. Record limitations instead of implying broader coverage than the checks provide.

Use the issue tracker for ordinary bugs and proposals. Keep secrets, credentials, customer data, and private security details out of public reports.

Maintain documentation sources

The root README introduces the distribution. The .SYSTEMX documents remain self-contained for people copying the operating folder into another project. The wiki provides longer guides and links back to canonical files.

GitHub stores wiki content in its own Git repository. Maintainers can edit it locally and push changes to its default branch, following GitHub's wiki editing guide. Update related guide pages and navigation together.

License and provenance

Contributions are made to the independent WayneTechLab/dotSYSTEMX repository. The original upstream template remains separately maintained. Preserve the MIT license notice and keep SOURCE.json accurate about the original source and extraction scope.