Apache Log4j 项目准则

本文档定义了Apache Log4j 项目的准则。它包括以下方面的定义：通过投票解决冲突的方式，能够投票的人，提出和进行更改的遵循程序以及更改代码的准则。

此处的目的是避免不必要的变更冲突，并 continue 及时构建质量体系。并非所有冲突都可以避免，但是至少我们可以就解决冲突的程序达成共识。

人，地方和事物

• Apache 日志记录项目 Management 委员会

  • 负责 ManagementApache Logging 项目(包括 Log4j)的志愿者小组。这包括确定以 Apache Logging Project 产品的形式分发的产品，维护 Project 的共享资源，代表 Project 发言，解决有关 Apache 产品的许可纠纷，提名新的 PMC 成员或提交者以及构建这些准则。

Apache Logging PMC 的成员资格仅受邀请，并且必须得到 Active Logging PMC 成员的共识批准。 PMC 成员因自己的声明或六个月内未对项目做出任何形式的贡献而被视为不活跃。不活动的成员可以通过撤消使他们不活动的任何条件(即，通过逆转其先前的声明或再次为项目工作做出贡献)来再次变得活动。可以通过除相关成员之外的所有活动 PMC 成员的一致投票来撤销成员资格。

• Apache 记录提交者

  • 负责 Apache 日志记录项目技术方面的志愿者小组。该小组有权访问适当的资源库，这些志愿者可以对任何技术讨论投具有约束力的选票。尽管提交者通常由于其在一个 Logging 项目上的活动而加入，但他们将拥有对所有 Logging 项目的提交访问权限。

作为提交者的成员资格仅受邀请，并且必须得到活动 Logging PMC 成员的共识批准。提交人被自己的声明视为无效，或者在六个月内未以任何形式对项目做出任何贡献。不活动的成员可以通过撤消使他们不活动的任何条件(即，通过逆转其先前的声明或再次为项目工作做出贡献)来再次变得活动。可以通过所有活动 PMC 成员(如果该成员是 PMC 成员，则除外)的一致投票来撤销成员资格。

• Log4j Developers

  • 所有为 Log4j 项目贡献时间，代码，文档或资源的志愿者。通常会邀请在六个月以上的时间内对项目做出持续，令人欢迎的贡献的开发人员成为“提交者”，尽管此类邀请的确切时间取决于许多因素。

• mailing list

  • Log4j 开发人员的主要邮件列表，用于讨论与项目相关的问题和更改([email protected])。列表的订阅已打开，但是只有订阅者可以直接在列表中发布。

• private list

  • Logging PMC 的私人邮件列表，用于讨论不适合公开讨论的问题，例如在发布修订之前的法律，个人或安全问题。列表的订阅仅对 Apache Logging 的项目 Management 委员会开放(实际上是强制性的)。

• Git

  • 所有 Apache 产品都使用 Subversion 或 Git 维护在信息存储库中。 Log4j 使用Git。只有一些 Apache 开发人员具有对 Apache Logging 存储库的写访问权。每个人都有read access。

Issue Management

Log4j 项目使用由 Apache Software Foundation 托管和维护的Jira错误跟踪系统来跟踪错误和增强功能。可以通过 JIRA 的 RoadMap 功能以及使用 Story 或 Epic 问题来维护项目 Route 图。

该项目将遇到许多问题，每个问题导致零个或多个提议的行动项目。问题一经发现，应在邮件列表中提出。 必须在邮件列表中提出操作项 ，并使用适当的问题类型将其添加到 JIRA。可以对所有操作项目进行投票，但是并非所有操作项目都需要进行正式投票。

Voting

任何 Log4j 开发人员都可以对任何问题或操作项目进行投票。但是，唯一具有约束力的投票是 Apache Logging PMC 的活跃成员投票的投票。如果投票是关于对源代码或文档的更改，则所更改内容的主要作者也可以对该问题进行具有约束力的投票。其他所有投票都不具有约束力。鼓励所有开发人员参与决策，但是决策本身由长期为项目做出贡献的人员做出。换句话说，Apache Log4j 项目是最低阈值精英。

投票行为具有某些义务-投票成员不仅在表达自己的意见，而且还同意帮助完成 Log4j 项目的工作。由于我们都是志愿者，因此成员经常会在一段时间内变得不活跃，以照顾他们的“实际工作”或将更多时间用于其他项目。因此，整个小组成员不太可能会就每个问题进行投票。为了解决这个问题，所有投票决定均基于最低法定人数。

可以按照以下三种方式之一进行投票：

• +1

  • 是的，同意，或者应该执行该操作。在某些问题上，只有当投票者已经在他们自己的系统上测试了该动作时，该投票才具有约束力。

