FreeBSD 状态报告流程

版权所有 © 2023 FreeBSD 文档项目
商标

FreeBSD 是 FreeBSD 基金会的注册商标。

Git 和 Git 徽标是软件自由保护协会（Git 项目的法人实体）在美国和/或其他国家/地区的注册商标或商标。

GitHub 是 GitHub Inc. 的商标，在美国和其他国家/地区注册。

制造商和销售商用于区分其产品的许多名称被认定为商标。在本文档中出现这些名称时，如果 FreeBSD 项目了解商标权利声明，则这些名称后面将加上“™”或“®”符号。

目录

FreeBSD 状态报告每季度发布一次，向公众提供对项目进展的了解，并经常由开发者峰会的特别报告补充。由于它们是我们最可见的沟通形式之一，因此非常重要。

在本文件中以及其他与 FreeBSD 状态报告相关的地方，状态报告一词既表示定期发布的文档，也表示其中包含的单个条目。

1. 写作说明

本节提供了一些关于撰写状态报告条目的建议，来自 David Chisnall，他是一位经验丰富的技术写作人员。此外，还提供了关于如何提交条目的说明。

如果您不是英语母语人士，请不要担心。 状态团队 将检查您的条目是否有拼写和语法错误，并为您修正。

1.1. 介绍您的工作

不要假设阅读报告的人了解您的项目。

状态报告的传播范围很广。它们通常是 FreeBSD 网站上的热门新闻项目之一，也是人们了解 FreeBSD 的一些基本信息时的首选阅读资料。请考虑以下示例：

abc(4) support was added, including frobnicator compatibility.

如果读者熟悉 UNIX 手册页，他们会知道 abc(4) 是一种设备。但为什么要关心呢？它是什么类型的设备？请比较一下这个版本：

A new driver, abc(4), was added to the tree, bringing support for
Yoyodyne's range of Frobnicator network interfaces.

现在读者知道 abc 是一个网络接口驱动程序。即使他们不使用任何 Yoyodyne 产品，您也已经传达了 FreeBSD 对网络设备的支持正在改进这一信息。

1.2. 展示工作的重要性

状态报告不仅仅是告诉每个人事情已经完成，还需要解释为什么要完成这些事情。

继续之前的例子。为什么我们现在支持 Yoyodyne Frobnicator 卡会很有趣？它们很普遍吗？它们被用于特定的流行设备吗？它们被用于 FreeBSD 拥有（或希望拥有）影响力的特定利基市场吗？它们是地球上最快的网卡吗？状态报告通常会这样说：

We imported Cyberdyne Systems T800 into the tree.

然后他们就停下了。也许读者是狂热的 Cyberdyne 粉丝，知道 T800 带来了哪些令人兴奋的新功能。这是不太可能的。他们更有可能只是听说过您导入的任何东西（尤其是导入到 ports 树中的内容：请记住，那里还有 30,000 多个其他东西……）。列出一些新功能或错误修复。告诉他们为什么拥有新版本是一件好事。

1.3. 告诉我们一些新的内容

不要重复使用相同的状态报告项目。

请记住，状态报告不仅仅是关于项目状态的报告，也是关于项目状态变化的报告。如果有一个正在进行的项目，请用几句话介绍它，但接下来的部分要重点介绍新的工作内容。自上次报告以来取得了哪些进展？还有什么工作要做？预计何时完成（或者，如果“完成”不适用，预计何时可以更广泛地使用、测试、在生产中部署等）？

1.4. 赞助

不要忘记您的赞助商。

如果您或您的项目获得了赞助、奖学金，或者您已经是某个公司的承包商或雇员，请将其包含在内。赞助商当然会很感谢您感谢他们的资金，但这也有助于他们表明他们正在通过这种方式积极支持该项目。最后但并非最不重要的是，这有助于 FreeBSD 更多地了解其重要客户。

1.5. 待办事项

如果需要帮助，请明确说明！

是否需要帮助？是否有其他人员可以完成的任务？您可以通过两种方式使用状态报告的待办事项部分：征求帮助，或快速概述剩余的工作量。如果已经有足够的人员参与项目，或者项目处于添加更多人员不会加速进展的状态，那么第二种方法更好。列出一些正在进行的大型工作项目，并可能指出谁是负责每个项目的人。

列出任务，并提供足够的细节，让人们知道他们是否有可能完成这些任务，并邀请他们联系您。

1.6. 提交您的报告

以下方法可用于提交您的报告：

  • 提交 Phabricator 评审 并将 status 组添加到评审者列表中。您应该将您的报告放在 doc/website/content/en/status/ 的相应子目录中（如果不存在则创建它）；

  • 通过 其 GitHub 镜像 向 doc 存储库提交拉取请求。您应该将您的报告放在 doc/website/content/en/status 的相应子目录中（如果不存在则创建它）；

  • 向 status-submissions@FreeBSD.org 发送一封电子邮件，其中包含您的报告。

您可以参考 AsciiDoc 样例报告模板。

2. 编辑说明

本节介绍了评审和发布流程的工作原理。

状态报告主页

https://freebsd.ac.cn/status/

状态报告存档 GitHub 存储库（用于 2017Q4 到 2022Q4 的报告）

https://github.com/freebsd/freebsd-quarterly

状态团队主要电子邮件地址

status@FreeBSD.org

报告提交的电子邮件地址

status-submissions@FreeBSD.org

接收状态报告征集邮件的邮件列表

freebsd-status-calls@FreeBSD.org

Phabricator 状态团队主页

https://reviews.freebsd.org/project/88/

