我们开源Docs.github.com
上周，我们开源了GitHub的所有产品文档，以及支持它的Node.js web应用程序。请查看我们新的公共存储库，网址为：jgithub.com/gihub/docs。
这篇文章讲述了我们为什么要将文档开源，我们在此过程中构建和开源了哪些工具，以及我们是如何努力使项目欢迎外部贡献者的。
开源社区喜欢创新。我们的Docs团队也很有创新精神，但数量相对较少。我们开源的docs.github.com欢迎更广泛、更多样化的人提出新的想法和贡献，就像您一样！
我们将GitHub的产品文档开源，以帮助证明私营公司将其产品开源是可能的(也是有益的)。多年来，GitHub已经开源了数百个项目，但docs.github.com是我们迁移到开放中的第一个私人生产服务。我们希望我们的应用程序设计、自动化工作流程和对外部贡献的开放能够成为其他希望开放其私人项目并从社区协作中受益的组织的典范。
Docs.github.com是一个国际化的网站，文档被翻译成日语、中文、西班牙语和葡萄牙语，不久将支持更多语言。与此同时，Node.js国际化工作组也在努力将Node.js文档本地化。Js项目面临许多与我们相同的挑战。他们使用GitHub存储库、GitHub Actions和Crowdin.com的本地化平台为开源社区构建工作流和工具。我们希望开源的GitHub文档对GitHub和Node.js社区互惠互利。通过合作，我们将能够更透明地共享实践、工具和工作流。@Crowdin-node和GitHub组织就是为了这个目的而存在的，那里的工具是由来自Electron、GitHub Docs和Node.js项目的人员维护的。我们目前与专业翻译人员合作，将我们的内容本地化，但我们希望最终也能向外部贡献者开放翻译过程。
当GitHub Docs团队的成员向第三方供应商(如Fastly、Crowdin、Algolia或Heroku)提出支持请求时，我们通常会详细描述我们试图解决的问题。这一耗时的过程可能会导致在私人支持渠道中进行大量的来回沟通。既然GitHub/docs是公开回购，我们就可以直接链接到与手头事情相关的代码或GitHub问题。我们的供应商可以(并且经常这样做)克隆我们的repo，尝试解决方案，甚至打开拉请求来帮助解决问题，而不是建议我们尝试。这不仅帮助了我们的团队，而且加强了我们与供应商的关系，并留下了我们如何解决问题的公共记录，其他人可以学习。
多年来，GitHub已经开源了许多东西，从像Electron这样的成熟平台到像GitHub Desktop和Ggh CLI这样的工具，再到像joctokit/rest.js和Soctokit.rb这样的API客户端库，以及大量的NPM软件包。我们还开源了非软件的东西，比如我们的员工知识产权协议和产品路线图。
但GitHub/docs与GitHub开源的所有其他项目有点不同：它不是一个独立的工具或库，而是一个包含我们所有产品文档的repo，以及支持它的web应用程序。这个应用程序创建于7年多前的2013年，有着悠久而丰富多彩的历史。
Idocs.github.com(最初是help.github.com)的第一个版本是Ruby on rails应用程序。后来使用Jekyll和Nanoc将其转换为静态站点，Nanoc是另一个Ruby静态站点生成器。如今，该网站由支持动态路由和内容呈现的Node.js web服务提供支持。
多年来，该站点的工具发生了变化，但Jekyll站点的许多久经考验的创作惯例被保留了下来：
在将GitHub Docs重新构建为Node.js应用程序时，我们一直在寻找机会将其不同部分开源：
开源GitHub Docs面临的独特挑战之一是找到一种方法将所有内容公之于众，同时仍然能够私下就即将发布的产品进行协作。为此，我们决定创建两个git存储库(一个是公共的，一个是私有的)，并着手寻找一种方法来自动保持这两个库的同步。
我们求助于GitHub Marketplace网站寻求解决方案。尽管似乎没有一种现有的工具可以满足我们的确切需求，但有一些工具接近了我们的需求：Pull是一款GitHub App，旨在自动执行经常乏味的任务，即让分叉回购与其上游回购保持同步。
我们联系了Pull应用程序的作者魏鹤，看看他是否有兴趣与我们合作开发一个类似的应用程序，但用于双向同步repos。魏愉快地接受了挑战，我们一起着手构建Repo Sync，这是一个使用Docker、Git、shell脚本、GitHub操作和GitHub Container Registry的新开源工具。
Repo Sync是一组灵活的GitHub操作，用于保持git存储库同步。使用按计划运行的单个操作工作流文件，我们可以保持私人和公共文档存储库的主要分支同步，而无需人工干预。
今年早些时候，我们将help.github.com和developer.github.com合并为一个网站，名为www.docs.github.com。在此迁移之前，GitHub的所有rest API参考文档都混合了非结构化Markdown、嵌入式Ruby、液态模板和手工粘贴的卷曲输出。当GitHub的rest API在十多年前创建时，并没有结构化的文档。Github.com代码库中有自动化测试，但没有机器可读的API规范。事实证明，developer.github.com上的非结构化rest API文档是关于GitHub的rest API最接近真相的来源。
在Ocotkit维护员Gregor Martynus和T.Redoc.ly承包商的帮助下，我们开始了一段漫长的旅程，将GitHub的REST API参考文档反向工程为机器可读和人类可编辑的OpenAPI描述文件。
截至今年早些时候，这些OpenAPI描述现在位于github.com代码库中，用于创建、验证和测试GitHub的REST API。这些OpenAPI描述现在还用于生成新的Javascript客户端和Ruby的Ocockit客户端，并在.docs.github.com/rest上呈现新的REST API参考文档。GitHub的OpenAPI描述文件现在是开源的，可以在以下网址下载：jgithub.com/gihub/rest-api-description。
要了解更多关于OpenAPI(最初是Swagger)的创建和GitHub最终采用它的历史，请查看我的OpenSwagger起源故事和演讲，以及我的同事在今年的API规范会议上描述了一个使用OpenAPI和Talk的10年API的文章。
Liquid是一种开源模板语言，类似于Nunjucks或Handlebar。它是由亚马逊Shopify创建的，目的是为他们的客户提供一种安全的方式，将动态内容添加到他们的店面。Liquid是一个Ruby项目，在使用Rails或Jekyll的项目中得到了广泛采用。虽然Liquid在Ruby社区中很流行，但它仍然相对鲜为人知，很少在JavaScript生态系统中使用。我们试图找到一个NPM包来解析和呈现我们现有的液态模板，但是无法找到满足我们所有需求的完整实现。
在这一点上，我们本可以认输并迁移到另一种模板语言，但我们喜欢我们所拥有的：我们团队的技术编写人员可以轻松地使用Liquid，而我们的工程师也不特别想承担将数千个内容文件迁移到新的模板语言这一艰巨而吃力不讨好的任务。
我们联系了几个现有的与Liquid相关的NPM包的作者，在许多贡献者的帮助下，我们能够弃用几个旧的和未维护的包，将Liquid-node重新命名为Liquid，将其代码库从CoffeeScript转换为JavaScript，并改进其测试和文档。
我们喜欢把东西自动化。如果人工任务枯燥、重复、耗时或容易出错，我们会寻找机会将其替换为自动化。
GitHub Docs团队接受了GitHub流的概念，这是一个连续的交付周期，其中作为正常拉式请求工作流的副产品，自动将更改分阶段、自动测试并部署到生产中。换句话说，任何人都应该能够在不离开github.com网站的情况下做出贡献、预览、测试和发布。
当在GitHub/Docs上打开拉取请求时，该拉取请求分支中的更改会自动部署到临时过渡/审查应用程序。这使得任何人都可以很容易地在实时应用程序中查看更改，而不必下拉更改并在当地环境中查看它们。当拉取请求合并到默认分支时，会销毁临时暂存应用，并将更改部署到生产中。
我们的团队享受这种“免提”的连续交付工作流已经有一年多了，我们再也不能回到有限的试运行实例和聊天部署命令的时代了。
我们希望为GitHub文档做贡献的过程对外部贡献者和GitHub员工一样简单，我们已经考虑到这一点来构建我们的测试和部署工具。当外部贡献者在GitHub/docs上打开拉取请求时，我们将运行相同的持续集成测试，并创建与我们为GitHub员工所做的相同的短暂试运行应用。
开源不仅仅是关于代码。成功的开源项目维护人员知道，项目的健康不仅取决于源代码，还取决于参与其开发的人员的福祉。除了通过和执行国际行为准则外，重要的是承认各种贡献，这样人们就知道他们的努力是有价值的。
所有贡献者都是一个很受欢迎的开源项目，它使得感谢贡献变得很容易。所有贡献者都包括一个规范、一个GitHub机器人，以及一个快速向您的项目添加贡献者的高级命令行工具。它还支持多种投稿类型：
我们现在在所有与文档相关的开放源码存储库上使用All Contributors项目。例如，请查看GitHub/docs自述文件。
我们花了很长时间，做了很多工作才来到这里。弄清楚如何开源这个存在已久的私人项目一直是一个有趣的挑战，但我认为最好的还在后头。公开工作是构建软件最有趣的方式，我迫不及待地想看看docs.github.com网站是如何发展的，因为我们邀请了来自世界各地的贡献者来帮助塑造它的未来。
