管理文档

我们是谁

Jenkins 项目是一个相关于 Jenkins 软件的社区。我们是一群热爱开源,着眼于开发,使用,提升 Jenkins 软件功能开发者,以及其他进行相关利益活动的人员。

本项目附属于 Software in the Public Interest (SPI)。SPI 是一个非盈利组织,提供必要的法律保护和开源软件运作需要的帮助。它也是本项目的法律上的拥有者和资产管理者。

我们的哲学

低门槛

我们努力地降低加入本项目的门槛,就如我们接纳所有人的提交,而不要求提交者通过某些方式来证明其有这个能力。另外我们认为每个人都是优秀的,除非他们自己经常犯错,我们对所有人都一视同仁。我们认为每个人的贡献都非常珍贵,所以任何多余的流程都是对吸引潜在的贡献者的阻碍。

Jenkins 核心项目,插件,模块以及独立的相关项目都采取低门槛策略,以便于减少参与和交流的阻碍。我们也努力的让每个人都找到他们自己舒适的工作方式,以便于高效,没有冲突的合作。我们认为每个人都有表达他们自己想法的权利。

相信人们的进步也是低门槛策略的原因。本项目的很多代码都不是原作者在维护。我们也鼓励新来者接管老的项目。我们认为早的贡献者应该充分的尊重新的贡献者,原始贡献者的不作为不应阻止新贡献者做出改变。

任人唯贤

我们推行低门槛方式,并不意味着每个人在社区里都有相同分量。我们会衡量每个人的贡献价值,来给与不同的责任和权力,即 任人唯贤。贡献不仅仅停留在代码修改,还包括对其他人的帮助,如 PR,维护基础设施等等。

公开透明

我们公开透明的管理项目,这包括从决策到代码变更的所有事情。

兼容性问题

我们认识到,用户希望现有的版本可以兼容现他们过去积累的数据(包括 Hudson 升级到 1.395),包括在 Jenkins 的未来版本中也能正常运作。这写数据包括他们正在使用的作业配置,构建记录和插件二进制文件。Jenkins 项目非常重视维护这种兼容性,并且在删除功能时会非常小心。

我们还认识到插件开发人员希望他们所依赖的 API 和其他代码在 Jenkins 的未来版本中仍然可用。这并不是说我们永远不会删除任何内容,但我们会非常谨慎地执行此操作。

因为一个插件可以依赖于另一个插件,所以我们期望许多其他插件所依赖的插件具有相同的原理。

自动化

Jenkins 项目的目标之一是实现更多自动化,我们在开发 Jenkins 时应用相同的原则。因此,我们开发并使用许多守护进程,机器人和脚本来执行本务活动和日常操作。

这不仅节省了我们做更多创造性工作的时间,而且还通过减少一个开发人员被另一个开发人员的阻塞来帮助减少进入障碍。此外,它还使我们的测试受益。

许可证

Jenkins 项目使用 MIT 许可证 作为我们开发的代码的首选许可证。除非另有说明,否则所有代码均在 MIT 许可下。

Jenkins 的核心完全在 MIT 许可下,我们的大多数基础设施代码(运行项目本身的)以及许多插件都是如此。我们鼓励托管插件使用相同的 MIT 许可证,以简化用户使用流程,但插件可以自由选择自己的许可证,只要它是 OSI 批准的开源许可证。

这不应该与专有插件相混淆,我们鼓励人们自己编写以供内部使用的插件,而不必使源代码可用。但 Jenkins 项目不会托管这样的插件。

贡献者许可协议 (CLA)

为了进一步明确项目的知识产权,我们要求核心提交者签署贡献者协议。此 CLA 与 Apache 的 CLA 相同。本协议明确赋予 SPI 一组权利,例如有效的联合版权所有权,专利授权,以及承认您拥有贡献的权限。

将这些权利分配给 SPI 有助于 Jenkins 对任何特定供应商保持中立,并且它还会使法律部门感到高兴,特别是在想要使用 Jenkins 的大型组织中。

