2019年9月宣布支持的GitHub作为文档的来源必威国际有限公司詹金斯插件的网站.多亏了Zbynek Konecny奥利弗Vernin以及其他贡献者,现在可以将插件文档直接存储在插件存储库中,而不是必威国际有限公司詹金斯维基对于插件维护者和Jenkins基础架构团队来说,维护它是很困难的。必威国际有限公司

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

GitHub文档的例子

为什么?

通过使用插件GitHub存储库文档,插件维护者可以遵循Documentation-as-code将文档更改作为拉请求的一部分,这样后续的文档就不会被遗忘。它还提供了一个检查文档更改和添加文档贡献者识别的机会,特别是在将故事组合在一起的情况下释放起草者

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

现在还有更紧迫的原因要做迁移……如果你订阅了开发人员邮件列表,你可能也看到过r·泰勒突堤关于Jenk必威国际有限公司ins Wiki的稳定性问题,并将其设置为只读,作为稳定实例的临时措施(邮件列表的线程).尽管功能后来已经部分恢复,但基础架构团队一致认为我们应该逐步转向替代解决方案。

例子

自9月发布以来,已有50多个插件从Wiki转移到GitHub。一些例子:

角色策略的例子

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

  1. 将文档从Wiki转换为GitHub Asciidoc或Markdown格式,如果你还没有这样做。

  2. 改变< url >字段,使它指向GitHub (指南).有效链接示例:

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

  4. 发布新的插件版本

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

接下来是什么?

这个故事被追踪为网站- 406这是更广泛的子项目的一部分,使用GitHub作为Jenkins插件网站和更新管理器的数据源(必威国际有限公司网站- 637).后面的步骤包括支持显示来自GitHub发布的更新日志,从GitHub拉插件标签,显示插件logo,和使用库权限更新器作为维护者信息的来源。

如何贡献?

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

导致文档

我们正在寻找有兴趣改进插件文档和帮助我们从Wiki迁移到GitHub的贡献者。对于许多插件,文档已经在GitHub中,欢迎您提交pull请求对任何存储库。

迁移文档:

如果您对编写文档有任何疑问,请参阅这个页面或者联系我们文档SIG Gitter聊天

代码贡献

你想用Java或JavaScript写一些代码吗?或者你想从事CSS样式和改进Jenkins设计?必威国际有限公司在这种情况下,欢迎你为必威国际有限公司詹金斯插件的网站.这是我们自己的插件市场实现,我们邀请贡献这一领域。这个插件网站非常容易开发。

关于作者
奥列格Nenashev

必威国际有限公司詹金斯核心维护者和董事会成员。Oleg在2008年开始在硬件/嵌入式项目中使用Hudson,并在2012年成为Jenkins的活跃贡献者。必威国际有限公司现在他领导着几个詹金斯必威国际有限公司团体、外展计划(谷歌代码之夏Hacktoberfest),必威国际有限公司詹金斯聚会在瑞士和俄罗斯。奥列格工作CloudBees并专注于社区的关键项目。