参与Zeal 8-bit OS开源贡献：路线图、贡献规范与提PR完整指南

参与Zeal 8-bit OS开源贡献：路线图、贡献规范与提PR完整指南

【免费下载链接】Zeal-8-bit-OSAn Operating System for Z80 computers, written in assembly项目地址: https://gitcode.com/gh_mirrors/ze/Zeal-8-bit-OS

Zeal 8-bit OS 是一个完全用 Z80 汇编语言编写的 8 位操作系统，专为 Z80 计算机设计，强调简单、可移植且可烧录进 ROM。无论你是 Z80 汇编爱好者、复古计算机玩家，还是想为开源操作系统贡献力量的新手，这篇Zeal 8-bit OS 开源贡献指南都能帮你理清项目路线、掌握贡献规范，并顺利完成第一个 Pull Request。本文将从项目现状出发，一步步带你走完从克隆代码到合并上线的完整流程，让你第一次提 PR 就心中有数。🚀

为什么值得参与 Zeal 8-bit OS 开源贡献？

Zeal 8-bit OS 的设计理念深受 Linux 与 CP/M 启发，但比它们更轻量：当前内核编译后代码不足 8KB、数据不足 1KB，单线程、模块化、可配置，还内置了虚拟文件系统（VFS）、驱动体系和 syscall 系统调用机制。对开发者来说，它是一片非常适合学习和实践的“小而美”代码库。

参与这个Z80 操作系统开源项目，你将收获：

• 🧠深入学习 Z80 汇编：整个内核、驱动、文件系统都由汇编写成，是最好的实战教材
• 🛠️理解操作系统原理：内存映射、系统调用、VFS 分层、磁盘与文件系统一应俱全
• 🌍结识复古计算社区：项目已支持 Zeal 8-bit Computer、TRS-80 Model-I、Agon Light 等平台
• 📈积累开源经验：从提 Issue、改 Bug 到合并 PR，完整走一遍协作流程

Zeal 8-bit OS 项目路线图：现在在哪、未来去哪

已经实现的核心能力 ✅

• 单线程内核，整颗 CPU 专供一个用户程序运行
• 最多支持 26 个磁盘（A~Z），ROM 可直接引导
• 文件、目录、驱动、实时时钟（RTC）与定时器
• 20+ 个 syscall，涵盖读写、打开、seek、ioctl、exec、内存映射等
• 文件系统：rawtable 与 ZealFS（v1/v2，v2 支持最大 4GB 分区）
• MMU 与 no-MMU 两种内核模式，可在 menuconfig 中自由选择
• 模块化构建系统：新增文件与目标平台非常方便

值得关注的开发方向 🔭

项目路线图中仍有大量空白等待贡献者填补，这正是你大展身手的地方：

• FAT16 文件系统：官方明确列为“Almost a must-have”，尚未实现，属于高价值目标
• 新平台移植：官方文档详细给出了移植步骤，可参考docs/supported-targets.md
• TRS-80 Model-I 完善：目前仅实现了文本模式视频驱动，键盘、磁盘驱动都待开发
• GPIO 用户接口 / 硬件定时器：在 Zeal 8-bit Computer 目标上仍标记为待实现

💡 想知道最值得动手的方向？先阅读 docs/supported-targets.md 中的“What still needs to be implemented”清单，再结合自身硬件条件选择。

贡献规范：提交前必须知道的规则

代码仓库结构速览

在动手之前，先熟悉仓库目录，能帮你快速定位改动位置：

• kernel/：内核核心代码，含 syscalls.asm、vfs.asm、disks.asm 等
• kernel/fs/：文件系统实现，如 zealfs_v2.asm、mbr.asm
• kernel_headers/：面向用户程序的公开头文件与示例，支持 SDCC、z88dk-z80asm、GNU AS 三种工具链
• romdisk/init/：开机自带的 init 程序（命令行工具集），如 ls.asm、cat.asm
• configs/：各目标平台配置（zeal8bit、trs80、agon）
• cmake/、tools/：构建系统与打包脚本

许可证与代码规范 📄

项目采用Apache 2.0 License，可自由用于个人与商业用途，但每个文件中的版权头不得移除。提交代码时请保持与现有汇编代码一致的风格：清晰的标签命名、必要的注释、遵循 syscall 参数约束（缓冲区不得跨越 16KB 虚拟页）。

