如何为文档做贡献

注解

GitHub 地址:https://github.com/MegEngine/Documentation (欢迎 Star~)

MegEngine 文档的贡献者大致可参考以下几个方向(由易到难):

  • 在 MegEngine/Documentation Issues论坛 中提供各种各样建设性的意见;

  • 更正文档中的拼写错误(Typographical error,简称 Typo)或格式错误(Format error);

  • 更正文档中的其它类型错误,需要详细说明理由,方便进行讨论和采纳;

  • 帮助我们进行对 Python API 源码中文档字符串的翻译,参考 如何帮助翻译文档内容

  • 帮助我们将中文文档内容翻译成对应的英文版本,参考 如何帮助翻译文档内容

  • 帮助我们补充完善 文档内容 ,比如教程和指南,不断追求更高的质量。

你也可以浏览处于 Open 状态的 Issues 列表,从里面接下任务或找到一些灵感。

非开发人员的贡献方式

如果你发现了文档中一些很容易改正的细节错误(比如错字、格式不正确等), 但没有 GitHub 账号,或者不熟悉 MegEngine 文档的 GitHub 协作流程 , 觉得 Fork & Pull Request 等流程过于麻烦, 则可以通过 Issues、交流群和论坛等官方渠道友好地提出来,由我们负责进行后续处理。 我们会在对应的 Commit 中将你以共同作者(Co-author)的形式加入历史记录(需要提供 GitHub 用户名和邮箱):

$ git commit -m "Refactor usability tests.
>
>
Co-authored-by: name <name@example.com>
Co-authored-by: another-name <another-name@example.com>"

俗话说得好:“众人拾柴火焰高”,有时候发现问题比解决问题还重要,快来尝试一下吧~

警告

  • 这样的方法虽然简单直接,但 MegEngine 团队不能保证处理此类 Issues 的优先级;

  • 请勿将对文档(Documentation)的 Issues 提交到 MegEngine/MegEngine 存储库。

开发者的贡献方式

开发环境设置

注解

目前提供基于 GitHub Codespaces 云端开发(推荐)和 本地开发 两种模式。

如果你的网络环境能够流畅地访问 GitHub 服务,建议在云端进行开发。 打开 Documentation 存储库, 点击 Code -> Codespaces -> New codespace 自动启动实例,完成环境初始化。 在云端的 Visual Studio Code 中进行相关操作后,执行下面的命令构建文档,启动 WEB 服务进行验证:

>>> make html
>>> python3 -m http.server 1124 --directory build/html

将自动转发的端口可见性设置为公开(Public),可以方便他人在其它机器上进行审核;

  • Codespaces 支持同步 Visual Studio Code 设置或基于 dotfiles个性化设置

  • Codespaces 支持通过 Visual Studio Code Desktop 打开,开发者可按需选择使用方式。

源码组织逻辑

MegEngine 文档的源码结构如下:

Documentation
├── source   ├── _static           # 静态资源文件统一放在这里   ├── _templates
│   ├── getting-started   #########################   ├── user-guide        #  文档内容主要覆盖区域    #   ├── reference         #  与网页 URL 路径一致    #   ├── development       #########################   ├── conf.py
│   ├── favicon.ico
│   ├── logo.png
│   └── index.rst
├── build                 # 生成的文档一般在 build 目录   ├── doctrees
│   └── html
├── examples
├── locales               # Sphinx 多语言支持,内部结构和 source 高度对齐   ├── zh-CN             # 中文:主要需要翻译 API 的 Docstring 部分   └── en                # 英文:需要翻译除 API Docstring 外的全部内容
├── Makefile
├── requirements.txt
├── LICENSE
├── CONTRIBUTING.md
└── README.md

注解

