Developer’s FAQ 开发者常见问题解答

Contributor’s FAQ 贡献者常见问题解答

The term contributor is broader and does not only mean contribution of code. The documentation is a significant part and this is where non-technical people add value. The user’s POV brings different questions than the developers’ and explaining things in human language is a good thing.
贡献者这个术语更广泛，不仅仅意味着贡献代码。文档是一个重要部分，这是非技术人员增加价值的地方。用户的观点带来的问题与开发人员不同，用人类语言解释事情是一件好事。

Sending patches to documentation follows the same practices as for the code.
发送文档补丁遵循与代码相同的实践。

The documentation referred here is of the userspace tools (btrfs-progs), the manual pages or the documentation that’s part of the tool help strings.
这里提到的文档是用户空间工具（btrfs-progs）的手册页面或工具帮助字符串的一部分。

The fixes range from rewording unclear sections, fixing formatting, spelling, or adding more examples.
修复范围包括重新措辞不清晰的部分、修复格式、拼写错误或添加更多示例。

Documentation patches have high chance of getting merged and released quickly.
文档补丁很有可能被合并并迅速发布。

Developer’s FAQ 开发者常见问题解答

By the term developer is meant somebody who’s working on the code.
开发者一词指的是正在编写代码的人。

This section assumes basics of working with git, sending patches via mail and aims to cover the current practices.
本节假定您已掌握使用 git 的基础知识，通过邮件发送补丁，并旨在介绍当前的实践方法。

Patch tags 补丁标签

The practice of tagging patches in linux kernel community is documented in https://www.kernel.org/doc/html/latest/process/submitting-patches.html, we’ll highlight the most frequently used tags and their expected meaning. This only briefly mentions the commonly used tags. You’re encouraged to read the whole document and get familiar with it.
在 Linux 内核社区中标记补丁的做法已在 https://www.kernel.org/doc/html/latest/process/submitting-patches.html 中有记录，我们将重点介绍最常用的标签及其预期含义。这只是简要提及常用标签。鼓励您阅读整个文档并熟悉其中内容。

Signed-off-by: Signed-off-by:

This tag may appear multiple times, the first one denotes the patch author. (The common abbreviation in free text is S-O-B or just sob line.) The patch author is also recorded in git log history.
此标记可能会出现多次，第一个表示补丁作者。（在自由文本中的常见缩写是 S-O-B 或只是 sob 行。）补丁作者也记录在 git 日志历史中。

Then, each maintainer that processed the patch adds his sob line.
然后，处理补丁的每个维护者都会添加自己的 sob 行。

Reference: Section of SubmittingPatches.
参考：提交补丁部分。

Do: Always send a patch with at least one such line with your name and email. If more people contributed to the patch, add their names and addresses too.
做：始终发送一个至少包含您的姓名和电子邮件的补丁。如果有更多人为补丁做出贡献，请添加他们的姓名和地址。

Don’t: Add a sob line under patch that you have no authoring relation to, e.g. as a reply to the mailinglist after you’ve reviewed a patch. See below.
不要：在您没有作者关系的补丁下添加一行悲伤的内容，例如，在您审查补丁后作为回复邮件列表的一部分。请参见下文。

Reviewed-by: 审查者：

The patch has been reviewed and the singed person is putting his hand into fire. If there’s a bug found in this patch, the person is usually a good candidate for a CC: of the bugreport.
补丁已经被审查，签署人正在把手伸进火里。如果在这个补丁中发现了错误，这个人通常是错误报告的抄送候选人。

Reference: Section of SubmittingPatches.
参考：提交补丁部分。

Do: talk to the maintainer if he forgot to add this tag to the final patch. Reviews do take time and the patches land in various branches early after they’re sent to the mailingslist for testing, but the reviews are always welcome.
做：如果维护者忘记将此标签添加到最终补丁中，请与其交谈。审查确实需要时间，补丁在发送到邮件列表进行测试后很快就会进入各种分支，但审查总是受欢迎的。

Do: collect the Reviewed-by tags for patches that get resent unchanged e.g. within a larger patch series
执行：收集对未更改重新发送的补丁的 Reviewed-by 标记，例如在更大的补丁系列中

Acked-by: Acked-by：

A more lightweight form of Reviewed-by, acknowledging that the patch is going the right direction, but that the person has not done a deeper examination of the patch. Asking for an ACK can be expressed by a CC: tag in the patch.
Reviewed-by 的一种更轻量级形式，承认补丁朝着正确的方向发展，但该人员尚未对补丁进行更深入的检查。请求 ACK 可以通过补丁中的 CC：标记来表示。

Tested-by: 经测试：

Indicates that the patch has been successfully tested in some environment, usually follows a proposed fix and closes the feedback loop.
表示补丁已在某个环境中成功测试，通常跟随建议的修复，并关闭反馈循环。

Reference: Section of SubmittingPatches.
参考：提交补丁部分。

Do: or rather you’re encouraged to add this tag to a patch that you’ve tested.
进行：或者更确切地说，鼓励您将此标记添加到您已经测试过的补丁中。

CC: 抄送：