• ±0

  • 弃权，没有意见，或者我很乐意让其他小组成员决定这个问题。如果太多人弃权，弃权可能会产生有害影响。

• -1

  • 否。在需要达成共识的问题上，此项投票被视为“否决”。所有否决权都必须说明为什么要使用否决权。没有解释的否决权是无效的。没有否决权可以被否决。如果您不同意否决权，则应游说投票否决权的人。打算否决某个行动项目的选民应立即将他们的意见告知小组，以便尽早解决该问题。

需要达成共识批准的行动项目必须至少获得 3 约束力 1 票和 否决票 。一项需要多数票通过的行动项目，必须至少获得 3 票具有约束力的 1 票和 -1 票而不是 -1 票(即，多数票的法定人数至少为 3 票)。所有其他操作项目都被认为是懒惰的批准，直到有人投票 -1 ，之后再由他们以协商一致或多数表决的方式决定，具体取决于操作项目的类型。

在适当的时候，JIRA 问题中应计票。所有投票必须发送到邮件列表或直接添加到 JIRA 问题中。

操作项的类型

• 长期计划

  • 长期计划只是宣布组成员正在处理与 Log4j 软件有关的特定问题。这些没有经过表决，但是不同意特定计划或认为其他计划会更好的小组成员有义务告知小组他们的感受。总的来说，最好还是先花一些时间在不太合适的解决方案上，再听听其他计划。

• 短期计划

  • 短期计划是指开发人员正在开发一组特定的文档或代码文件，表示其他开发人员应避免使用它们或尝试协调其更改。这是主动避免冲突和可能重复工作的好方法。

• Release Plan

  • 发布计划用于使所有开发人员知道何时需要发布，谁将成为发布 Management 者，何时冻结存储库以创建发布，并进行其他分类以防止我们在发布过程中绊倒自己。最后的 Moment。懒惰的多数(至少 3 x 1 且比-1 多 1)决定了发行计划中的每个问题。

• Release Testing

  • 构建新版本后，必须对其进行测试，然后才能发布给公众。在发布发行版本之前，需要获得多数批准。

• Showstoppers/Blockers

  • Showstoppers 是一些问题，需要在下一次公开发布之前进行修复。为了特别关注此问题，它们在 Jira 中列出。当问题在吉拉(Jira)中被列出时，它就成了风头浪尖，并且依懒惰的共识仍然如此。

对当前活动存储库的所有产品更改均需遵守惰性协议。提交更改之前，对分支机构(旧版本)存储库的所有产品更改都需要达成共识。

何时提交更改

想法必须先审核后再提交；补丁可以先提交再审查。通过提交然后审阅过程，我们相信进行提交的开发人员对更改具有高度的信心。在提交到存储库之前，需要讨论可疑的更改，新功能和大规模检修。任何影响可配置指令自变量语义，显着增加程序运行时大小或更改现有 API 函数语义的更改，都必须在提交之前获得邮件列表的共识批准。

每个开发人员负责通知邮件列表，并在对产品的新功能或重大更改有想法时向 Jira 添加一个操作项。 Log4j 项目的分布式性质要求提前 48 小时通知，以便正确审查重大更改-在可以提交更改之前，需要对概念或特定修补程序达成共识性的批准。请注意，成员可以否决该概念(有充分的解释)，但是如果特定补丁满足了他们的反对意见，则稍后撤回该否决权。无需提前通知即可提交单个错误修复程序。

相关更改应作为一个整体或紧密结合在一起进行。除非有必要将已完成的项目交付给已同意在短期内完成该项目的另一名开发人员，否则不要进行半完成的项目。必须先成功编译所有代码更改，并且单元测试必须在开发人员平台上通过，然后才能提交。

当前的源代码树应始终能够完成编译。但是，有时一个平台上的开发人员在提交更改时就无法避免破坏其他平台，尤其是在完成更改要求访问该另一平台上的特殊开发工具时。如果预计给定的更改会破坏其他平台，则提交者必须在提交日志中指出这一点。

提交者应对他们提交到存储库的任何第三方代码或文档的质量负责。提交给存储库的所有软件都必须受 Apache LICENSE 的保护，或包含允许在与 Apache LICENSE 相同的条件下进行重新分发的版权和许可。

如果某个投票成员之一否决了变更，则必须撤消已提交的更改，并且等同于“错误修复”的提交不能立即满足否决条件。必须取消否决权，才能将更改包含在任何公开发行版中。

changes.xml 和 Git 日志

应该在 changes.xml 文件中记录许多代码更改，所有更改都应记录在 Git 提交消息中。 Git 日志的文本和 changes.xml 条目通常是相同的，但是不同的需求有时会导致信息不同。

Git log

Git 提交日志消息包含以下信息：