提 PR 完整指南：从克隆到合并的五步流程

第一步：克隆仓库并准备环境

首先将仓库克隆到本地：

git clone https://gitcode.com/gh_mirrors/ze/Zeal-8-bit-OS

构建环境需要：bash、git、CMake 3.16+（推荐）或 GNU Make 4+、Python3 与 pip3（用于 menuconfig），以及 z88dk v2.2+（其z80asm汇编器是核心依赖）。Ubuntu 下可用以下命令安装：

sudo apt install git python3 python3-pip pip3 install --ignore-installed --user kconfiglib

第二步：Fork 并创建功能分支

1. 在 GitCode 上将项目 Fork 到自己的账号下
2. 将 Fork 后的仓库添加为 remote，并创建功能分支（官方建议，非强制）
3. 分支命名建议体现改动主题，如feat/fat16-read-only或fix/trs80-keyboard

第三步：本地编译验证改动

进入项目根目录，用 menuconfig 生成配置：

make menuconfig

全部选项都有默认值，不确定时直接按S保存为os.conf，再按Q退出。接着编译：

make

看到OS binary: build/os.bin即表示内核构建成功；os_with_romdisk.img则包含内核与 romdisk，可直接烧录。改动涉及内核或驱动时，务必保证编译通过、回归无异常。

第四步：写出规范的提交信息 ✍️

提交信息要清晰简洁，官方推荐的格式是：

模块: 对 a 的 add/fix/remove 操作 说明做了什么、如何做、为什么

例如：

Disks: implement a get_default_disk routine It is now possible to retrieve the default disk of the system.

好的提交信息能让维护者快速理解改动意图，显著提升 PR 合并速度。

第五步：Push 并创建 Pull Request

1. 将本地分支推送到你的 Fork 仓库
2. 发起 Pull Request，目标分支选择原项目的默认分支
3. 在 PR 描述中写清楚：改了什么、为什么改、如何测试，必要时附上编译日志与运行截图

新手该从哪里开始贡献？推荐清单

如果你还不太熟悉 Z80 汇编，不妨从这些低门槛任务入手：

• 📝完善文档：docs/目录下的 getting-started.md、system-calls.md 都值得补充示例与细节
• 🐛修复简单 Bug：在 romdisk 命令工具（echo.asm、ls.asm 等）中寻找边界问题
• 🧪新增示例程序：参考 kernel_headers/examples/ 下的三种工具链示例，补充更多 demo
• 🔌编写驱动：熟悉DRV_VECTORS段与驱动结构后，可为目标平台补充键盘、存储等驱动

常见问题 FAQ

Q：不会 C 语言，能参与贡献吗？A：完全可以！Zeal 8-bit OS 的内核与驱动全部用 Z80 汇编编写，汇编能力才是核心技能；文档与测试类贡献则几乎零门槛。

Q：改动会影响其他平台吗？A：内核代码与目标平台代码分离，新增驱动或移植新平台时尽量只改configs/对应目录，避免影响既有目标。

Q：提交 PR 前必须完整测试吗？A：至少保证编译通过并完成基本功能验证；涉及硬件相关改动时，请注明测试环境与结果，方便维护者复现。

Q：在哪里了解最新的开发规划？A：项目根目录的 Kconfig 与kernel/Kconfig展示了全部可配置项，docs/目录下的 details/ 系列文档则详细说明了内核、驱动、VFS 等模块的设计。

结语

参与Zeal 8-bit OS 开源贡献并不难：一份清晰的路线图让你知道该做什么，一套简洁的贡献规范让你知道怎么做，而完整的 PR 流程则确保你的努力能顺利落地。无论你是想精进汇编功力，还是单纯享受复古计算的乐趣，这个用纯汇编写成的 8 位操作系统都值得你投入时间。现在就克隆仓库、跑一次编译、从修复一个小 Bug 开始你的第一个 Pull Request 吧！🌟

【免费下载链接】Zeal-8-bit-OSAn Operating System for Z80 computers, written in assembly项目地址: https://gitcode.com/gh_mirrors/ze/Zeal-8-bit-OS