Add this tag to the patch if you feel that the person should be aware of the patch.
如果您认为某人应该知道这个补丁，请将此标记添加到补丁中。

Ordering 排序

The order of the tags can track the flow of the patches through various trees, namely the Signed-off-by tag. Ordering of the other tags is not strict so you can find patches with randomly mixed tags. A common practice we find kind of useful is to sort them how things happened. It would be good to use that, namely the references to stable trees and original reports.
标签的顺序可以跟踪补丁通过各种树的流动，即 Signed-off-by 标签。其他标签的顺序不严格，因此您可能会发现带有随机混合标签的补丁。我们发现一种常见的实践有点有用，即按事情发生的顺序对它们进行排序。最好使用这种方式，即对稳定树和原始报告的引用。

• how it happened 事情发生的方式

  1. (optional) Bugzilla: (可选) Bugzilla:

  2. (optional) Link: (可选) 链接:

  3. Reported-by: 报告者:

• where it should be backported, relevant references
  应该进行回溯的地方，相关参考资料

  1. Fixes: 修复：

  2. CC: stable@vger.kernel.org # 4.4+
     抄送：stable@vger.kernel.org # 4.4+

• other tags 其他标签

  1. CC:

  2. Suggested-by: 建议者：

• quality control by non-authors
  非作者进行质量控制

  1. Reviewed-by: 审查者：

  2. Tested-by: 测试者：

• author(s) 作者们

  1. Signed-off-by: 签名者:

• maintainer(s) 维护者

  1. Reviewed-by: 审查者：

  2. Signed-off-by: 签名者:

Patch flow 补丁流程 

Simple patch 简单补丁 

1. developer works on the patch, self-reviews, tests, adds the formal tags, writes changelog
   开发人员在补丁上工作，自我审查，测试，添加正式标签，编写更改日志

2. patch lands in the mailinglist
   补丁发布到邮件列表

3. patch is commented, reviewed
   补丁被评论，审查

   • several iterations of updates may follow
     可能会跟随几次更新迭代

4. maintainer adds the patch into a branch
   维护者将补丁添加到一个分支中

5. when the right time comes, a branch with selected patches is pushed up the merge chain
   当时机成熟时，带有选定补丁的分支被推送到合并链中

6. a release milestone that contains the patch is released, everybody is happy
   包含补丁的发布里程碑发布后，每个人都很高兴

Controversial changes 有争议的更改

This happens, not every patch gets merged. In the worst case there are not even any comments under the patch and it’s silently ignored. This depends on many factors, most notably *cough*time*cough*. Examining potential drawbacks or forseeing disasters is not an easy job.
这种情况时有发生，不是每个补丁都会被合并。在最糟糕的情况下，甚至在补丁下面没有任何评论，被悄悄地忽略了。这取决于许多因素，尤其是*咳嗽*时间*咳嗽*。审查潜在的缺点或预见灾难并不是一件容易的工作。

Let’s be more positive, you manage to attract the attention of some developer and he says, he does not like the approach of the patch(es). Better than nothing, isn’t it? Depending on the feedback, try to understand the objections and try to find a solution or insist on your approach but possibly back it by good arguments (performance gain, expected use case) or a better explanation why the change is needed.
让我们更加积极一些，你成功吸引了一些开发者的注意，他说，他不喜欢这些补丁的方式。总比没有好，不是吗？根据反馈，尝试理解异议并寻找解决方案，或者坚持自己的方式，但可能需要用良好的论据支持（性能提升，预期用例），或者更好地解释为什么需要这种变化。

Repeated submissions 重复提交

If you got feedback for a patch that pointed out changes that should be done before the patch can be merged, please do apply the changes or give a reason why they’re wrong or not needed. (You can try to pinkie-swear to implement them later, but do not try this too often.)
如果你收到了关于补丁的反馈，指出了在补丁合并之前应该做出的更改，请应用这些更改或者给出一个理由说明它们是错误的或者不需要的。（你可以试着保证稍后实施它们，但不要经常这样做。）

For the next iteration, add a short description of the changes made, under the first --- (triple dash) marker in the patch. For example (see also Example 3):
对于下一个迭代，请在补丁中的第一个 ---（三个破折号）标记下添加对所做更改的简短描述。例如（另请参见示例 3）：

---
V3: renamed variable
V2: fixed typo

Keep all previous changelogs. Larger patchsets should contain the incremental changelogs in the cover letter.
保留所有先前的更改日志。较大的补丁集应在封面信中包含增量更改日志。

Patch completeness, RFC
补丁完整性，RFC 

A patch does not necessarily have to implement the whole feature or idea. You can send an early version, use a [RFC] string somewhere in the subject. This means request for comments. Be prepared to get comments.
补丁不一定要实现整个功能或想法。您可以发送一个早期版本，在主题中的某处使用[RFC]字符串。这意味着请求评论。准备好接受评论。

Please describe the level of completeness, e.g. what tests it does or does not pass or what type of use cases is not yet implemented. The purpose is to get feedback from other developers about the direction or implementation approach. This may save you hours of coding.
请描述完成度水平，例如它通过了哪些测试或未通过哪些测试，还有哪些用例类型尚未实现。目的是从其他开发人员那里获得关于方向或实现方法的反馈。这可能为您节省数小时的编码时间。