CLA 有两种类型。每个核心贡献者都需要签署个人 CLA(ICLA),如果您不独自拥有您的贡献(例如当您的公司指派您参与 Jenkins 工作,因此如果您的公司拥有您的辛勤贡献,则公司也需要签署公司 CLA(CCLA)。有关更多详细信息,请参阅 Apache 中的讨论。可以从以下 URL 获取 CLA 表单:

为了平衡额外的开销和较低的进入门槛,此政策仅适用于核心,我们欢迎任何愿意为插件贡献者提交 CLA。

提交 CLA 的详细信息记录在 infra-cla README 自述文件中。

核心中的第三方库许可证

Jenkins 项目在很大程度上依赖于第三方库。我们认为,重用我们的能力比重新发明更好,这样我们的宝贵资源就可以用在其他地方。

Jenkins 作为一个整体需要成为一个开源项目,所以我们一直限制自己只使用 OSI 认可的开源许可证的第三方库(例如 Apache 软件许可证,BSD 许可证,MIT 许可证,Eclipse Public)许可证和较​​小的 GNU 公共许可证。)此外,为了使核心可以重复使用最广泛的用例,我们拒绝所谓的 copyleft licenses 许可证,将许可证限制为特定许可证(例如 GNU 公共许可证)。最终,我们将以下许可证指定为我们可以依赖的已批准许可证。其他许可证需经委员会批准:

在核心中,构建过程确保考虑依赖库的所有许可证。 换句话说,我们要求依赖 POM 以 Maven 方式声明自己的许可证,或使用 许可证完成脚本提供一个 POM 缺少的信息。

结果打包到核心中,并且可以从 应用程序本身 中看到。它也可以在 war 文件中以 XML 格式提供。

插件中的第三方库许可证

在涉及第三方许可证政时,插件不一定遵循相同的形式。显然他们需要尊重他们使用的库的许可证,所以他们不需要使用与核心使用的相同许可证方案。

我们鼓励插件遵循相同的第三方许可证作为核心。但是后果需要自负,更多信息 FSF 对使用非 GPL 核心的 GPL 插件的看法

商标

