人员、地点和事物

Apache 日志项目管理委员会

负责管理 Apache 日志项目（包括 Log4j）的志愿者团队。这包括决定作为 Apache 日志项目产品发布的内容，维护项目的共享资源，代表项目发言，解决有关 Apache 产品的许可证争议，提名新的 PMC 成员或提交者，以及制定这些指南。

Apache 日志 PMC 的成员资格仅限于邀请，并且必须得到活跃的日志 PMC 成员一致同意。PMC 成员被认为是由于他们自己的声明或在超过六个月的时间内未以任何形式为项目做出贡献而处于非活跃状态。非活跃成员可以通过扭转导致他们处于非活跃状态的任何条件（即，通过撤回他们之前的声明或通过再次为项目的运作做出贡献）再次变得活跃。成员资格可以通过除相关成员以外的所有活跃 PMC 成员一致投票撤销。

Apache 日志提交者

负责 Apache 日志项目的技术方面的志愿者团队。该团队对相应的源代码仓库具有写访问权限，这些志愿者可以对任何技术讨论进行有约束力的投票。尽管提交者通常由于他们在某个日志项目上的活动而加入，但他们将对所有日志项目具有提交访问权限。

提交者的成员资格仅限于邀请，并且必须得到活跃的日志 PMC 成员一致同意。提交者被认为是由于他们自己的声明或在超过六个月的时间内未以任何形式为项目做出贡献而处于非活跃状态。非活跃成员可以通过扭转导致他们处于非活跃状态的任何条件（即，通过撤回他们之前的声明或通过再次为项目的运作做出贡献）再次变得活跃。成员资格可以通过所有活跃的 PMC 成员（除相关成员外，如果他们是 PMC 成员）一致投票撤销。

Log4j 开发人员

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

邮件列表

Log4j 开发人员的主要邮件列表，用于讨论与项目相关的议题和更改（[email protected]）。订阅列表是开放的，但只有订阅者才能直接发布到列表中。

私人列表

日志 PMC 的私人邮件列表，用于讨论不适合公开讨论的议题，例如在发布修复之前与法律、个人或安全问题相关的议题。订阅列表仅对 Apache 日志的项目管理委员会开放（实际上：强制性）。

Git

所有 Apache 产品都使用 Subversion 或 Git 在信息库中维护；Log4j 使用Git。只有部分 Apache 开发人员对 Apache 日志库具有写访问权限；每个人都具有读访问权限。

问题管理

Log4j 项目使用 https://github.com/apache/logging-log4j2/issues[GitHub Issues] 作为其问题跟踪系统。

项目将遇到许多问题，每个问题都会导致零个或多个建议的行动项目。问题应在识别后立即在邮件列表中提出。行动项目必须在邮件列表中提出并添加到问题跟踪器中。所有行动项目都可以进行投票，但并非所有行动项目都需要正式投票。

投票

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

投票行为承担着某些义务——投票成员不仅在陈述自己的意见，他们还同意帮助完成 Log4j 项目的工作。由于我们都是志愿者，成员经常会为了处理他们的“真正工作”或将更多时间投入其他项目而变得不活跃一段时间。因此，整个组成员不可能对每个问题都进行投票。为了解决这个问题，所有投票决定都基于最低人数。

每次投票都可以以三种形式之一进行

+1

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

±0

弃权、无意见或我很乐意让其他组成员决定这个问题。如果太多人弃权，弃权可能会产生不利影响。

-1

否。在需要共识的问题上，此投票算作否决。所有否决都必须包含否决理由的解释。没有解释的否决无效。任何否决都不能被推翻。如果您不同意否决，您应该游说投否决票的人。打算否决行动项目的投票者应立即将他们的意见告知小组，以便尽早解决问题。

需要共识批准的行动项目必须至少获得3 个有约束力的 +1 票，并且没有否决。需要多数批准的行动项目必须至少获得3 个有约束力的 +1 票，并且+1 票多于-1 票（即，多数票，最低人数为三个正票）。所有其他行动项目被认为具有延迟批准，直到有人投票-1，之后它们将通过共识或多数投票决定，具体取决于行动项目的类型。

在适当的情况下，应在问题跟踪器中统计投票结果。所有投票必须发送到邮件列表或直接添加到相关问题中。

行动项类型

长期计划

长期计划只是宣布小组成员正在处理与 Log4j 软件相关的特定问题。这些计划不进行投票，但不同意特定计划或认为备用计划更好的小组成员有义务向小组告知他们的想法。一般来说，在花费时间处理不太充分的解决方案之前，最好先了解备用计划。

短期计划

短期计划是宣布开发人员正在处理一组特定的文档或代码文件，这意味着其他开发人员应该避免这些文件或尝试协调他们的更改。这是一种主动避免冲突和可能的工作重复的好方法。

发布计划

发布计划用于让所有开发人员了解何时需要发布，谁将担任发布经理，何时冻结存储库以创建发布，以及其他各种琐事，以防止我们在最后时刻互相绊倒。懒人多数（至少 3 x +1 以及 +1 比 -1 多）决定发布计划中的每个问题。

发布测试

构建新版本后，必须在将其发布到公众之前对其进行测试。在分发可以公开发布之前，需要多数人批准。

阻碍因素/障碍

阻碍因素是需要在下一个公开版本之前修复的问题。它们列在问题跟踪器中，以便将重点放在问题上。当问题在跟踪器中被列为阻碍因素并通过懒人共识保持这种状态时，它就成为一个阻碍因素。

