写点什么

Jenkins 插件开发之旅:两天内从 idea 到发布 (下篇)

用户头像
donghui
关注
发布于: 2020 年 05 月 22 日
Jenkins 插件开发之旅:两天内从 idea 到发布(下篇)

本文分上下两篇,上篇介绍了从产生 idea 到插件开发完成的过程; 下篇将介绍将插件托管到 Jenkins 插件更新中心的一系列过程。

托管插件

托管插件包括一系列流程步骤。 笔者完成了它所有步骤(包括非必须的步骤),其中主要有两个具有标志性的任务:

  • 插件代码被托管在 jenkinsci GitHub 组织的一个仓库,然后作者拥有它的管理权限。笔者插件的代码仓库为:jenkinsci/maven-snapshot-check-plugin 。

  • 你可以将插件发布到 Jenkins 项目的 Maven 仓库,它是 Jenkins 项目所使用的更新站点的数据来源。

准备工作

在请求插件托管之前,需要完成以下几个步骤。

查找类似的插件

Jenkins 社区欢迎任何人的贡献,但为了让 Jenkins 用户受益, 它要求查找解决相同或类似问题的插件,看看是否可以与现有的维护人员联手。 可以在 https://plugins.jenkins.io 查看所有的插件, 以确认是否已有类似的插件实现了你计划实现的功能。 笔者在之前已进行过查找,并没有找到可以实现笔者计划实现的功能的类似插件。

命名规约

Jenkins 制定了一些与插件相关的命名规约。 插件开发者要确保遵循这些命名规约。

artifactId

插件的 artifactId 被用于文件基本名称,是 Jenkins 插件和更新站点的唯一标识。

它需要遵循一些发布规约:

  • 使用小写 ID ,并根据需要使用连字符分隔术语。

  • 除非名称有任何意义,否则不要在 ID 中包含 jenkins 或 plugin 。

插件名称

插件的名称在 Jenkins UI 和其它地方(如:插件站点)展示给用户。

如果可以,建议使用简短的描述性名称,如 Subversion 。

笔者所写的插件的名称为:Maven SNAPSHOT Check 。

groupId

推荐使用 io.jenkins.plugins 或 org.jenkins-ci.plugins 作为 groupId 。 但是不禁止其他组织 ID ,除非它们是恶意的(例如引用与你没有关系的组织)。 笔者所写的插件使用的 groupId 为: org.jenkins-ci.plugins 。

Java 源代码

Jenkins 项目一般遵循 Oracle Java 代码规约, 但是并没有很好的强制甚至在核心组件中。 个别的插件维护者有时会选择使用不同的风格指南作为插件。 笔者日常使用 IDEA 进行开发,之前安装了「阿里 Java 规约插件」, 因而使用它作为编码规约。

提交消息

Git 提交消息应该从引用与之相关的 JIRA 问题开始(如果适用), 然后在第一行进行简短的总结,并在随后的行中提供更多详细信息。例如:

[JENKINS-00000] Frobnicate the widget
复制代码

如果给定的提交修复了指定的问题, 那么使用以下前缀中的任何一个将会自动化解决相关的 JIRA 问题。

[FIX JENKINS-00000] Frobnicate the widget[FIXED JENKINS-00000] Frobnicate the widget[FIXES JENKINS-00000] Frobnicate the widget
复制代码

由于还没过将插件托管,笔者并没有遵循该规约, 等插件发布后,笔者将考虑遵循该规约。

License

Jenkins 项目分发的所有插件都需要是免费的开源软件。 这适用于插件源代码及其所有依赖项。 要确保在 pom.xml 文件和仓库中的 LICENSE 文件指定协议。 官方建议使用 MIT license ,它用于 Jenkins 核心和大多数插件和库, 但是任何 OSI 批准的开源 license 都可以。 笔者这里使用了 MIT license 。

要求注册的账号

通过 Jenkins 项目更新站点分发的插件需要托管在 jenkinsci GitHub 组织中, 因此需要在 GitHub 上有一个账号,并且需要有一个公共仓库来存放插件源代码。

为了完整地发布你的插件,需要注册一个 Jenkins 社区帐号, 它可以让你访问 JIRAwiki 和 Maven 仓库 。

发起托管请求

注意:Jenkins 官方自动化流程使用更容易实现的 fork + 删除的方式(见下文),而不是转移仓库所有者。

登录到 JIRA 然后在 HOSTING 项目创建一个问题。 请确保按照描述填写所有字段。 Jenkins 项目成员将在几天内审查你的请求。 如果审查人员要求你更改,那么请按照要求进行更改。

笔者提交的申请为:HOSTING-750, 比较幸运的是当天凌晨(北京时间)笔者的请求就被审查, 正巧那时笔者未眠,于是随后按要求进行了更改并在不久后该申请被审批通过。

一旦满足了所有的需求,你的仓库将被 fork 到 jenkinsci 组织中, 并且你将被邀请加入该组织,并且将为你在 JENKINS 项目中创建 JIRA 组件。

此时,将要求你删除 Jenkins 从中 fork 的仓库。 之后你可以通过再次从 jenkinsci 那里 fork 来重新创建它。 这将确保 jenkinsci 仓库是 Github 上网络图的根。 这意味着:

  • 不会混淆哪个仓库是权威仓库。

  • 即使在 GitHub 上没有大量的关注者,源代码搜索也会成功。

  • 其他人更可能在 jenkinsci 仓库中提交 pull request(这是协作的理想选择)。