Patchsets 补丁集 

Related patches, patch dependency
相关补丁，补丁依赖

Group the patches by feature or by topic. Implementing a particular feature may need to prepare other parts of the code for the main patch. Applying the patches out of order will not succeed, so it’s pointless to send them as unrelated and separate mails. The git tool is helpful here, see git-format-patch.
将补丁按特性或主题分组。实现特定功能可能需要准备代码的其他部分以适应主要补丁。以无序方式应用补丁将不会成功，因此将它们作为无关和独立的邮件发送是毫无意义的。git 工具在这里很有帮助，参见 git-format-patch。

An example of grouping by topic is cleanups, or small bugfixes that are quite independent but it would be better to processes them in one go.
按主题分组的一个示例是清理或独立的小错误修复，但最好一次性处理它们。

Sometimes a patch from a series is self-contained enough that it might get applied ahead of the whole series. You may also submit it separately as this will decrease the work needed to keep the patch series up to date with the moving development base.
有时，系列中的一个补丁足够独立，可能会先于整个系列应用。您也可以单独提交它，这样可以减少保持补丁系列与不断发展的基础保持最新所需的工作量。

Do: make sure that each patch compiles and does not deliberately introduce a bug, this is a good practice that makes bisecting go smooth
要做：确保每个补丁都可以编译，并且不会故意引入错误，这是一个很好的实践，使二分法更加顺利。

Do: send the cover letter (i.e. the non-patch mail) with brief description of the series, this is a place where feedback to the whole patchset will be sent rather than comments to the individual patches. To generate the series with cover letter use git format-patch --cover-letter --thread.
要做：发送封面信（即非补丁邮件），简要描述系列，这是整个补丁集将接收反馈而不是对单个补丁的评论的地方。要生成带封面信的系列，请使用 git format-patch --cover-letter --thread。

Good practices, contribution hints
良好的实践，贡献提示 

• if you feel that you understand some area of code enough to stick your Reviewed-by to submitted patches, please do. Even for small patches.
  如果您觉得您对某个代码领域的理解足以将您的 Reviewed-by 粘贴到提交的补丁中，请这样做。即使是小的补丁。

• don’t hesitate to be vocal if you see that a wrong patch has been committed
  如果您发现错误的补丁已经提交，请毋须犹豫地发表意见。

• be patient if your patch is not accepted immediately, try to send a gentle ping if there’s a significant time without any action
  如果您的补丁未被立即接受，请耐心等待，如果有很长时间没有任何动作，请尝试发送友好的提醒

• if you want to start contributing but are not sure about how to do that, lurk in the mailingist or on the IRC channel
  如果您想开始贡献但不确定如何做，可以在邮件列表或 IRC 频道中潜水

• every patch should implement one thing -- this is vaguely defined, you may receive comments about patch splitting or merging with other
  每个补丁应该实现一件事情 -- 这个定义模糊，您可能会收到关于拆分补丁或与其他补丁合并的评论

• every patch must be compilable when applied, possibly with all related CONFIG_ variable values
  每个补丁在应用时必须是可编译的，可能需要所有相关的 CONFIG_ 变量值

• send a new patch as a new mail, not within another thread, it might get missed
  将新的补丁作为新邮件发送，不要放在另一个线程中，否则可能会被忽略

• use git-format-patch and git-send-email
  使用 git-format-patch 和 git-send-email

Sample patches 示例补丁 

There are some formalities expected, like subject line formatting, or the tags. Although you may find them annoying at first, they help to classify the patches among the rest of mails.
有一些预期的形式，比如主题行格式，或标签。虽然一开始可能会觉得它们很烦人，但它们有助于将补丁分类到其余的邮件中。

Subject: 主题： 

For kernel patches add the prefix btrfs:
对于内核补丁，请添加前缀 btrfs：

for userspace tools add btrfs-progs:
对于用户空间工具，请添加 btrfs-progs：

Example 1 示例 1 

From: John Doe <john@doe.org>
Subject: [PATCH] btrfs: merge common code into a helper

The code for creating a new tree is open-coded in a few places, add a helper
and remove the duplicate code.

Signed-off-by: John Doe <john@doe.org>
---
fs/btrfs/volumes.c |    5 +++--
1 files changed, 3 insertions(+), 2 deletions(-)
diff --git a/fs/btrfs/volumes.c b/fs/btrfs/volumes.c
index e138af710de2..3f0cc12ec488 100644
--- a/fs/btrfs/volumes.c
+++ b/fs/btrfs/volumes.c
(rest of the patch)

Example 2 示例 2 

From: Jane Doe <jane@doe.org>
Subject: [PATCH] btrfs-progs: enhance documentation of balance

Add examples of typical balance use, common problems and how to resolve them.

Signed-off-by: Jane Doe <jane@doe.org>
---
Documentation/btrfs-balance.txt |    20 +++++++++++++++++++-
1 files changed, 3 insertions(+), 2 deletions(-)
diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt
index e138af710de2..3f0cc12ec488 100644
--- a/Documentation/btrfs-balance.txt
+++ b/Documentation/btrfs-balance.txt
(rest of the patch)

