Apache Log4j 项目准则

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

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

人，地方和事物

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

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

Issue Management

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

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

Voting

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

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

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

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

在适当的时候，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 是最终用户从一个版本升级到下一个版本时需要查看的信息的子集：

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

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

首页