当前位置：首页 > news >正文

CANN/opbase文档贡献指南

news 2026/5/9 15:02:14

文档贡献指南

【免费下载链接】opbase本项目是CANN算子库的基础框架库，为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase

欢迎您对本项目文档做出贡献，优质的文档对于项目成功至关重要。本指南将帮助您高效地提交符合规范的文档。

贡献范围

我们欢迎任何能提升文档质量的贡献，包括但不限于：

纠错与改进：修复错别字、语法错误、错误的代码示例、过时的信息或失效的链接。
澄清与优化：让描述更清晰易懂，优化语句结构，补充背景知识。
内容补充：为现有功能添加使用示例、API文档、常见问题解答（FAQ）、最佳实践或警告说明等。
新内容创作：为新增功能撰写全新的章节或教程，比如README、API介绍文档等，如有问题建议先创建Issue讨论。
本地化翻译：帮助我们翻译或校对其他语言的文档。
样式与导航：改进文档网站的布局、可读性和导航结构。

贡献流程

准备工作
- 确定任务：如有文档问题可新建Issues，建议标签类别[Documentation|文档反馈]，并提供详细描述。基于已有Issues列表，确定待解决的文档issue。
- 认领任务：在对应的Issue下评论/assign @yourself，表明您将处理它，避免重复劳动。
文档修改
- 选择分支：请从master或其他Tag分支下载源码到本地。
- 遵循格式：
  - 本项目推荐使用Markdown格式。
  - 遵循项目既有的写作风格。
  - 图片等静态资源放入对应目录，例如图片一般在docs目录下figures文件夹，特殊情况可自行调整。
- 谨慎增删：修改内容时，请尽量保持原有的行宽和换行约定。
提交更改
- 原子化提交：每个提交应专注于一个独立的修改。例如，“修复xx指南的拼写错误”和“更新API参考的示例代码”应分两次提交。
- 撰写清晰的提交信息：
```
简短说明（不超过50字符） 如有必要，在此处进行更详细描述。说明修改的原因和内容，而不是具体改了什么（代码本身会展示）。 关联的 Issue: #123
```
发起Pull Request
- 目标分支：请将PR合并到项目的目标分支。
- 标题与描述：
  - PR标题：应清晰概括修改，例如：[Docs] 修复快速入门中的配置示例。
  - PR描述：详细说明您的更改内容、动机，并关联对应Issue（使用Closes #123或Fixes #456）。
- 预览检查：请提前检查本地或在线浏览的文档效果，确保渲染符合预期。
- 等待审查：维护者会进行审查，可能会提出修改建议。请及时跟进讨论。

写作规范

开发者进行项目文档写作前，请务必先阅读如下规范，如有问题欢迎您随时提出建议！

前提条件：请先学习CANN组织提供的统一写作规范，具体参见CANN文档写作规范。
- 文档内容要求：介绍项目里必选和可选文档交付件。
- 目录结构规范：介绍目录划分的原则，例如中、英文管理等。
- 内容元素规范：介绍不同写作元素的规则，例如文件命名、标题、字体、图片、代码块、链接等。
注意事项：
除了上述写作规则，还需注意以下事项：
- 语气：使用友好、专业且中立的语气。面向新手，避免不必要的行话。
- 术语：保持术语一致性（如统一使用“点击”而非“单击”）。请参考项目术语表（如有）。
- 代码示例：
  - 确保所有代码示例可运行并经过测试。
  - 提供足够的上下文和解释。
  - 注明代码运行所需的环境或前提条件。
- 标点与格式：
  - 中英文混排时，使用全角标点，标点符号必须符合中/英文语境。
  - 标题使用合适的层级（#、 ##、 ###）。
  - 使用列表和表格来组织复杂信息。
- 链接：使用描述性链接文本，避免“点击这里”，确保链接资源真实可靠。
- 图片：
  - 常用格式：推荐png格式，风格尽量与已有图片保持一致。
  - 分辨率与清晰度：需清晰且尺寸适中，避免模糊或过度压缩。
  - 文件大小：单张图片不建议超过10M。
- 版权：所有引用的图片、文献等资源，请确保合规性。