Example 3 示例 3 

From: John Doe <john@doe.org>
Subject: [PATCH v3] btrfs: merge common code into a helper

The code for creating a new tree is open-coded in a few places, add a helper
and remove the duplicate code.

Signed-off-by: John Doe <john@doe.org>
---
V3: add helper prototype into header file
V2: found one more open-coded instance

fs/btrfs/ctree.h   |    1 +
fs/btrfs/volumes.c |    5 +++--
2 files changed, 4 insertions(+), 2 deletions(-)
diff --git a/fs/btrfs/volumes.c b/fs/btrfs/volumes.c
index e138af710de2..3f0cc12ec488 100644
--- a/fs/btrfs/volumes.c
+++ b/fs/btrfs/volumes.c
(rest of the patch)

Pull requests vs patches to mailinglist
拉取请求 vs 邮件列表补丁 

By default, all patches should be sent as mails to the mailinglist. The discussions or reviews happen there. Putting a patch series to a git branch may be convenient, but does not mean the exact unchanged branch will be pulled.
默认情况下，所有补丁都应该通过邮件发送到邮件列表。讨论或审查将在那里进行。将一个补丁系列放到一个 git 分支可能很方便，但并不意味着完全不变的分支将被拉取。

There are some criteria that have to be met before this happens. The patches should meet/have:
在此之前必须满足一些标准。补丁应该符合以下要求：

• no coding style violations
  没有编码风格违规。

• good quality of implementation, should not exhibit trivial mistakes, lack of comments
  实现质量好，不应出现琐碎错误，缺乏注释

• unspecified number of other things that usually get pointed out in review comments
  通常在审查评论中指出的其他事项的数量未指定

  • this knowledge can be demonstrated by doing reviews of other developers’ patches
    通过审查其他开发人员的补丁来展示这种知识

  • doing reviews of other developers’ patches is strongly recommended
    对其他开发人员的补丁进行审查是强烈推荐的

• good changelogs and subject lines
  良好的变更日志和主题行

• the base point of the git branch is well-defined (i.e. a stable release point or last development point, that will not get rebased)
  git 分支的基准点是明确定义的（即稳定发布点或最后的开发点，不会被 rebase）

The third point is vague, mostly refers to preferred coding patterns that we discover and use over time. This may also explain why the pull-based workflow is not used often. Both parties, developers and maintainers, need to know that the code to be pulled will be satisfactory in this regard.
第三点比较模糊，主要指的是我们随着时间发现并使用的首选编码模式。这也可以解释为什么基于拉取的工作流程并不经常使用。开发人员和维护人员双方都需要知道，待拉取的代码在这方面是令人满意的。

It should be considered normal to send more than one round of a patchset, based on review comments that hopefully do not need to point out issues in anything of the above. Rather focus on design or potential uses and other impact.
应该考虑发送多轮补丁集是正常的，基于审查意见，希望不需要指出上述任何问题。而是专注于设计或潜在用途以及其他影响。

Kernel patches 内核补丁 

If you think you’re able to provide the expected quality of patches and are familiar with a bit more advanced git use, ask the maintainers. If you’re a long-term developer, the maintainers can also ask you to start the pull-based workflow. The main point for the workflow is to make maintainers’ life easier.
如果您认为自己能够提供预期质量的补丁，并且熟悉一些更高级的 git 使用，请向维护者询问。如果您是一名长期开发者，维护者也可以要求您开始基于拉取的工作流程。工作流程的主要目的是让维护者的生活更轻松。

Suggested branch names for patchsets for current development cycle:
建议的补丁集分支名称为当前开发周期：

• base -- the last commit of the last pull (could be in branch named something like misc-next), or some older head of pull request
  base -- 上一个拉取请求的最后提交（可能在名为 misc-next 的分支中），或者一些较旧的拉取请求的头部

Patches for next development cycle:
下一个开发周期的补丁:

• base -- the last release candidate tag in Linus’ tree, be sure not to be ahead of the integration branches that will become the pull requests for the next development cycle.
  base -- Linus 的树中的最后一个发布候选标记，确保不要超过将成为下一个开发周期拉取请求的集成分支。

• for-next -- patches should be in a good state, i.e. don’t complicate testing too much, workarounds or known problems should be documented (e.g. in the patchset cover letter)
  for-next -- 补丁应处于良好状态，即不要使测试过于复杂，应记录解决方法或已知问题（例如，在补丁集封面信中）。

• other names, for example a patchset for a given feature as a topic branch: feature-live-repair
  其他名称，例如给定功能的补丁集作为主题分支：feature-live-repair

Experimental, unsafe or unreviewed patchsets are good candidates for topic branches as they could be added or removed from the for-next branches easily (compared to manually removing the patches from a long series).
实验性、不安全或未经审查的补丁集是主题分支的良好候选，因为它们可以轻松地从 for-next 分支中添加或移除（与手动从长系列中移除补丁相比）。

Btrfs-progs patches Btrfs-progs 补丁 