创建 wiki 页面

尽管这对发布插件来说这不是严格要求的,但最好为插件创建一个 wiki 页面来存储文档。关于如何执行此操作的详细信息,请参阅插件 wiki 页面指南

笔者所写的插件的 wiki 页面为:Maven SNAPSHOT Check Plugin 。 其间除了官方文档,笔者还参考了其它插件 wiki 页面的排版。

开启 CI 构建

Jenkins 项目托管了一个 Jenkins 实例来执行插件的持续集成构建。 官方推荐通过在插件的 Github 仓库根目录创建一个 Jenkinsfile, 为在 Jenkinsci Github 组织中的插件设置 CI 构建。 典型的插件构建( Maven 或 Gradle )只需在 Jenkinsfile 中包含以下语句即可运行:

buildPlugin()
复制代码

申请上传权限

在源代码被 fork 到 jenkinsci 组织后,需要提交一个上传权限请求。 按照 jenkins-infra/repository-permissions-updater/ 仓库的 README 文件中所说的来做就可以。

Jenkins 项目在 Artifactory 上托管 Maven 制品,例如核心和插件发布。 它的权限系统与 Github 是独立的, 限制了那些用户(由 Jenkins LDAP 帐户标识,与 wiki 和 JIRA 一样)可以上传。 这个仓库包含 YAML 格式的 Artifactory 上传权限定义, 以及将它们同步到 Artifactory 的工具。

先决条件:在申请权限之前,需要先用 Jenkins 社区帐号登录一次 Artifactory 。

要请求对制品(通常是插件)的上传权限,需要提交一个 PR , 该 PR 需要创建与申请上传权限相关的 YAML 文件。 笔者所提交的 PR 为:Plugin: Permission for maven-snapshot-check-plugin 。

通过查看它可以看出该 PR 增加了一个文件:permissions/plugin-maven-snapshot-check.yml ,其内容如下:

name: "maven-snapshot-check"github: "jenkinsci/maven-snapshot-check-plugin"paths:- "org/jenkins-ci/plugins/maven-snapshot-check"developers:- "donhui"
复制代码

在创建 PR 后,会有帮助说明以及 checklist 让提交人对该 PR 进行检查确认。

等这个 PR 被审批后,插件开发者就会拥有该插件的发布权限。

发布插件

前提

要先确认拥有发布该插件的权限。

Maven 要使用的 Artifactory 凭据

需要告诉 Maven 访问 Artifactory 的凭据。 登录 Artifactory ,从用户 profile 中获取加密的密码。 在 ~/.m2/settings.xml 文件配置 server 认证信息,如下所示:

<settings xmlns="https://maven.apache.org/SETTINGS/1.0.0"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="https://maven.apache.org/SETTINGS/1.0.0                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
<servers> <server> <id>maven.jenkins-ci.org</id> <username>your_user_name_here</username> <password>your_encrypted_password_here</password> </server> </servers>
</settings>
复制代码

配置 GitHub 以接受你的 SSH key

当执行 release 时,Maven Release Plugin 会自动往仓库推送代码, 所以需要配置 GitHub 以接受你的 SSH key 。

更多信息可以参考:GitHub help on SSH 。

执行发布

当 GitHub 和 Maven 凭据配置好后, 执行一次发布应该很简单,只需要运行下面的命令:

mvn release:prepare release:perform
复制代码

可能在执行发布时会遇到 “401 Unauthorized” 或 “403 Forbidden” 之类问题, 这一般是 settings.xml 配置问题或是没有上传权限。 一些公共的问题处理方案可以查看:HostingPlugins-Workingaroundcommonissues

插件发布后,8 小时内,将可以在插件更新中心看到它。

笔者所写的 maven-snapshot-check 插件, 在插件列表页的地址为:https://plugins.jenkins.io/maven-snapshot-check 。

Jenkins 实例的插件管理页面的「可选插件」选项截图如下:


为插件分类

在 Jenkins 插件列表页面,可以对插件进行分类显示。

要为插件添加一个分类,需要向 jenkins-infra/update-center2 仓库提交一个 PR 。 笔者所提交的 PR 为:add maven-snapshot-check category 。

通过查看它可以看出该 PR 在 src/main/resources/label-definitions.properties 文件增加了一行,如下所示:

maven-snapshot-check=builder
复制代码

总结

两天的 Jenkins 插件开发之旅, 让笔者了解了插件开发的基本知识,并在托管插件的过程中学到一些知识。 然后在周末花了几个小时总结回顾,并将它写成文档。 同时也希望此文能给 Jenkins 插件开发者入门带来一点帮助!

参考


最后,想要了解更多与 Jenkins 相关的资讯、博客、技术分享,可以关注 Jenkins 公众号:


发布于: 2020 年 05 月 22 日阅读数: 825
用户头像

donghui

关注

公众号:ServerlessLife 2018.01.01 加入

还未添加个人简介

评论 (2 条评论)

发布
用户头像
这么快就有下篇了,感谢分享,这篇也推荐了。
2020 年 05 月 22 日 13:19
回复
谢谢~~
2020 年 05 月 22 日 14:23
回复
没有更多了
Jenkins 插件开发之旅:两天内从 idea 到发布(下篇)