贡献

创建分支、修改源码、运行检查并提交 Pull Request。

本页目录

分支

先 fork Aitaide/OpenXTOS，再把 fork 克隆为 origin，把公开仓库设为 upstream。一个功能分支只处理一个问题；SDK 生成库、QEMU 日志和 .build 不能进入提交。

主机：把 YOUR-ACCOUNT 替换为自己的账户。此流程不提交也不创建 PR。

git clone https://github.com/YOUR-ACCOUNT/OpenXTOS.git
cd OpenXTOS
git remote add upstream https://github.com/Aitaide/OpenXTOS.git
git fetch upstream
git switch -c fix/guest-validation upstream/main
git rev-parse HEAD
git status --short

SDK、信号工具、构建脚本、验证、内核集成和文档都可以单独贡献。
先复现旧行为，再写触发条件和改后行为。
提交保持聚焦；feat:、fix:、docs: 等前缀可用于说明类型。

构建基线

主机需要 Linux 和约 10 GB 可用磁盘。Linux 与 BusyBox 源码已在仓库中。改动前先用未修改源码完成 x86_64 构建和 QEMU 自检。

主机：Debian/Ubuntu 基线；慢主机可使用 300 秒预算。

sudo apt-get update
sudo apt-get install -y build-essential flex bison bc libssl-dev libelf-dev libc6-dev python3 cpio gzip rsync kmod file qemu-system-x86
. ./scripts/reproducible_env.sh
JOBS=$(nproc) ./scripts/build_system.sh
QEMU_TIMEOUT=180 ./scripts/verify_system.sh

reproducible_env.sh 使用 HEAD 提交时间或 SOURCE_DATE_EPOCH，并设置 KBUILD_BUILD_VERSION、USER、HOST、TIMESTAMP、LC_ALL=C、TZ=UTC。它避免把当前时间、主机名和绝对路径写入产物。

内核与 UAPI

kernel/linux/ 是 Linux 6.6.0 源码树，已集成 PREEMPT_RT rt15 和 XTOS。内核组件改动要同步 kernel/patches/xtos-linux-6.6.patch；配置改动要比较 kernel/xtos_defconfig、olddefconfig 和最终配置。

边界	规则
内核与驱动	ARM64/RISC-V 使用 -mgeneral-regs-only；内核驱动和 UAPI 不加入浮点类型。
UAPI 同步	同时核对 kernel/linux/include/uapi/linux/xtos_bci.h、sdk/libxtos-bci/include/xtos/bci_uapi.h 和集成补丁。
整数和单位	input_range_mv 是 __u32/uint32_t，单位 mV；CHECK_IMP 是 32 个 __u32/uint32_t，单位 kOhm。
ioctl	核对命令号、结构布局、字段宽度和语义；编码大小相同也可能语义不同。
新用户态文件	sdk/、tools/、system/、scripts/、examples/ 新文件应带 SPDX-License-Identifier: Apache-2.0。
GPL 文件	kernel/linux/、kernel/patches/ 和 userspace/busybox/ 遵守各自 GPL-2.0 与已有 SPDX。

新 XTOS 用户态 C 文件；不要覆盖 GPL 文件原标记。

/* SPDX-License-Identifier: Apache-2.0 */

整数 UAPI 只限制内核边界，不限制用户态信号算法使用 double。kernel/xtos_defconfig 的许可证在 LICENSE-NOTICE 中单独列为 Apache-2.0，不能按 kernel/linux/ 的 GPL 规则概括。

ABI 版本

修改 sdk/<lib>/include/ 公共头文件时，按兼容性更新版本头和 Makefile。

三个库当前版本基线都是 1.0.0。

版本头维护 MAJOR、MINOR、PATCH、VERSION_STRING；Makefile 的 LIB_MAJOR/LIB_MINOR 决定文件名和 SONAME。

改动	版本	检查
移除符号、签名或结构破坏	增加 MAJOR。	版本头和对应 Makefile。
增加兼容符号	增加 MINOR。	libxtos-*.so.MAJOR.MINOR。
行为修复	增加 PATCH。	VERSION_STRING 与 PATCH 一致。
加载身份	SONAME 是 libxtos-*.so.MAJOR。	check_abi.sh 比较 SONAME、文件名和版本头。

主机：先构建原生 SDK；期望 abi_check=pass。

make -C sdk/libxtos-rt all test
make -C sdk/libxtos-signal all test
make -C sdk/libxtos-bci all
./scripts/check_abi.sh

提交前验证

提交前完成 x86 构建、QEMU 自检和 ABI 检查。影响 UAPI、内核、工具链或跨架构 rootfs 的改动还要完成对应交叉构建和严格 guest 检查。CI 配置不是本次改动的通过结果。

主机：运行原生 SDK、ABI 和源码检查。

. ./scripts/reproducible_env.sh
JOBS=$(nproc) ./scripts/build_system.sh
QEMU_TIMEOUT=300 ./scripts/verify_system.sh
make -C sdk/libxtos-rt all test
make -C sdk/libxtos-signal all test
make -C sdk/libxtos-bci all
./scripts/check_abi.sh
./scripts/verify_source_tree.sh
git diff --check
git status --short

主机：跨架构改动使用独立源码副本，按架构串行执行。

sudo apt-get install -y crossbuild-essential-arm64 libc6-dev-arm64-cross qemu-system-arm
JOBS=2 ./scripts/build_system_arm64.sh
QEMU_TIMEOUT=300 ./scripts/verify_guest_arm64.sh

sudo apt-get install -y gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu libc6-dev-riscv64-cross qemu-system-misc opensbi
JOBS=2 ./scripts/build_system_riscv64.sh
QEMU_TIMEOUT=360 ./scripts/verify_guest_riscv64.sh

verify_source_tree.sh 检查 Linux 版本、rt15、XTOS 必需源码和生成物污染。

generated_or_dependency 或 generated_in_bundled_kernel 指向生成物时，改用独立输出目录。

公开版本没有 scripts/test.sh，也没有 libxtos-bci 的 test 目标。

提交与 PR

用 git diff 和 git diff --check 检查范围，只暂存相关源码、头文件、补丁或文档。
提交说明写触发条件、旧行为、改后行为和兼容性影响。
推送功能分支，向 Aitaide/OpenXTOS 的 main 创建 Pull Request。
PR 写真实运行的命令、退出码、日志和标记；区分失败、未运行和无硬件。
公共接口改动附版本说明；内核改动附集成补丁同步和交叉验证结果。

主机：提交前审查范围，不使用 git add . 收集未知生成物。

git diff --check
git diff --stat
git diff
git status --short

issue 报告写主机 OS、工具链、源码提交、架构、精确命令和完整错误。启动问题附 QEMU 串口日志；设备问题写节点、权限、驱动绑定和真实硬件状态。

源码：CONTRIBUTING.md、README.md、.github/workflows/ci.yml、scripts/reproducible_env.sh、scripts/check_abi.sh、scripts/verify_source_tree.sh、三个 SDK Makefile/版本头以及内核和 SDK BCI UAPI。