The first paragraph from previous section applies here as well.
前一节的第一段同样适用于这里。

Unlike the kernel, there are no release candidates during development. If a patchset is independent, the master branch is a suitable point. In case there are other patches in devel, a non-rebased development branch needs to be created. As this is not needed most of the time, this will happen only on-demand.
与内核不同，在开发过程中没有发布候选版本。如果一个补丁集是独立的，主分支是一个合适的点。如果在 devel 中有其他补丁，需要创建一个非基于重置的开发分支。由于大部分时间都不需要这样做，这只会在需要时发生。

Copyright notices in files, SPDX
文件中的版权声明，SPDX 

License information in files is using the SPDX standard.
文件中的许可信息使用 SPDX 标准。

Quoting https://spdx.dev/about/:
引用 https://spdx.dev/about/:

SPDX is an open standard for communicating software bill of material information, including provenance, license, security, and other related information. SPDX reduces redundant work by providing common formats for organizations and communities to share important data, thereby streamlining and improving compliance, security, and dependability. The SPDX specification is recognized as the international open standard for security, license compliance, and other software supply chain artifacts as ISO/IEC 5962:2021.
SPDX 是用于传达软件材料信息的开放标准，包括来源、许可、安全性和其他相关信息。SPDX 通过提供组织和社区共享重要数据的常见格式，减少了重复工作，从而简化和改进了合规性、安全性和可靠性。SPDX 规范被认可为 ISO/IEC 5962:2021 的国际开放标准，用于安全性、许可合规性和其他软件供应链工件。

The initiative started in 2017 https://lwn.net/Articles/739183/ aims to unify licensing information in all files using SPDX tags, this is driven by the Linux Foundation. Therefore it’s not necessary to repeat the license header (GPL) in each file, the licensing rules are documented in https://docs.kernel.org/process/license-rules.html (also available in linux git tree in Documentation/process/license-rules.rst which is the source file of the linked document).
该倡议始于 2017 年 https://lwn.net/Articles/739183/ 旨在使用 SPDX 标记统一所有文件中的许可信息，由 Linux 基金会推动。因此，在每个文件中重复许可证头部（GPL）是不必要的，许可规则已记录在 https://docs.kernel.org/process/license-rules.html 中（也可在 linux git 树中的 Documentation/process/license-rules.rst 中找到，这是链接文档的源文件）。

Complete information with history about contributors of changes in a particular file is recorded in git using Signed-off-by tags that are documented and widely understood (Developer’s certificate of origin). For more information please see https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin .
记录特定文件中更改的贡献者的完整信息和历史记录在 git 中使用 Signed-off-by 标记，这些标记已记录并被广泛理解（开发者的原始证书）。有关更多信息，请参阅 https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin 。

Copyright notices in files. This delves into the legal territory and there’s no easy answer about the recommended practice. This paragraph could help you to answer some questions regarding that but is not by any means complete and refers to known and documented practices:
文件中的版权声明。这涉及法律领域，关于推荐做法没有简单的答案。本段落可能帮助您回答一些关于此事的问题，但绝不是完整的，并参考已知和记录的做法：