2.1. 时间线

状态团队始终接受报告提交，但主要收集流程在每个季度的最后一个月进行，即 3 月、6 月、9 月和 12 月。这些月份将发送明确的状态报告征集邮件。1 月、4 月、7 月和 10 月则用于整理上一个季度提交的报告；这可能包括等待延迟提交的报告。状态报告的发布时间与报告准备完毕的月份相同。

所有报告提交的截止日期都可以通过 向状态团队发送电子邮件 延长，直到延长后的截止日期，即季度结束后的 8 天。由于状态报告与季度 ports 分支之间存在重叠，因此来自 ports 管理团队 的条目默认为延长后的截止日期。

非状态团队成员对提交的报告的评审应在 1 月中旬/4 月中旬/7 月中旬/10 月中旬（第三方评审缓冲期）基本完成。也就是说，除了打字错误或其他轻微的校对之外，状态团队应该能够在 15 日之后不久开始整理提交的报告。请注意，这并非完全冻结，状态团队可能仍然能够在此时接受评审。

第一季度第二季度第三季度第四季度

首次征集报告

3 月 1 日

6 月 1 日

9 月 1 日

12 月 1 日

剩余 2 周提醒

3 月 15 日

6 月 15 日

9 月 15 日

12 月 15 日

最后提醒

3 月 24 日

6 月 24 日

9 月 24 日

12 月 24 日

标准截止日期

3 月 31 日

6 月 30 日

9 月 30 日

12 月 31 日

延长截止日期

4 月 8 日

7 月 8 日

10 月 8 日

1 月 8 日

第三方评审缓冲期

4 月 15 日

7 月 15 日

10 月 15 日

1 月 15 日

2.2. 征集报告

状态报告征集邮件将发送给以下收件人：

  • freebsd-status-calls@FreeBSD.org 邮件列表；

  • 所有上次状态报告的提交者（他们可能会有更新或进一步的改进）；

  • 以及根据季节

    • 各种会议组织者

      • AsiaBSDCon 3 月份（第一季度）；

      • BSDCan 5 月份（第二季度）；

      • EuroBSDcon 9 月 - 10 月（第三、第四季度）。EuroBSDcon 作为组织并不想为 FreeBSD 撰写报告（至少在 2019 年 10 月之前是这样：其原因是该会议不是 FreeBSD 特定的），因此应向参加该会议的 FreeBSD 社区成员征集有关该事件的报告；

    • Google Summer of Code 学生 及其 导师。

发送状态报告请求的最简单方法是使用 sendcalls perl 脚本，该脚本位于 doc git 仓库的 tools/sendcalls 目录中。该脚本会自动向所有目标接收者发送请求。它也可以通过 cron 作业使用，例如

0      0       1,15,24 3,6,9,12        *       cd ~/doc/tools/sendcalls && git pull && ./sendcalls -s 'Lorenzo Salvadore'

如果您负责发送状态报告请求，并且确实使用 cron 作业，请在 freefall 上运行它并使用您的姓名进行签名，以便在出现问题时可以推断出谁配置了 cron 作业。此外，请使用您的姓名更新上面的示例，作为额外的安全措施。

您也可以考虑在论坛上发布报告请求，就像 过去所做的那样。

2.3. 构建报告

提交的报告将在它们被提交时被审核并合并到 doc/website/content/en/status/ 的适当子目录中。在报告被更新时，状态团队以外的人员也可以查看各个条目并提出修正建议。

通常，内容审核过程的最后一步是在名为 intro.adoc 的文件中编写引言：只有在收集完所有报告后才能编写一个好的引言。如果可能的话，建议让不同的人来编写引言，以便增加多样性：不同的人会带来不同的观点，并有助于保持引言的新鲜感。

一旦所有报告和引言都准备就绪，就需要创建 _index.adoc 文件：该文件用于将报告分配到不同的类别并进行排序。

2.4. 发布报告

当状态报告的所有文件都准备就绪后，就可以发布它了。

首先，编辑 doc/website/content/en/status/_index.adoc：更新下一个截止日期，并添加指向新报告的链接。然后将更改推送到仓库，状态团队会检查一切是否按预期工作。

然后，将主网站页面的新闻条目添加到 doc/website/data/en/news/news.toml 中。

以下是新闻条目的示例

[[news]]
date = "2021-01-16"
title = "October-December 2020 Status Report"
description = "The <a href=\"https://freebsd.ac.cn/status/report-2020-10-2020-12.html\">October to December 2020 Status Report</a> is now available with 42 entries."

一旦报告的 HTML 版本构建完成并上线，就使用 w3m(1) 将网站转储为纯文本，例如

% w3m -cols 80 -dump https://freebsd.ac.cn/status/report-2021-01-2021-03/ > /tmp/report-2021-01-2021-03.txt

w3m(1) 具有完整的Unicode 支持。-dump 只是输出 HTML 代码的文本渲染，然后可以剪切掉一些元素，而 -cols 确保所有内容都包装到 80 列内。

在引言和第一个条目之间添加指向渲染报告的链接。

最后，报告准备发送，切换处置方式（报告应该内联），并确保它以 UTF-8 编码。

发送两封电子邮件，两封电子邮件的主题格式为 FreeBSD 状态报告 - <第一/第二/第三/第四> 季度 <年份>

这封电子邮件必须经过批准，因此，如果您负责发送这封电子邮件，请确保有人执行此操作（如果邮件长时间未发送，请邮件 postmaster）。

最后修改时间：2023 年 3 月 14 日，由 Lorenzo Salvadore 修改