Q+ 贡献指南（Contributing）

English summary. Contributor quick reference for Q+ 1.14.0-dev / spec v4.45 (candidate, NOT PUBLISHED): repo structure (see docs/REPO_LAYOUT.md), verified local commands (tools/build.sh, tools/test.sh, tools/robustness_test.sh, tools/test_qfmt.sh, tools/test_fs.sh, tools/test_async_io.sh, tools/test_float_parity.sh, tools/test_net_poc6.sh, tools/test_net_aot_p5.sh, consistency, package), the five build anchors + bootstrap/AOT fixed points, commit and authorization norms (no external account needed; push/merge/publication only with Maintainer authorization; Apache-2.0; no secrets/private paths/generated artifacts), safe codegen changes (self-hosting/bootstrap/AOT risk), stdlib/tests/docs/site procedures, and common errors (qboot miscompile, /tmp quota/EDQUOT, AOT no-exec-bit/loud unsupported, stale anchors). Full guide: docs/CONTRIBUTING.html.

快速参考

1. 先看结构与规则

目录职责/生成物/冻结区：仓库布局；
发布流程/门禁：发布工程指南；
规范/构建：语言规范 · BUILDING (EN)。

2. 本地验证命令（v240 实测）

mkdir -p .tmp && export TMPDIR="$PWD/.tmp"
bash tools/build.sh                  # 5 锚点；Phase 3: CodeGen ... [Q+ build] artifacts in ./build
bash tools/test.sh                   # QPLUS_LANGUAGE_TESTS_PASS
bash tools/robustness_test.sh        # ROBUSTNESS_PASS
bash tools/test_qfmt.sh              # QPLUS_QFMT_TEST: PASS=306 FAIL=0 SKIP=0
bash tools/test_fs.sh                # STD_FS_TEST_PASS (VM fs ops + AOT loud)
bash tools/test_async_io.sh          # P3B_ALITE: PASS=30 FAIL=0
bash tools/test_float_parity.sh      # FLOAT_PARITY_PASS
bash tools/test_net_poc6.sh          # NET_POC6_PASS ...
bash tools/test_net_aot_p5.sh        # AOT_NET_PHASE5_PASS
bash tools/check_release_consistency.sh --root .   # PASS=58 FAIL=0 SKIP=0
bash tools/package.sh ./.tmp/dist    # 确定性 tar + 私有词扫描（不发布）
cd site && python3 build_site.py --qplus-root .. && python3 ci/selftest.py

3. 固定点（v240，逐字节复现）

产物	sha256 前 8	大小
build/bqvm	`141e980b`	187,088 B
build/bqvm_small	`3e6eee3f`	187,088 B
build/qboot.qbc	`7248ce0d`	529,994 B
build/cgtest.qbc	`664d7648`	187,002 B
build/cgtest_aot	`235b0d3e`	1,989,608 B

bootstrap/qboot.qbc == build/qboot.qbc；bootstrap/cgtest_aot == build/cgtest_aot； bootstrap/stage0.q + bootstrap/SHA256SUMS 须通过。bootstrap 仅在批准的编译器/codegen 变更后刷新；禁止手工改锚点/跳测试/重打历史包。

4. 提交与授权

无需外部账号；push/merge/tag/发布需维护方授权（默认不得 push）；
不提交 build/、site/public/、.tmp/、__pycache__、EVIDENCE、密钥/私有路径；
Apache-2.0；签名/GPG 私钥永不入库；正式发布签名仅 Maintainer；
修改 codegen：先加 fixture、两次 clean build 比锚点、全量测试 + AOT/网络/浮点边界；固定点变更需批准并更新 bootstrap/BUILDING/spec/README；意外漂移=回归，回退/二分。

5. 常见错误

qboot 误编译 → 回退/最小复现加 fixture；/tmp 配额/EDQUOT → TMPDIR=$PWD/.tmp； AOT rc=5/无 ELF → 用了未支持能力（loud，用 VM 或查边界）；AOT ELF 无输出 → chmod +x 且 cgtest_aot in.qbc out.elf（位置参数）；Permission denied → bash tools/...； PRIVATE_WORD_SCAN_FAIL → 清理私有词；站点页数/checks 以实际构建为准。