Contributing

Contributing

This is a beta prerelease 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 remains disabled in this repository and no beta workflow is published. Maintainers run applicable local release checks and retain the evidence; see the final beta review for the two 373-test macOS suites and their six documented skips. 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 beta prerelease notice. Current template source keeps published PDF/image references and reusable operating files. Film, audio, and paper-authoring tools belong to the separate production archive. The historical alpha.5 publication security tests describe the retired authoring component; they are not a current runtime test command. Build future publication drafts in their own workspace and preserve the exact identity of already published editions.

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.