• All code merged into the mainline kernel retains its original ownership (https://docs.kernel.org/process/1.Intro.html#licensing)
  所有合并到主线内核的代码保留其原始所有权（https://docs.kernel.org/process/1.Intro.html#licensing）

• Removing the copyright from existing files is not trivial and would require asking the original authors or current copyright holders.
  从现有文件中删除版权并不是一件简单的事情，需要询问原始作者或当前版权持有者。

• In btrfs code, adding copyright notices is not mandatory
  在 btrfs 代码中，添加版权声明并非强制要求。

• In btrfs code, there are some copyright notices present from years before 2017
  在 btrfs 代码中，存在一些早于 2017 年的版权声明

• In btrfs code, the copyright notices are inconsistent and incomplete (please refer to git history to look up the cod change authors)
  在 btrfs 代码中，版权声明不一致且不完整（请参考 git 历史查找代码更改作者）

• If not sure, please consult your lawyers
  如果不确定，请咨询您的律师

Btrfs developer community perspective, not legally binding.
Btrfs 开发者社区的观点，不具有法律约束力。

The copyright notices are not required and are discouraged for reasons that are practical rather than legal. The files do not track all individual contributors nor companies (this can be found in git), so the inaccurate and incomplete information gives a very skewed if not completely wrong idea about the copyright holders of changes in a given file. The code is usually heavily changed over time in smaller portions, slowly morphing into something that does not resemble the original code anymore though it shares a lot of the core ideas and implemented logic. A copyright notice by a company that does not exist anymore from 10 years ago is a clear example of uselesness for the developers.
版权声明并非必需，出于实际而非法律原因，我们不鼓励使用。文件并未跟踪所有个人贡献者或公司（这些可以在 git 中找到），因此不准确和不完整的信息会给人们关于给定文件中变更的版权持有者的想法带来非常偏颇，甚至完全错误的印象。代码通常会随着时间逐渐在较小的部分中进行大量更改，慢慢地变成了与原始代码不再相似，尽管它分享了许多核心思想和实现逻辑。10 年前不存在的公司的版权声明是开发者们的一个明显无用的例子。

When code is moved verbatim from a file to another file, in the new file it appears to be contributed by a single author while it is in most cases code resulting from many previous contributions from other people. This is most obvious when splitting code from big files to new ones, because this is considered a good development practice, but somehow goes against the meaning of the copyright notices, unless a complete list of original code authors and copyright holders is also copied.
当代码从一个文件逐字移动到另一个文件时，在新文件中，它看起来像是由单个作者贡献的，但实际上大多数情况下是由许多其他人之前贡献的代码。当将代码从大文件拆分到新文件时，这一点最为明显，因为这被认为是一种良好的开发实践，但在某种程度上违背了版权声明的意义，除非也复制了原始代码作者和版权持有者的完整列表。

The current copyright notices will not be removed but at least new contributions won’t continue adding new ones. The change history is recorded in git using Signed-off-by tags that are documented (https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin) and widely understood. Unless there’s a blessed practice regarding the copyright notices that significantly improves the situation, the current way is considered sufficient for practical development purposes.
当前的版权声明不会被移除，但至少新的贡献不会继续添加新的声明。更改历史记录在 git 中使用已记录的 Signed-off-by 标签，这些标签已经被广泛理解和记录（https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin）。除非有一种关于版权声明的受认可的做法显著改善了情况，否则当前方式被认为对于实际开发目的已经足够。

Given all the above, we don’t want the copyright notices in individual files that are new, renamed or split. This applies to all new changes in all btrfs related code changes. Obviously lawyers may disagree and/or may require additional refinements to the process, which is fine but beyond the scope of this section.
鉴于上述所有情况，我们不希望在新建、重命名或拆分的各个文件中出现版权声明。这适用于所有 btrfs 相关代码更改中的所有新更改。显然，律师可能持不同意见和/或可能需要对流程进行额外的完善，这是可以接受的，但超出了本节的范围。

You may also read a perspective from Linux Foundation that shares a similar view: https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/
您还可以阅读 Linux 基金会的一篇观点，分享了类似的观点：https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/

Development schedule 开发时间表 

A short overview of the development phases of linux kernel and what this means for developers regarding sending patches etc.
Linux 内核开发阶段的简要概述以及对开发人员发送补丁等方面的影响。

Major release 主要发布 

Overall: a major release is done by Linus, the version bumps in the 2nd position of the version, e.g. it’s 4.6. This usually means distributions start to adopt the sources, the stable kernels are going to be released.
总体而言：主要发布由 Linus 完成，版本号的第二位数会增加，例如 4.6。这通常意味着发行版开始采用这些源代码，稳定内核将会发布。

Developers: expect bug reports based on this version, this usually does not have other significance regarding development of new features or bugfixes
开发人员：预计基于此版本的错误报告，这通常不涉及开发新功能或错误修复方面的其他重要性

Merge window 合并窗口

Overall: the time when pull requests from 1st level maintainers get sent to Linus, the merge window starts after the major release and usually takes two weeks
总体而言：一级维护者的拉取请求发送给 Linus 的时间，合并窗口在主要发布后开始，通常需要两周时间

Developers: get ready with any bugfixes that were not part of the patches in the pull requests but are still relevant for the upcoming kernel
开发人员：准备好任何未包含在拉取请求中但仍与即将到来的内核相关的错误修复

There are usually one or two pull requests sent by the maintainer so it’s OK to send the bugfixes to the mailinglist even during the merge window period. If the “deadline” is not met, the patches get merged in the next rc.
通常由维护者发送一到两个拉取请求，因此即使在合并窗口期间也可以将错误修复发送到邮件列表。如果“截止日期”未能满足，补丁将在下一个 rc 中合并。

Sending big patchsets during this period is not discouraged, but feedback may be delayed.
在此期间发送大型补丁集并不受到阻止，但反馈可能会延迟。

The amount of changes that go to master branch from the rest of the kernel is high, things can break due to reasons unrelated to btrfs changes. Testing is welcome, but the bugs could turn out not to be relevant to us.
从内核的其余部分到主分支的更改数量很高，事情可能会因与 btrfs 更改无关的原因而发生故障。欢迎测试，但错误可能与我们无关。

The rc1 rc1

Overall: most of the kernel changes are now merged, no new features are allowed to be added, the following period until the major release is expected to fix only regressions
总体而言：大部分内核更改现在已经合并，不允许添加新功能，直到主要发布之前的这段时间预计只会修复退化。

Developers: it’s a good time to test extensively, changes in VFS, MM, scheduler, debugging features and other subsystems could introduce bugs or misbehaviour
开发人员：现在是广泛测试的好时机，VFS、MM、调度程序、调试功能和其他子系统的更改可能会引入错误或不良行为

From now on until the late release candidates, it’s a good time to post big patchsets that are supposed to land in the next kernel. There’s time to let others to do review, discuss design goals, do patchset revisions based on feedback.
从现在开始直到最后的发布候选版本，现在是发布大的补丁集的好时机，这些补丁集应该会在下一个内核中落地。有时间让其他人进行审查，讨论设计目标，根据反馈进行补丁集修订。

Depending on the proposed changes, the patchset could be queued for the next release within that time. If the patchset is intrusive, it could stay in the for-next branches for some time.
根据提议的更改，该补丁集可能会在此期间排队等待下一个发布。如果补丁集具有侵入性，它可能会在未来的分支中停留一段时间。

The late rcX (rc5 and up)
迟到的 rcX（rc5 及更高版本）

Overall: based on past experience, there are at least 5 release candidates, done on a weekly basis, so you can estimate the amount of time before the full release or merge window. The 5 seems like am minimum, usually there are 2 or 3 more release candidates.
总体而言：根据过去的经验，至少有 5 个发布候选版本，每周发布一次，因此您可以估计在完整发布或合并窗口之前的时间。5 似乎是最少的，通常还会有 2 或 3 个发布候选版本。

Developers: new code for the upcoming kernel is supposed to be reviewed and tested, can be found in the for-next branch
开发人员：即将发布的内核的新代码应该经过审查和测试，可以在 for-next 分支中找到。

Sending intrusive changes at this point is not guaranteed to be reviewed or tested in time so it gets queued for the next kernel. This highly depends on the nature of the changes. Patch count should not be an issue if the patches are revieweable or do not do intrusive changes.
此时发送侵入性更改不能保证及时审核或测试，因此会排队等待下一个内核。这在很大程度上取决于更改的性质。如果补丁可以审查或不进行侵入性更改，则补丁数量不应成为问题。

Last rcX before major release (rc7 or rc8)
在主要发布之前的最后一个 rcX（rc7 或 rc8）

The releases typically take 3 months, which means that rc7 or rc8 are the last ones, followed by a release and the merge window opens. Before that the development is effectively frozen or continues in parallel. Up to date list of release dates is at https://en.wikipedia.org/wiki/Linux_kernel_version_history .
发行版通常需要 3 个月的时间，这意味着 rc7 或 rc8 是最后一个版本，随后是一个发布和合并窗口打开。在此之前，开发实际上已经冻结或并行进行。最新的发布日期列表请参阅 https://en.wikipedia.org/wiki/Linux_kernel_version_history 。

Major release 主要发布 

goto 1;

Development phase, linux-next, for-next
开发阶段，linux-next，for-next 

Patches and patchsets that are supposed to be merged in the next merge cycle are usually collected in the linux-next git tree. This gives an overview about potential conflicts and provides a central point for testing various patches. The btrfs patches for linux-next tree are hosted at https://git.kernel.org/pub/scm/linux/kernel/git/kdave/linux.git in branch for-next. The update period is irregular, usually a few times per week.
通常，应该在下一个合并周期中合并的补丁和补丁集通常会被收集在 linux-next git 树中。这提供了关于潜在冲突的概述，并为测试各种补丁提供了一个中心点。用于 linux-next 树的 btrfs 补丁托管在 https://git.kernel.org/pub/scm/linux/kernel/git/kdave/linux.git 的 for-next 分支中。更新周期不规律，通常每周几次。

Patches are added to for-next when they get a basic review and do not seriously decrease stability. Some level of breakage is allowed and inevitable so there’s a possibility to get a tree for early testing. Also there are external services that provide compilation coverage for various arches and configurations.
当补丁经过基本审查并且不会严重降低稳定性时，它们会被添加到 for-next 分支。允许出现一定程度的破坏和不可避免的问题，因此有可能获得用于早期测试的树。此外，还有外部服务为各种架构和配置提供编译覆盖率。

The for-next branch is rebased and rebuilt from scratch and cannot be used as base for patch development. Independent patches should use last -rc tag.
for-next 分支会被从头开始重新基于并重建，不能作为补丁开发的基础。独立的补丁应该使用最新的 -rc 标签。

• https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git -- daily snapshots
  https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git -- 每日快照

• https://git.kernel.org/pub/scm/linux/kernel/git/kdave/linux.git -- for-next

Misc information and hints
杂项信息和提示

This section collects random pieces of advice from mailinglist that are given to newcomers.
本节收集了从邮件列表中给新手的随机建议。

How to get started - development
如何入门 - 开发

• Build and install the latest kernel from Linus’s git repository.
  从 Linus 的 git 存储库构建并安装最新的内核。

• Create one or several btrfs filesystems with different configurations and learn how they work in userspace -- what are the features, what are the problems you see? Actually use at least one of the filesystems you created for real data in daily use (with backups)
  创建一个或多个具有不同配置的 btrfs 文件系统，并学习它们在用户空间中的工作方式 - 它们有哪些特性，你看到了哪些问题？实际上，至少使用你创建的一个文件系统来存储真实数据并在日常使用中使用（带有备份）。

• Build the userspace tools from git
  从 git 中构建用户空间工具

• Project ideas used to be tracked on the wiki (https://archive.kernel.org/oldwiki/btrfs.wiki.kernel.org/index.php/Project_ideas.html) but this contains outdated information and will be moved elsewhere eventually. If you pick the right one(s), you’ll have to learn about some of the internal structures of the filesystem anyway. Compile and test your patch. If you’re adding a new feature, write an automated fstests case for it as well.
  项目想法曾经在维基上进行跟踪（https://archive.kernel.org/oldwiki/btrfs.wiki.kernel.org/index.php/Project_ideas.html），但其中包含过时信息，最终将被移至其他地方。如果选择了正确的项目，您将不得不了解文件系统的一些内部结构。编译并测试您的补丁。如果正在添加新功能，请为其编写一个自动化的 fstests 用例。

• Get that patch accepted. This will probably involve a sequence of revisions to it, multiple versions over a period of several weeks or more, with a review process. You should also send your test to fstests and get that accepted.
  让该补丁被接受。这可能需要对其进行一系列修订，多个版本在数周甚至更长时间内，经过审查过程。您还应将您的测试发送给 fstests 并获得接受。

• Do the above again, until you get used to the processes involved, and have demonstrated that you can work well with the other people in the subsystem, and are generally producing useful and sane code. It’s all about trust -- can you be trusted to mostly do the right thing?
  再次执行上述操作，直到您习惯所涉及的流程，并已证明您能够与子系统中的其他人员良好合作，并且通常能够生成有用且理智的代码。这一切都建立在信任之上 -- 您能被信任大多数时候做正确的事情吗？

• Developer documentation is listed in a section on the main documentation page.
  开发人员文档列在主文档页面的一个部分中。

• Output of btrfs inspect-internal dump-tree can be helpful to understand the internal structure of the filesystem.
  运行 btrfs inspect-internal dump-tree 命令的输出有助于理解文件系统的内部结构。

How not to start
如何不开始

It might be tempting to look for coding style violations and send patches to fix them. This happens from time to time and the community does not welcome that. The following text reflects our stance:
可能会诱人地寻找编码风格违规并发送补丁来修复它们。这种情况偶尔会发生，但社区并不欢迎这样做。以下文字反映了我们的立场：

If you want to contribute and do something useful for others and yourself, just don’t keep sending these patches to fix whitespace/style issues reported by checkpatch.pl. Think about it:
如果你想为他人和自己做点有用的事情，就不要继续发送那些用于修复由 checkpatch.pl 报告的空格/样式问题的补丁。好好考虑一下：

1. You don’t learn anything by doing them. You don’t learn nothing about btrfs internals, filesystems in general, kernel programming in general, general programming in C, etc. It ends up being only a waste of time for you;
   通过这样做，你学不到任何东西。你对 btrfs 内部，文件系统一般，内核编程一般，以及 C 语言一般编程等方面一无所知。对你来说，这只会是浪费时间；

2. You’re not offering any benefit to users - not fixing a bug, not adding a new feature, not doing any performance/efficiency improvement, not making the code more reliable, etc;
   你没有为用户提供任何好处 - 不修复错误，不添加新功能，不进行任何性能/效率改进，不使代码更可靠等；

3. You’re not offering a benefit for other developers either, like doing a cleanup that simplifies a complex algorithm for example.
   你也没有为其他开发人员提供任何好处，比如简化复杂算法的清理工作。

If you care so much about the whitespace/style issues, just fix them while doing a useful change as mentioned above that happens to touch the same code. It takes time to read and understand code, it can be a big investment of time, but it ends up being worth it. There’s plenty of bug reports and performance issues in the mailing list or bugzilla, so there’s no shortage of things to do.
如果您非常关心空格/样式问题，只需在进行有用的更改时修复它们，如上述提到的碰巧涉及相同代码。阅读和理解代码需要时间，这可能是一项很大的时间投资，但最终是值得的。邮件列表或 bugzilla 中有大量的错误报告和性能问题，因此没有缺少要做的事情。

Same advice applies to any other kernel subsystem or open source project in general. Also before jumping into such a storm of useless patches, observe first what a community does for at least a month, and learn from other contributors - what they do, how they do it, the flow of development and releases, etc. Don’t rush into a sending patch just for the sake of sending it and having your name in the git history.
相同的建议适用于任何其他内核子系统或开源项目。在跳入这样一场无用补丁的风暴之前，首先观察社区至少一个月的做法，并向其他贡献者学习 - 他们做什么，如何做，开发和发布的流程等。不要仓促发送补丁，只是为了发送补丁并让您的名字出现在 git 历史记录中。

References 参考资料 

• Kernel maintainersip: an oral tradition (pdf) a nice presentation from ELCE 2015 what does it mean to be a maintainer and what the developers can expect.
  内核维护：一种口头传统（pdf）来自 ELCE 2015 的一个很好的演示，它解释了成为维护者意味着什么，开发人员可以期待什么。

• https://www.kernel.org/doc/html/latest/process/submitting-patches.html (must read)
  https://www.kernel.org/doc/html/latest/process/submitting-patches.html (必读)

• https://www.kernel.org/doc/html/latest/process/coding-style.html (must read)
  https://www.kernel.org/doc/html/latest/process/coding-style.html (必读)

• Pro Git by Scott Chacon http://progit.org/book/
  由 Scott Chacon 编写的《Pro Git》http://progit.org/book/

• Git project main page http://git-scm.com
  Git 项目主页 http://git-scm.com