贡献指南

HiDiTingV100 社区欢迎开发者改进文档、修复示例、补充新的业务场景。本文说明从发现问题到提交合并请求的完整流程，并给出文档与 Demo 的统一验收要求。

贡献范围

类型	适合提交的内容	提交时需要同步检查
文档修正	错别字、失效链接、错误锚点、描述不准确、图片缺失	目录、上下文、相关页面和 Web 预览
文档增强	背景知识、快速跑通、代码走读、故障排查	SDK 接口、Demo 路径、命令和预期结果
Demo 修复	编译错误、资源泄漏、不安全函数、异常路径缺失	README、构建配置、运行日志和对应开发指南
新增 Demo	可独立构建的 Native 或 JS 示例	工程结构、接入目标、README、开发指南和验证记录

仓库与目录

贡献目标仓库为 GitCode 上的 HiSpark/hs-fbb，主要目录如下。

目录	用途
/docs/zh-CN/HiDiTingV100/	中文开发文档源文件
/samples/native_samples/	Native 示例工程
/samples/js_samples/	OpenHarmony JS 示例工程
/src/	SDK 组件、接口与内置实现

Web 文档由独立部署仓同步生成。文档正文只能链接 /docs/ 内可随站点发布的页面和图片；SDK 与 Demo 使用 /src/、/samples/ 开头的路径文字说明，不创建从文档站反向跳往代码文件的本地链接。

提交流程

1. 在 GitCode 确认问题是否已经存在；修复缺陷时，在问题描述中记录复现条件和影响范围。
2. Fork HiSpark/hs-fbb，从最新 master 创建短期分支。
3. 修改文档或代码。涉及功能流程时，文档、Demo README 和构建配置应在同一变更中保持一致。
4. 在本地完成对应检查；不要只验证单个 Markdown 的预览效果。
5. 提交变更并创建合并请求，说明修改原因、验证方法、验证结果和暂未覆盖的条件。
6. 根据评审意见更新原分支，不重复创建表达同一目的的合并请求。

推荐分支名称：

docs/<topic>
fix/<module>-<issue>
sample/<feature>

文档贡献规范

新增开发指南可从开发指南模板开始，并遵循以下要求。

结构

• 每篇文档只保留一个一级标题。
• 开发指南至少说明适用范围、准备条件、快速跑通、核心流程、基于 Demo 开发、注意事项和常见问题。
• Web 站点根据正文标题自动生成页面目录，不在文档开头重复维护手写“目录”章节；正文确需跨章节引用时，使用稳定且能在 Web、GitCode 和常用编辑器中一致解析的锚点。
• 分类 README.md 负责导读，子文档负责完整流程，避免在多个页面复制同一大段正文。

链接与路径

• 文档仓内部链接使用相对路径，并在移动或重命名文件后同步更新所有入口。
• 引用 SDK 或 Sample 时直接链接到 GitCode 的源码目录或示例目录。文件使用 blob 地址，目录使用 tree 地址；需要精确定位时追加 #L行号，不在正文中只写源码路径，也不创建从 docs 反向跨到代码目录的相对链接。
• 需要精确定位代码行时，可在 GitCode 文件链接后使用 #L行号。由于 master 分支的行号会随代码变化，长期有效的精确行链接应固定到发布标签或提交号；持续更新的开发指南优先链接到文件本身。
• 外部链接优先使用长期稳定的官方页面，并说明链接用途。
• 提交前检查图片、文档、锚点和外部链接；不能以“稍后补充”替代有效目标。

图片

• 图片放在所属文档附近的 figures 目录，文件名使用能够表达内容的中文名称。
• 每张图片提供准确的替代文本；替代文本描述图片内容，不写“图片1”之类的编号。
• 保留原始宽高比，不拉伸、不使用空白占位图，不在图片内重复正文可表达的大段文字。
• 常规正文图片由 Web 站点统一居中和限制最大宽度；只有确有排版需要时才单独指定尺寸。

描述与代码片段

• 参数、返回值、宏、组件名和日志必须与当前 SDK 或 Demo 一致。
• 代码片段只保留理解业务所需的核心数据结构和关键调用，完整实现通过 /samples/ 或 /src/ 路径说明。
• 示例必须包含初始化、正常调用、失败处理和资源释放；省略代码时明确省略的内容，不使用无法编译的伪代码冒充完整示例。
• AT 命令可以作为串口调试或板端回归入口，但不是非 AT 业务功能的必要组成部分。

Demo 贡献规范

新增或修改 Demo 时至少满足以下要求。

1. 工程目录包含 README.md，说明功能、目录结构、依赖、构建目标、运行方法、预期日志和故障排查。
2. 构建脚本、组件名称、配置宏和源文件路径真实存在，大小写完全一致。
3. 内存和字符串操作使用 SDK 支持的安全接口，并检查会影响业务正确性的返回值。
4. 初始化失败、任务退出和重复运行路径能够释放句柄、内存、线程、定时器及外设资源。
5. Native Demo 至少通过当前社区目标的编译验证；涉及硬件或双设备的场景，还应写明接线和验证角色。
6. JS Demo 同时检查工程配置、签名要求、权限声明、页面生命周期和安装运行结果。
7. 对应开发指南给出“快速跑通”和核心流程走读，并明确 Demo 归档路径。

提交信息

提交信息应简洁表达类型、模块和目的，例如：

docs: 修正 USB 指南中的枚举流程
fix(audio): 释放初始化失败路径的缓冲区
sample(rtc): 增加 RTC 独立运行示例

一个提交尽量只处理一个可独立评审的主题。格式化产生的大面积无关变化应与功能修改分开。

合并请求说明

合并请求至少填写以下内容：

• 问题和修改目标。
• 涉及的文档、组件、Demo 和构建目标。
• 实际执行的检查、编译或板端验证步骤。
• 关键日志、截图或可观察结果。
• 未验证的硬件条件或外部服务条件。
• 是否需要同步 Web 文档导航、版本说明或其他关联页面。

提交前检查表

• 文档和代码使用 UTF-8，文件名、目录名不包含空格。
• 一级标题、目录、标题层级和锚点正确。
• 文档链接、图片链接和外部链接有效。
• 文档没有链接到 /docs/ 之外的本地文件。
• 图片命名、替代文本、对齐和尺寸符合规范。
• Demo README、构建配置和开发指南相互一致。
• 示例能够编译；具备条件时已经完成板端运行验证。
• 没有提交构建产物、临时文件、账号、密钥或证书。
• 已在合并请求中说明验证范围和已知限制。

当前文档基线及更新记录参见版本说明。