Contributing to Q+

Thank you for your interest in Q+. This repository is the language-only Q+ project: compiler, bytecode VM, standard library, examples, tests, and specification. The a separate product line (另一产品线) kernel and OS services are a separate closed-source product line and are out of scope for this repository.

Q+ Language is maintained by Rudong Xinghan Technology Co., Ltd. (如东星瀚科技有限公司), brand 星瀚 / Xinghan.

Code of conduct

Participation is covered by CODE_OF_CONDUCT.md. Be respectful, constructive, and professional.

Project governance and release documents: GOVERNANCE.md, MAINTAINERS.md, SUPPORT.md, RELEASING.md, ROADMAP.md, P0_RELEASE_CHECKLIST.md, and GITHUB_READY.md. v1.4.8-dev is a release candidate (NOT PUBLISHED); do not claim or imply that a release exists.

Before you start

1. Read BUILDING.en.md and confirm that the toolchain builds and the regression suite passes on your machine:

   tools/build.sh
   tools/test.sh    # ends with QPLUS_LANGUAGE_TESTS_PASS

1. Check the issue tracker before starting significant work. For large language changes, compilation-strategy changes, or new standard-library modules, open an issue first so the approach can be discussed.
2. Read the relevant part of docs/qplus_language_spec.md. For language behavior, the specification is the source of truth; for usage guidance, see LANGUAGE_GUIDE.en.md.

Development workflow

1. Fork the repository and create a topic branch.
2. Make a focused change. Avoid mixing refactoring, formatting, and behavior changes in one pull request.
3. Build and test locally:

   tools/build.sh
   tools/test.sh

1. Commit with a clear message and a DCO sign-off (see below).
2. Open a pull request using the template in .github/PULL_REQUEST_TEMPLATE.md.

Developer Certificate of Origin (DCO)

Q+ uses the Developer Certificate of Origin (DCO) instead of a contributor license agreement (CLA). Every commit must be signed off, certifying that you wrote the change or otherwise have the right to submit it under the project's license.

Add the sign-off automatically:

git commit -s -m "Fix match exhaustiveness diagnostic"

This appends a line like:

Signed-off-by: Your Name <you@example.com>

The sign-off must use your real name and an email address you can be contacted at. Commits without a sign-off may be rejected. The full DCO 1.1 text is available at https://developercertificate.org/.

By submitting a contribution, you agree that it is licensed under the Apache License 2.0, the same license as the project (see LICENSE).

Test requirements

Every pull request must build and pass the regression suite. Run both commands before opening the pull request:

tools/build.sh
tools/test.sh

tools/test.sh enforces the following, so new or changed fixtures must follow these conventions:

Additional requirements:

• Every compiler fix needs a regression fixture under src/tests/ that fails before the fix and passes after it.
• Language changes must update the specification. If behavior described in docs/qplus_language_spec.md changes, update the document in the same pull request.
• Keep the type-error contract. A fixture named bad*.q must fail with exit status 4 and a [TC…] diagnostic; a fixture named parse_*.q must fail with exit status 2. Do not repurpose an existing fixture for a different failure mode.
• Do not weaken tests to make a change pass. If a test must change, explain why in the pull request.
• Both the compiler source and the standard library are compiled by the tests; a change that only works with a rebuilt bootstrap is not acceptable without a clear explanation.

The fixtures under src/tests/robustness/ exercise malformed input. They are not run by tools/test.sh in this release; extend them when fixing a crash or hang, and mention the fixture in the pull request description.

Coding guidelines

• Follow the style of the surrounding code. Q+ source uses // comments, four-space indentation, and one statement per line.
• Keep changes to the self-hosted compiler (src/compiler/qboot/qboot_v52_final3_fix2.q) minimal and well commented. This file compiles itself; a change that breaks self-hosting breaks every subsequent build.
• Use relative paths in shell scripts and resolve the repository root from the script location, as tools/build.sh and tools/test.sh do.
• Do not commit build artifacts. build/ is ignored by .gitignore.
• Do not add absolute paths, machine-specific assets, or paths from your local environment to any committed file.
• Keep diagnostics stable: existing error messages and exit statuses are part of the documented behavior and may be checked by fixtures.
• For standard-library additions, prefer a new module file in stdlib/std/ following the naming of neighboring modules, and make sure it compiles with tools/test.sh.
• Documentation changes are welcome. Keep the English guide (LANGUAGE_GUIDE.en.md) consistent with the specification.

Pull requests

A good pull request:

1. Has a short title in the imperative mood (for example, "Reject unqualified enum patterns in match arms").
2. Describes what changed and why.
3. States the tests that were run, with the commands and the result.
4. Describes compatibility and specification impact. Call out any change to language behavior, diagnostics, or exit statuses.
5. Links the issue it addresses, if one exists.
6. Is signed off (DCO).

The pull request template asks for a summary, a test checklist, and a compatibility/spec-impact note. Please fill in all three sections.

Maintainers review for correctness, test coverage, specification alignment, and backward compatibility. Changes that affect language semantics may require a specification update before merge. CI runs tools/build.sh followed by tools/test.sh on every push and pull request; a red CI run must be resolved before merge.

Security issues

Do not open public issues for security problems. Follow the private reporting process in SECURITY.md.

Questions

If something in this repository is unclear, open an issue using the issue templates with the exact command, expected behavior, and actual output. For general language questions, check FAQ.en.md and LANGUAGE_GUIDE.en.md first.