为了保护项目和用户不会混淆使用该术语,“Jenkins” 这个名称是美国的注册商标(#4664929,由 Software in the Public Interest, Inc. 持有)。为了减少流程开销并维护我们的开源精神,我们采用Linux内核策略来使用商标。

如果您使用术语 “Jenkins” 作为您自己的基于Jenkins的软件商品或服务的商标或品牌标识符的一部分,则需要申请 sublicense。如果您的商标未注册,或者您不打算使用该商标赚钱,则无关所谓。

回答以下问题可以帮助您确定是否需要子许可证。如果您仍有疑问,请联系委员会,我们将与您一起确定是否需要申请子许可。

如果以下所有三个问题的答案都是“是”,那么您需要申请一个子许可证。如果这些问题的答案都是“否”,那么您不需要申请子许可证。

  • 我的商标是否为商标(请参阅 Linux 基金会“商标”定义 FAQ)?

  • 我的标记是否按以下顺序包含以下相邻字符串:“Jenkins”,这些字母可包括各种类型的大小写,而在外国字符的情况下,也可以使用语音翻译。

  • 我是否使用我的标记来识别与软件相关的商品或服务(请参阅如何在LF中再次定义该短语)?

可以在已批准的商标使用页面上找到项目批准的商标用法列表。

商标归属

商标归属指南主要源自 Linux Foundation trademark attribution

通用归属

即使你使用 Jenkins 商标不在子 Jenkins 许可证的范围内,你仍需要注明所有权。有两种方式:

对于每个网页,广告或出版物,Jenkins 应该有相邻的“圆圈R”字符,如下所示:

Jenkins®

在您的网页末尾,广告,出版物或媒体广播,包括以清晰易读的字体和大小的以下文字:

Jenkins® 是 Software in the Public Interest, Inc 的注册商标。

子许可证持有人的归属

Jenkins 子许可协议规定了商标应如何归属于子许可证。子许可证持有者必须在每件授权商品上醒目地放置以下图例,并且在每个授权商品或服务随附的任何文档或销售文献的标题页区域内至少放置一次

依据来自于 Jenkins 项目和 Public Interest, Inc 的软件的子许可证使用注册商标 Jenkins®。

我们理解由于地理空间因素,取得这种授权可能会很困难,所以必要时传真形式的授权也是可用的。如有任何对于这种便捷形式的不满意,可以提给我们你的意见,以做参考。

项目角色/利益相关者

管理委员会

管理委员会由三个人组成,当需要时,他们充当项目的公共代表,例如可以是对内联系的途径,如 SPI。

如果无法通过常规项目社区会议解决争议,委员会也可以作为最终决策权。委员会的决策能力更具象征性和尊重性,并且像英国女王一样“统治”而不是独裁统治。

管理委员会 页面提供更多信息,包括当前的委员会成员,以及如何与委员会的名单。

您可以在这里查看选举程序

基础设施管理员

基础结构管理员具有对各种服务器的 root 访问权限,并构建运行的从属服务器 jenkins-ci.org 和其他子域。他们保持这些服务器正常运行,安装新软件,协调镜像,处理密钥和证书,并确保我们可以继续产出代码。

由于这项工作的敏感性,基础设施管理员只能通过邀请,有些活动是闭门的。基础结构管理员经常委派给其他人对系统的部分访问权以完成某些任务。

可以在此处找到一些公共基础架构组件的管理员列表:基础架构管理员

核心提交者

核心提交者是那些对主要的 Jenkins 库(构建在 jenkins.war 中)具有推送访问权限的人。要成为核心提交者,需要签署贡献者许可协议。在被授予提交访问权限之前,不需要具有经过验证的贡献历史记录,但这并不意味着其他核心提交者永远不会还原您的更改。

CLA签名者列表将在此处维护:https://github.com/jenkinsci/infra-cla

插件提交者

插件提交者是那些对 jenkinsci GitHub 组织下托管的特定插件存储库具有推送访问权限的人。在被授予提交访问权限之前,不需要具有已证实的贡献历史。你所要做的就是申请。但这并不意味着其他现有的提交者永远不会还原您的更改。

本地化贡献者

本地化贡献者可以同时访问核心和托管插件。他们对代码和资源进行本地化/国际化相关的更改,他们推动这些更改而不寻求核心/插件提交者的批准。

用户

用户使用 Jenkins 及其插件。他们通过提供反馈,提交错误报告,为开发人员确定功能和修复程序的优先级,帮助其他用户以及让提交者感觉他们的工作是值得的,为项目做出贡献。

沟通

社区中人们之间的沟通对于项目的一致性至关重要。Jenkins项目的人员在几个不同的地方相互沟通。

邮件列表

我们鼓励将邮件列表作为开发人员和用户讨论的主要方式,因为它们具有异步性和搜索存档的能力。项目网站列出了活动邮件列表及其用途

IRC

Jenkins 项目使用 IRC 频道进行实时交互式通信。这也是活跃成员彼此联系的地方。

Twitter

@jenkinsci 是 Jenkins 项目的官方 Twitter 帐户,由基础架构管理员运营。

基础设施

源代码

GitHub JenkinsCI organization 是我们托管我们的大多数代码(见资料库的名单,便于浏览)的地方。因为我们在以前使用 Subversion 作为主源代码库,我们也有 subversion 库,其中包含所有原始项目的历史数据。一些插件仍在 Subversion 存储库中主动维护。

为了帮助对 1000 多个 Git 存储库进行分类,我们采用了一些命名约定:

  • 插件被命名为 “* -plugin”

  • 库被命名为 “lib- *”

  • 后端基础设施程序命名为 “backend- *”

为了鼓励将插件从 Subversion 迁移到 Git,守护进程用于将插件单独镜像到 GitHub。有关如何将插件迁移到 GitHub 的更多信息,请参阅此页面

用户帐户

基础架构管理员运行 LDAP 服务器和一个小前端程序,让用户在 jenkins-ci.org 上创建帐户。此帐户用于我们自己运行的所有软件。

Wiki

您正在阅读的这个 wiki 是我们用于文档的主要协作机制。这使用上述 LDAP 服务器进行访问。

Bug 跟踪

我们主要的 Bug 跟踪 由 infra 管理员维护。使用上述 LDAP 服务器进行访问。

Jenkins 运行在 Jenkins 上

我们为自己的开发运行 Jenkins 并自动执行各种基础架构任务。由于设置作业的敏感性,只有 infra 管理员才具有完全写入权限。

做决定

Jenkins 项目使用双周项目会议作为需要达成共识的事项的决策主要论坛。会议在 IRC 上进行,对所有人开放。只需将您的主题添加到 Governance Meeting Agenda wiki 页面,任何人都可以添加议程项目。请务必提供您的用户名(以便我们知道是谁提出了主题)。

是公开的会议纪要:

如果项目会议未能就特定主题达成共识,委员会将成为最终决策机构。

我们如何开发代码

核心

核心指的是一组产出 jenkins.war 二进制文件的代码和库。官方核心存储库托管在 GitHub 上。

提交者将更改直接推送到此存储库,尽管其他核心提交者仍可以在他们认为必要时还原他们的更改并进行讨论。新的提交者也可以在他们对自己的变化感觉良好时,或者如果变化微小的情况下也这样做。

感觉需要审核的新旧提交者需要使用 GitHub 的 pull request 作为征求反馈的方式。没有提交访问权限的人也使用 pull request 将他们的更改发送到核心。核心提交者应该关注待处理的 pull request,并尝试快速采取行动。

核心提交者通常自己决定要做什么。

发版

每个周末都会从主分支构建一个新版本,并以各种形式(包括 jenkins.war 本机包)发布。这使我们能够相对快速地将新功能和错误修复发送到用户手中。

LTS 发版

我们每三个月左右选择一个先前版本作为新的长期支持(LTS)版本,然后从该版本点开始创建“稳定”分支。此分支从主分支向后移植重要的错误修复,并且大约每两周构建一次补丁版本,直到选择下一个 LTS 基线。有关详细信息,请参阅LTS Release Line

核心编码公约

我们大致遵循源代码中的 Sun 编码约定,我们使用 4 个空格缩进而不使用制表符。如果您提交的更改不会过多地更改代码格式,那么通常会更加实用和受欢迎,因为它可以简化编码审查工作。尝试在单独的提交中提交格式更改和功能更改。

话虽如此,我们也不依赖严格编码约定,我们不想拒绝贡献,仅仅因为他们的代码格式与我们使用的不匹配。

插件

插件是由插件工作人员自主开发的。每个人都有自己的存储库,自己的 Jenkins-on-Jenkins 工作,自己的 bug 跟踪器组件,并维护自己的发布计划。

一些插件由少数人主动维护,他们可能有自己的本地化,例如不同的编码约定,额外的提交策略。我们这样做是为了让人们能够感受到他们作品的所有权和归属感,并且他们不会觉得他们必须遵循外部决定的规则。

由于大部分此类本地化都是隐含的,因此通常很难从外部了解给定插件的运营文化。安全的经验法则是在进行任何提交之前提前联系现有开发人员(但如果一周内没有及时响应,那么您应该随意提交。)不太积极维护的插件往往没有这样的本地化,所以在那些您觉得可以的地方,您可以提前进行更改并同时发送提示(并接受更改被恢复的可能性。)

维护者信息应列在插件维基页面的信息框中。如果您无法确定联系人,那么良好的后备选项就是开发人员的邮件列表。

插件 Wiki 页面

每个插件在 https://wiki.jenkins-ci.org/ 都有自己的 Wiki 页面,例如这个。插件维基页面应该是描述插件的作用,以及发布历史/更改日志。可以看看一些插件维基页面作为你应该做什么的指导。

这些 wiki 页面是从 Jenkins 内置的更新中心引用的,它们是用户发现插件信息的主要方式。

模块

模块是与核心分开构建的库(很像插件),但是作为JAR文件捆绑到 WAR 文件中 WEB-INF/lib,因此从用户的角度来看它就像是核心的一部分。模块可以被认为是库和插件之间的东西。它有自己的 POM,一组源代码,并且像库一样单独构建,但它获得与插件相同的编译时处理。

这有助于将大毛球(即核心)分成更易处理的小块,并允许OEM分别添加/删除功能。

提交指南

有关向Jenkins提交代码的指南,请参阅 pull请求清单

从其他地方复制代码

如果您拥有许可证,并且该许可证与 MIT 许可证兼容,则可以将代码从其他地方复制到 Jenkins 中。

最典型的情况是原始代码是在开源许可证的某个子集下许可的,例如 ASL,BSD 和 MIT 许可证。Copyleft 许可证即使是开源许可证也无法复制,例如 EPL 和 GPL。

要复制的代码必须使用其所在的许可证进行清楚标记,并且在复制时,您需要在标题中保留版权/许可证属性。还请将副本的来源指明为提交消息的一部分。

特别是,这意味着我们可以在 MIT 许可下复制 Oracle Hudson 的源代码,但不能在 EPL 下复制 Eclipse Hudson 的源代码。

本地补丁依赖项

有时,有必要在我们使用的库中进行错误修复和更改。如果库对Jenkins很重要并且对我们的用户影响很大,我们选择将本地补丁集维护到上游库,就像Linux发行版为其包维护这样的补丁一样。

我们通常打算将这些本地补丁集成到上游,因此我们将票据上游归档并提供差异。当这工作时,这使我们可以在将来的某个时刻回到原始的上游版本。这些补丁集作为并行分支在我们的 git 存储库中维护。

在某些情况下,所谓的“临时”补丁集由于我们无法控制的各种原因而变得更加永久,例如上游的停止开发,但这仅仅是因为它的结果,而不是因为我们在一开始就打算这样做。使用分布式版本控制系统,为Jenkins维护并行补丁发布并不像以前那么难。

如何加入项目

引入新的插件/工具/库

如果您开发插件,我们鼓励您与 Jenkins 项目共同维护,以便社区中的其他人可以参与。有关详细信息,请参阅托管的插件

更改现有插件

如果您只想进行少量更改而无意留下来感兴趣。通过GitHub发送拉取请求最简单。有关详细信息,请参阅使用 pull request。如果你的拉取请求没有及时得到关注,请通过开发人员的邮件列表 ping 我们,以便我们解决这个问题。

如果您想更加认真地参与,除了拉取请求之外,我们建议您考虑成为提交者。在IRC频道或开发列表中给我们留言,我们将为您设置提交访问权限。尝试通过向他们提出单挑并与他们协调来对现有开发人员保持礼貌,但如果他们没有回应,请不要让阻止您的进展。开发人员的资历是通过持续参与获得的。

帮助和接管休眠插件

通常情况下,一旦插件变得足够好(或者如果原作者改变了工作并且不再有动力去研究技术),原始开发人员会转移到其他事物上。所以我们鼓励新的开发人员或开发者不同的插件可以插入其他插件的待处理请求或处理针对它们的问题。

为此,我们还鼓励人们拿起休眠插件并将其视为自己的插件。为此,请在开发列表中给我们留言,并尝试联系上一个维护者,以了解他们是否仍然对驱动插件感兴趣。在接手之前尝试坚持联系最新的显然不活跃的维护者是我们的一项重要实践。通常的做法是在发送请求维护插件的开发者邮件中抄送他们。

许多不太活跃的插件并没有真正拥有任何明显的所有者,并且它们由人们进行协作维护,进行小的更改并在需要时发布它们。如有疑问,请在开发列表中询问。

对核心进行更改

如果您只想进行小的更改且不想在社区驻足,那么同样的过程也适用于插件,如上所述。但是,由于核心更改会影响更多人,因此,请您在 pull request 中尽可能提供详细的信息,我们将不胜感激。

如果您想更加认真地参与,请考虑获取提交权限。请参阅有关如何成为插件开发人员的部分。此外,我们需要您签贡献者许可协议(CLA)。

进行更改时,请使用惯例。例如,如果您正在考虑进行重大更改,建议您先与开发人员讨论您的更改。或者,如果您发现您想要处理的部分已被其他人积极修改,请给他们一个提醒。

贡献本地化

我们一直在寻找能够帮助 Jenkins 本地化为不同语言的人。如果您有兴趣提供帮助,请在开发列表中留言以获取提交权限,并查看国际化以了解如何进行更改的详细信息。

使用 pull request

如上所述,Jenkins 项目使用 pull request 作为获取更改的主要工作流之一。当您准备提交 pull request 时,请考虑以下清单作为最佳实践。

  • 有关如何创建 pull request,请参阅 github online help

  • 我们建议您在问题跟踪器中提交问题单,以描述您正在修复的错误或正在实施的功能。这在我们的系统上创建了一个永久记录,使未来的开发人员能够理解代码如何进入当前形态。这不是必要条件(特别是对于小的更改),但如果您这样做,我们表示感谢。

  • 使用 JENKINS-1234 作为故障单 ID 的表示法 [JENKINS-1234],在提交消息中引用故障单。这允许我们的脚本在没有人工帮助的情况下理解历史记录并生成更改日志。如果您使用该表示法 [FIX JENKINS-1234],我们的机器人将在将更改合并到存储库时以及在我们的 CI 服务器中测试更改时自动关闭依据。这些表示法可以跨系统创建有用的交叉引用,因此强烈建议使用。

  • 尝试描述您的更改,以便其他人了解您的操作。

  • 确保您没有修改与更改无关的部分(通常由IDE自动修复导入语句和其他代码格式引起)。

我们确实试图关注产生的 pull requests,但正如您在此处所见,我们很遗憾无法及时解决其中的一些问题。如果您注意到您的 pull request 在一两周内没有得到处理,请在开发人员列表中给我们留言,请考虑成为提交者并直接推送更改。有关更多信息,请参阅 Pull Request

本文说明

本文件为社区所有,如果您有疑问或变更可以提议到 下个会议议程中。

注意:本页为中文译文,仅供参考,如有疑问请以英文站点的原文为主。