对当前活动存储库的所有产品更改均需遵守懒人共识。对先前分支（旧版本）存储库的所有产品更改都需要在更改提交之前达成共识。

何时提交更改

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

每个开发人员都有责任在他们有关于产品的新功能或重大更改的想法时通知邮件列表并在问题跟踪器中添加行动项。Log4j 项目的分布式性质要求提前 48 小时通知，以便适当地审查重大更改——在更改可以提交之前，需要对概念或特定补丁达成共识批准。请注意，成员可能会否决概念（并提供充分的解释），但如果特定补丁满足他们的异议，他们可能会撤销该否决。提交单个错误修复不需要提前通知。

相关的更改应作为一组提交，或非常接近地提交。未完成的项目不应提交，除非这样做对于将接力棒传递给同意在短期内完成项目的另一位开发人员是必要的。所有代码更改必须在提交之前在开发人员的平台上成功编译并通过单元测试。

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

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

如果提交的更改被投票成员之一否决，并且否决条件无法通过等效于“错误修复”提交立即满足，则必须撤销该更改。在更改可以包含在任何公开版本中之前，必须撤销否决。

变更日志和 Git 日志

许多代码更改应记录在 src/changelog/.<releaseMajorVersion>.x.x/<issueId>_<shortSummary>.xml 文件中，所有更改都应记录在 Git 提交消息中。通常，Git 日志的文本和变更日志条目相同，但不同的要求有时会导致不同的信息。

Git 日志

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

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

• 最终用户（至少指出对最终用户的含义；不必使用最友好的措辞）

如果代码更改由非提交者提供，请使用 Submitted-by 进行归属。如果更改按原样提交，请使用 Reviewed-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
        

变更日志

变更日志是最终用户在从一个版本升级到下一个版本时需要查看的信息的子集

• 我现在可以做哪些以前做不到的事情

• 我们预计用户可能遇到的哪些问题现在已修复

• 所有包含的安全性修复，以及 CVE 编号。（如果在提交时不可用，请稍后添加。）

所有变更日志条目应包含适当的问题编号，并应通过引用非提交者来表彰他们做出的贡献，即使需要对贡献进行修改。

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

提交安全性修复

开源项目（ASF 或其他项目）对漏洞修复的提交有不同的程序。这些程序的一个重要方面是，是否可以将漏洞修复提交到存储库，而提交日志和可能的 CHANGES 条目有意模糊漏洞并省略任何可用的漏洞跟踪信息。Apache HTTP Server 项目已决定，对任何分支进行此类代码更改的初始提交将提供当时可用的最佳描述以及任何可用的跟踪信息（例如 CVE 编号），这对我们的用户来说是最有利的。提交修复将延迟到项目确定可以共享有关该问题的全部信息为止。

在某些情况下，即使无法提供有关该问题的全部信息，也早点共享代码也有很多实际好处，包括更广泛地审查、测试和分发修复的可能性。但这与以下担忧相抵触：仅共享代码更改允许熟练的分析师确定影响和利用机制，但不允许一般用户社区确定是否应采取预防措施。

如果在确定错误可利用之前提交修复，从而部分披露漏洞，则 httpd 安全团队将根据具体情况决定何时记录安全影响和跟踪编号。

补丁格式

当在邮件列表中提出对软件的特定更改以供讨论或投票时，应以对 patch 命令的输入形式呈现。发送到邮件列表时，消息应包含以 [PATCH] 开头的主题以及与该补丁的行动项相对应的独特的一行摘要。之后，STATUS 文件中的补丁摘要应更新为指向该消息的 Message-ID。

补丁应通过使用 diff -u 命令从原始软件文件到修改后的软件文件创建。例如，diff -u http_main.c.orig http_main.c >> patchfile.txt 或 svn diff http_main.c >> patchfile.txt 解决行动项所需的所有补丁应在一个补丁消息中连接起来。如果后来需要修改补丁，则应发布整个新补丁，而不仅仅是两个补丁之间的差异。然后应更新 STATUS 文件条目以指向新的补丁消息。

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

团队合作

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

1. 谨慎行事。如果您不理解，请不要触碰它，并在列表中询问。如果您认为自己理解了，请再次阅读或询问，直到您确定自己理解为止。没有人会因为您提出问题而责怪您。
2. 不要破坏构建 - 如果您所做的更改有丝毫可能导致单元测试失败，请运行所有单元测试。更好的是，养成在进行提交之前始终运行单元测试的习惯。
3. 如果构建中断，并且您最近进行了更改，那么假设是您破坏了它，并尝试修复它。虽然可能不是您所做的，但这会让其他人感觉比不得不为您修复错误要好得多。每个人都会犯错。对错误负责是一件好事。
4. 不要更改内容以匹配您的个人喜好 - 该项目有 样式指南，这些指南通过 checkstyle、PMD 和其他工具进行验证。如果您没有修复错误、修复工具识别出的问题或修复这些指南中明确提到的问题，那么请开始讨论，看看项目是否希望进行更改，然后再开始着手进行更改。我们尝试先讨论，然后实施在讨论中达成的共识。
5. 同样，不要在未审查的情况下提交 IDE 自动进行的更改。代码中有一些地方无法符合样式指南，否则会导致某些环境中的错误。这些地方已明确标记，必须保持原样。