在2019年9月,我们宣布了对GitHub作为必威国际有限公司詹金斯插件站点文档来源的支持。感谢Zbynek Konecny奥利弗Vernin以及其他贡献者, 现在可以将插件文档直接存储在插件储存库中,而不是必威国际有限公司詹金斯维基中,对于插件维护者和詹必威国际有限公司金斯基础设施团队来说,这在过去是很难维护的。

这篇博文可能对插件维护者和那些想为詹必威国际有限公司金斯文档做贡献的人来说很有趣。我将描述如何将插件文档迁移到GitHub并获得如下页面:

GitHub文档的例子

为什么?

通过使用插件的GitHub仓库存储文档,插件维护者可以遵循文档即代码的方法,将文档更改作为拉请求的一部分,这样就不会忘记文档的后续工作。它还提供了一个评论文档更改以及增加文档贡献者的认可度的机会,尤其是如果与故事释放起草者结合。

不幸的是,在2019年9月之前,GitHub文档的使用引起了一些问题。首先,许多插件维护者已经将他们的文档迁移到GitHub,这导致了文档的碎片化(Wiki、GitHub j必威国际有限公司enkins.io)。为了解决这个问题,插件维护者仍然需要使用重定向来维护存根Wiki页面,用户不得不花一些时间来找出真正的文档在哪里。通过支持GitHub作为文档来源,我们允许维护者逐步淘汰插件Wiki页面,同时改善用户体验。

现在进行迁移还有更紧迫的原因,如果你订阅了开发者邮件列表, 你可能还看到了r·泰勒突堤关于詹必威国际有限公司金斯Wiki稳定性问题的声明,并将其设置为只读,作为稳定实例的临时措施(邮件列表主题)。虽然功能后来部分恢复了, 基础架构团队一致认为,我们应该逐渐转向替代解决方案。

例子

自从9月份宣布以来,超过50个插件已经从Wiki迁移到GitHub。几个例子:

角色策略的例子

如何为你的插件启用GitHub文档?

  1. 将文档从Wiki转换到GitHub Asciidoc或减价格式,如果你还没有做。

    • 它可以用半自动的方式完成,请看这里的指南。

  2. 更改pom.xml中的< url >字段,使其指向GitHub (指南)。有效链接的例子:

    • https://github.com/必威国际有限公司jenkinsci/mailer-plugin——插件站点将使用GitHub REST API来提取README

    • https://github.com/必威国际有限公司jenkinsci/ssh-credentials-plugin/blob/master/doc/README.md- 从自定义位置提取插件页面

  3. 可选:添加徽章到页面,以改善外观和感觉,并为用户提供快速链接。变更日志、聊天室、插件站点和安装量都有标准的徽章。

  4. 发布新的插件版本

  5. 等待几个小时,直到更改传播。之后,必威国际有限公司詹金斯插件站点将会展示来自GitHub的新文档。

下一步?

这个故事被跟踪为网站- 406,它是使用GitHub作为詹金斯必威国际有限公司插件站点和更新管理器(网站- 637)数据源的更广泛子项目的一部分。后面的步骤包括支持显示来自GitHub释放的变更日志,从GitHub中提取插件标签,显示插件标志,以及使用库权限更新器作为维护者信息的来源。

如何贡献?

10月是一个贡献的好机会!插件文档是Hacktoberfest活动中的一个特色项目, 我们欢迎所有对文档和代码库的贡献。

为文档做贡献

我们正在寻找有兴趣改进插件文档并帮助我们从Wiki迁移到GitHub的贡献者。对于几十个插件来说,文档已经在GitHub中,欢迎你针对任何仓库提交拉请求。

迁移文档:

如果你有任何关于贡献文档的问题, 请查看这个页面或者在医生团体git聊天室联系我们。

贡献代码

您想用Java或JavaScript编写一些代码吗?或者你愿意致力于CSS样式并改进詹金斯必威国际有限公司的设计吗?在这种情况下,欢迎向必威国际有限公司詹金斯插件站点做贡献。这是我们自己的插件市场实现,我们邀请对这个领域的贡献。这个插件站点很容易开发。

关于作者
奥列格Nenashev

奥列格是CloudBees的活必威国际有限公司跃Jenkins贡献者和工程师。他拥有硬件工程博士学位,在研发和自动化领域有10年的经验。奥列格为詹金斯核心做出了贡献必威国际有限公司远程和插件角色的策略EnvInject所有权等。他还组织必威国际有限公司詹金斯聚会和事件GSoC