• 开发人员或其他研究源代码更改/修复的人员

• 最终用户(至少指出对最终用户的影响；不必使用最人性化的措辞)

如果代码更改是由非提交者提供的，请使用 Submitted-by 属性。如果更改是逐字提交的，请标识使用“审阅者”审阅过该更改的提交者。如果更改是通过修改提交的，则使用适当的措辞记录下来，如果提交的人进行了更改，则可能是“提交了更改”，如果其他人对提交的代码做出了贡献，则可能是“提交了 xxxx 的贡献”。

示例日志消息：

LOG4J2-9999
Check the return code from parsing the content length, to avoid a
crash if requests contain an invalid content length.
Submitted by: Jane Doe <janedoe example.com>
Reviewed by: susiecommitter

changes.xml

changes.xml 是最终用户从一个版本升级到下一个版本时需要查看的信息的子集：

• 我现在该怎么做以前无法做的事情

• 现在，我们已解决了我们预期用户可能遭受的哪些问题

• 包括所有安全修复程序，以及 CVE 号。 (如果在提交时不可用，请稍后添加.)

changes.xml 中的所有条目都应包含适当的 Jira 发行号，并且应该通过在 Due-to 属性中引用非提交者的贡献来贷记它们，即使需要对该贡献进行修改。

更改的归因是负责代码更改的任何人。

提交安全修复程序

不管是 ASF 还是其他开源项目，提交漏洞修复程序的过程都不同。这些过程的一个重要方面是，是否可以使用提交日志和可能的 CHANGES 条目将针对漏洞的修复程序提交到资源库，这些条目有意掩盖了漏洞并忽略了任何可用的漏洞跟踪信息。 Apache HTTP Server 项目已决定，对我们的用户而言，此类代码更改对任何分支的首次提交将提供当时可用的最佳描述以及任何可用的跟踪信息(例如 CVE 编号)，这符合我们的最大利益。修复的提交将被延迟，直到项目确定可以共享有关该问题的所有信息为止。

在某些情况下，即使无法完全获取有关该问题的完整信息(包括更广泛地查看，测试和分发此修补程序的可能性)，尽早共享代码也具有非常实际的好处。由于仅共享代码更改才可以让熟练的分析人员确定影响和利用机制，但不允许一般用户社区确定是否应采取预防措施，因此这一担心远远超过了。

如果在确定漏洞可以被利用之前通过提交修复程序部分披露了漏洞，则 httpd 安全团队将逐案决定何时记录安全隐患和跟踪编号。

Patch Format

如果建议对软件进行特定的更改以在邮件列表中进行讨论或投票，则应以 patch 命令的 Importing 形式呈现该软件。发送到邮件列表时，消息应包含以[PATCH]开头的主题和与该补丁的操作项相对应的独特的单行摘要。后记，状态文件中的补丁摘要应更新为指向该消息的消息 ID。

应该使用 diff -u 命令从原始软件文件到修改后的软件文件来创建补丁。例如，diff -u http_main.c.orig http_main.c >> patchfile.txt 或 svn diff http_main.c >> patchfile.txt 解决某个操作项所需的所有补丁都应合并在一条补丁消息中。如果以后需要修改补丁，则应发布整个新补丁，而不仅仅是两个补丁之间的区别。然后应更新状态文件条目以指向新的修补程序消息。

在目标存储库中发出命令 patch -s <patchfile 时，完成的补丁文件应该不会产生任何错误或提示。

Teamwork

当每个人都知道并遵守“道路规则”时，开源项目才能发挥最佳作用。

• 谨慎方面的错误。如果您听不懂，请不要触摸它并在列表上询问。如果您认为您理解它，请再次阅读或询问直到确定您会这样做。没有人会怪你问问题。

• 不要破坏构建-如果您所做的更改极有可能导致单元测试失败，请运行所有单元测试。更好的是，养成在提交之前始终运行单元测试的习惯。

• 如果构建中断，并且您已进行了最近的更改，则假定已中断构建并尝试对其进行修复。尽管您可能没有做过这件事，但是与必须为您解决错误相比，这会使其他人感觉好多了。每个人都会犯错。对他们负责是一件好事。

• 请勿根据自己的喜好进行更改-该项目的style guidelines已通过 Checkstyle，PMD 和其他工具验证。如果您不是要修复错误，解决工具确定的问题或解决这些准则中明确指出的问题，请开始讨论以查看更改是否是项目想要的，然后再着手进行。我们尝试首先讨论问题，然后执行讨论中达成的共识。

• 同样，请勿提交未检查您的 IDE 所做的自动更改。代码中的一些地方在某些环境下不引起样式错误就不能符合样式准则。这些都有清晰的标记，必须保留原样。