与常见的软件文档 “以英文撰写原文,后续提供多语言翻译” 的逻辑不同, MegEngine 文档默认以中文作为原稿,后续提供其它语言的翻译版本。 但由于 Python 文档字符串 属于源代码注释的一部分,而代码注释提倡用英文撰写, 因此 MegEngine 中文文档中的 API 页面在自动生成时,将先从源代码提取出英文文档字符串, 再通根据对应的 locales/zh-CN/LC_MESSAGES/reference/api/*.po 文件中的翻译替换中文。 想要了解有关细节,可以参考 如何帮助翻译文档内容 页面。

警告

尽管单个的 API 页面是依据文档字符串的内容自动进行生成的, 但为了支持 APIs 的自定义排序,MegEngine 的 API 参考 中的各个列表是在 source/reference/*.rst 文件中人工进行维护的。

比如 functional.add 位于 source/reference/functional.rst 的 Arithmetic operations 分类。

新增 API 不应该出现在当前版本的文档中,所以在验证无误后,请提交到文档的 dev 分支, 与 MegEngine 的 master 分支对应。(如果更新了适用于新版本的教程或用户指南,方法同理。)

内容分类逻辑

MegEngine 的文档主要包括以下方面的内容:

  • 教程(Tutorial):指导读者通过一系列步骤完成项目(或有意义的练习)的课程;

  • 指南(Guide):引导读者完成解决常见问题所需步骤的指南(How-to 系列);

  • 参考(Reference):用于 API 查询和浏览,方便网络引擎检索的百科全书;

  • 解释(Explaination):对于特定主题、特性的概念性说明。

下面这张表格有助于我们理解它们之间的区别:

学习阶段

使用阶段

实践步骤

教程 🤔

指南 📖

理论知识

解释 📝

参考 📚

更多细节请参考 MegEngine 文档风格指南

GitHub 协作流程

高效清晰的沟通是合作的前提,标准的 MegEngine 文档协作流程如下:

  1. 创建一个 Issue,讨论接下来你打算进行什么样的尝试,交流想法;

  2. 一旦确定了初步方案,Fork 并 Clone 存储库,创建一个新的本地分支;

  3. 参照 风格指南语法规范 修改代码或文本,在本地构建与预览文档

  4. 按照 格式要求 记录 Commit 信息(需要使用 GitHub 账号);

  5. 确认所有改动符合预期后,Push 到你 Fork 的远端分支(Origin);

  6. 在 GitHub 创建一个 Pull Request 并向上游(Upstream)发起合并请求;

  7. 根据 Review 意见进行交流,根据需求在 Pull Request 中提交后续修改;

  8. 当你的分支被合并了,便可以删除对应的本地和远程分支。

我们还提供了更加详细的 Pull Request 的一生 (里面的规则适用于 MegEngine )。

注解

要求首先创建 Issue 进行讨论的原因是希望避免一些突如其来的 Pull Request 做无用功; 而具备一定经验的核心开发者可以直接提供一个草稿版本的 Pull Request 直接进行后续的讨论。

持续集成 & 部署逻辑

已经推送分支后,可以通过向 Documentation 的特定分支发起 Pull Request 来触发持续集成。

../../_images/megengine-ci.png

注解

  • 借助于 Build 工作流, 我们可以对整个文档的构建过程进行检查,确保能够正常生成整个文档网站。

  • 如果整个工作流成功执行完,你会在 Actions 对应的 workflow runs 结果页面中找到临时生成的构件(Artifacts), 里面是 HTML 形式生成的整个文档网站的压缩包,可以下载到本地后解压预览。

  • 同时,Gitpod Bot 也会为你的 Pull Request 提供一个云端 IDE 环境,并自动完成初始化和预览。

  • Pull Request 被合并到主分支后,将完成后续的部署,在下一次官网更新时能看到你的改动。

Pull Request 如何被合并

我们为 main 分支启用了保护规则,满足以下条件的 Pull Request 才能被成功合并(Merge):

  • 必须签署贡献者协议(Contributor License Agreement,简称 CLA);

  • 必须至少有一位官方维护人员审核(Review)完成并批准(Approve)了你的所有代码

  • 必须通过 Actions 中触发的状态检查(Status check),如 Build .

  • 必须将你的 Commits 历史记录整理为线性,消息内容符合 Commit message 书写指南

警告

签署 CLA 协议要求 commit 中所记录的 Author 账户都是 GitHub 上的账户。 如果你默认使用了非 GitHub 账户,建议使用 git config --local 命令配置。

注解

官网文档页面的更新将会有一定的处理流程延迟,请耐心等待官网服务器更新文档内容。