手册:开发图书馆

来自MyaWiki.Org
(重定向)作曲家/PACGIST.ORG
跳转到导航 跳到搜索

其他语言:

这些是基于最初开发为MeaWiWiKi或相关维基媒体项目的代码的创建、发布和管理库的指南。其中有些是PHP专用的,但有些是通用的,适用于所有语言。

理论基础[编辑]

越来越多的人希望将有用的库从核心的MyaWiKi应用程序中分离出来,并使它们在非基于MeavaWiKi的项目中得以使用。图书馆化“MyaWiKi”被认为具有几个长期优势:

  • 通过将代码组织成易于理解的简单组件,为新的(和有经验的)开发人员提供更好的生活。
  • 通过鼓励开发者(在内核中)将他们的工作开发为具有明确定义的接口的可重用模块的反向惯性。
  • 用独立的可测试单元开始对核心可行单元进行真正的单元测试
  • 以一种独立于该目标的方式提供面向服务架构的过渡步骤。
  • 鼓励重用和集成更大的软件生态系统。做正确的,这将提供一个有用的手段,扩大我们的开发能力,通过招聘图书馆的作者急于展示他们的工作在前10网站。
  • 分享我们令人敬畏的图书馆与其他人,并鼓励他们的贡献,即使他们不是特别感兴趣,使我们的网站更好。

成功的,这些图书馆需要发展他们自己的生活,独立于MeaWiki。因此,图书馆的作者在图书馆的成功中有一定的纬度和独立性。这些政策在很大程度上取决于图书馆的主要维护者,而且所做出的选择可能与MeaWiki核心背离。注意,主要的维护者可能不是大多数代码(或任何一个)的原始作者,并且将有权限独立地决定关于库的内容。保持者获得的纬度的数量与他们所维护的图书馆的承诺量、可信度和努力程度成正比。为了实现这个战略

储存库指南[编辑]

维基媒体基金会可能会投资于将代码审查从GITHUB转移到内部审查工具(PHBRICCAR)的工具。最后,这应该消除与WikimidiaFoundation或Github托管主Git存储库之间的区别。在短期内,GeRIT托管是默认的托管选项,除非在努力吸引来自外部开发人员的一部分贡献的情况下除外。

不要在个人用户的GITHUB帐户下进行托管。它使基于资料库所有者的拉请求的代码审查变得复杂,并使共享库的管理变得困难。请注意:这并不意味着它必须专门在WikimeDa帐户下托管;事实上,在不同于特定项目的组织帐户下进行项目比较方便。塞斯詹斯.

知识库命名指南[编辑]

根据主机位置可能有所不同。尽可能合理地遵守当地的公约。不要在仓库名称中添加“Wikimidia-”前缀。在GRITIT上,Git存储库应该命名为“MiTaWiki/LIBS/< Name >”。

问题跟踪指南[编辑]

  • 灭菌器
  • github

您的库的问题跟踪应该与您的Git宿主匹配,以减少匹配提交和请求请求的冲突,反之亦然。因此,GRITIT托管回购应该维基媒体的实例而GITHUB托管的RePOS应该使用GITHUB的内置问题跟踪器。

代码审查指南[编辑]

项目代码评审应使用与主GIT托管最密切相关的工具。无论主机平台的选择如何,都强烈鼓励预合并代码审查和单元测试。公然的自我融合行为在GITHUB上看来是令人厌恶的,因为它一般都在GeRIT。

如果主托管是通过GITHUB,则应该通过拉请求而不是直接推到主机来提出更改。在大多数情况下,拉取请求应该来自与用户自己的GITHUB帐户相关联的存储库的分支。格瑞休是一个GeRIT供电的代码审查服务,它可以与GITHUB托管库一起使用,以用于使用GErIT的项目,但出于某些原因,不想用WikimiDa托管。

代码风格指南[编辑]

我们鼓励中维基风格PHPPSR-2但是,最重要的事情是图书馆开发者社区采用的清晰性、一致性和最佳的可能性。

在创建新的存储库时,必须选择编码风格标准并使用CodeSniffer执行。还指向项目自述文件中的样式指南。

对于MyaWiKi编码风格,请使用MIDAWIKI/MIATAWIKI代码转换器旅行包

一定要使用最新版本的MealaWiki-CoDeNffffER(检查)PACKAGIST.ORG不要使用通配符版本,必须明确地进行升级,以防止主分支的不通过状态。

对于PSR-2编码风格,使用PHP代码转换器.

自动化测试指南[编辑]

合并前和合并后的测试都应该使用。测试应包括基本皮棉,单元测试和编码风格检查。

格里特[编辑]

WikimdiaGeRIT中托管的项目应该使用詹金斯。使用作曲测试入口点。连续积分/入口点详情。

一旦创建,确保也允许合并后的发布者自动生成文档和代码覆盖率(例如对于IPSET,HTTPS://DOC.Wikimdia.Org/IPSt/HTTPS://DOC.Wikimdia.Org/Copy/IPSt/可以在项目中启用这些作业。集成/配置储存库(实例提交:GRITIT改变227615或者,将任务提交到第二类CI配置项目.

github[编辑]

GITHUB托管项目可以使用特拉维斯进行预合并测试。参见CSSJANUSTravIS.YML作曲家JSON作为一个例子。镜像到GITHUB的项目可以使用特拉维斯进行后合并测试。

包装指南[编辑]

PHP库应该发布PACKAGIST.ORG. 添加新软件包时:

  1. 跟随JSON最佳实践并在您的存储库中添加一个。
  2. 配置包装服务钩在GITHUB回购中:
    • 使用GITHUB.com镜像作为Git URL,这将允许作曲家下载可以被缓存的ZIPBARK。
    • 问一个维基媒体GITHUB组织的所有者在GITHUB回购中设置PACKAIST.ORG服务挂钩。
  3. 向Packagist.org提交回购协议:
    • 登录到WikimiDa帐户PACGIST.ORG并提交GITHUB URL。
  4. 确保“MeaWiKi”和“Wikimidia”帐户都是包的维护者。

下列人员可以访问不同的帐户,以防由于任何原因而需要更新包:

通过作曲家和包装师分发的包也应该包括GITS属性在他们的Git存储库中的配置文件,它不包括在生成的包中运行时不需要的测试和实例等文件。{维基媒体/CDB库是一个很好的例子:

GITAttest导出忽略Is.GiTrimeExtEngestRealEng.RealEng.YML导出忽略.doxFILE导出忽略>复合器.JSON导出忽略.doc导出忽略.ppPC.xml输出忽略忽略pHIPUNIT.xML.DIST输出忽略测试出口忽略

请注意,Copy.JSON应该被排除在外,这有点违反直觉。

许可证指南[编辑]

对于几乎所有从MyaWiKi中提取的内容,很可能需要GPLV2(或更高版本)。全部贡献者必须同意从GPLV2+改变许可证,以便任何人更改许可证(除了更改为GPLV3)。新图书馆的许可证需要在代码的标题中保持清晰的标记,并且完整的许可证文件(通常称为“许可证”或“复制”)必须被载入新项目。

对于一个完全由新代码组成的库,任何遵照开源定义可能是可以接受的,但是麻省理工学院GPLV2+Apache许可证2许可证可能是最容易采用的。包括贡献版权授予条款,这对于确保项目代码库的完整性很重要。ApACE2和MIT许可证被视为更多。许可的,在这一点上,它允许衍生品作品包括一份独立的新捐款许可证。

文件指南[编辑]

自述文件[编辑]

任何一个库都应该有一个ReMe.MD文件,它在高层次上描述项目。此文件应使用格式化降价大多数Git浏览器通常支持的语法(例如用于标题、链接和代码块),同时也是人类可读的。

良好的读数。

  • 浅谈图书馆解决的主要使用案例
  • 如何安装图书馆
  • 如何使用图书馆(散文和简短的代码示例,如果可能的话)
  • 如何投稿
    • 许可证名称(GPL-2,…)
    • 在哪里提交错误
    • 在哪里提交补丁
    • 链接到编码标准
    • 如何运行测试
    • 自动测试结果在哪里

代码文档[编辑]

添加用于生成代码文档的管道。常见的选择是:

查看现有图书馆的文档HTTPS://DOC.Wikimdia.ORG举个例子,看看这些看起来像什么。连续积分/入口点关于如何配置这些。

关于Wiki文档[编辑]

图书馆应该在MyaWiki.Org上有一个简短的页面,记录他们的目的、历史和相关链接。完整列表):

建立新图书馆[编辑]

新的库需要很多不同的公共文件来支持库(.gITActEngices,Cyrul.JSON,Doxyfile,PHPunIt.xml等)。为了使这更容易,有工具将引导扩展为您。

常用组合[编辑]

  • 在GeRIT中主持并发布给包装商维基媒体命名空间
  • 在WikimediaGithub组织中主持并发布给包装商维基媒体命名空间
  • 托管在另一个GITHUB组织,并发布给包装商,作为维基媒体或MiaWiKi以外的东西(例如CSSJANUS)。

当托管在GeRIT中时,该项目应该与GeRIT代码审查、PHBICKART错误跟踪和Wiki文档等任何“典型”维基媒体赞助项目一起运行。

如果在GITHUB托管,项目可以合理地选择通过拉请求进行代码审查,并在GITHUB上托管bug跟踪程序。这种选择应该仔细考虑在项目的基础上,因为代码审查和问题跟踪工具来自更大的维基媒体社区的差异有一些缺点:

  • 这个布格朗格勒预计不会监视您的项目的问题。
  • MeaWiKi开发者社区的成员可能会在PHBRICCAR中对您的产品提出错误。
  • 在项目和MeaWiWi之间移动bug报告将是一个更为复杂的过程。

如果可以创建更好的机器人以在两个环境之间集成,这些缺点可能会随着时间的推移而减少。

在一个独立的GITHUB组织下进行托管对于某些项目(CSSJANUS、WiKiTaA、语义MealaWiKi……)来说是有意义的。在CSCSJANUS这样一个图书馆试图建立一个跨社区和跨语言的标准工具集时,这一点尤其合理,只有一部分工具与维基媒体世界重叠。

将现有的GITHUB回购协议转换为维基媒体[编辑]

  • 在一张票里存入一张票噬菌体库化项目转让请求。
  • 当接触时,将存储库转移到响应的维基媒体GITHUB管理员。
  • 管理员将把项目转移到维基媒体并给您提供访问权限。

提取库的技巧[编辑]

提取库的细节将根据提取的代码和当前与其他MeaWiKi特定类的纠缠而变化。在最佳情况下,要提取的代码已经包含在包含/库MIATAWIKI/COR.GIT目录,因此完全不受限制。建议不在这种状态下的代码逐步更新和重构,直到出现这种情况为止。

一旦你得到所有的代码包含/库事情变得更直接了:

  1. 在这个RFC中遵循其他准则创建一个新项目。
  2. 导入代码包含/库进入你的新项目〔1〕.
    • 有可能使用GIT滤波器分支提取保留历史记录的文件副本,但目前不认为这是提取的先决条件。在新项目的自述文件中,将当前的文件头带入新项目并提供文件出处的文件就足够了。〔2〕.
  3. 创建适当的作曲家JSON文件如下最佳实践面向项目并向包装商发布〔3〕.
  4. 标记存储库以创建稳定的发布。
  5. 提议改变MITAWIKI/VANDOR.GIT导入新项目的稳定发布〔4〕. 手册:外部库更多细节。
  6. 提议改变作曲家JSON进入MiTaWiki/Ci.GIT要求新项目的稳定发布〔5〕.

还可能需要引入垫片类。MiTaWiki/Ci.GIT在提取的库和现有的MeaWiKi代码库之间提供向后兼容的桥。这个国开行图书馆这样做是为了提供向后兼容的类名,而不需要使用新的名称。国开行命名空间〔6〕.

标签发布[编辑]

  • 在确定下一个版本号时,坚持语义版本控制
  • GPG通过添加标记来标记-S查看标签命令
  • 您还可能希望在注释标签注释中提供变更日志。
  • 然后git推-标签提交标签。

首次发行后[编辑]

一旦存储库被引导,初始发布就已经完成。下面是一些要考虑的下一步:

  • 在MyaWiki.Org上为这个库创建一个页面。这一页应该指出:
    • 源代码(例如GIT.Wikimdia.Org或Github.com)。
    • 已发布的包(例如PACKAGIST.org或NPMJS.org)。
    • 问题跟踪器(例如PHabReabor工作板,或GITHUB问题)。
    • API文档(如doc.Wikimdia.org)。
  • 输入GITHUB镜像的描述和URL。特别是如果它只反映了GITHUB,这很容易被忘记。输入一行描述并输入MyAuthWik.Org页面(如果存在)的URL,或者输入DOC.Wikimdia.Org页面。HTTPS://Github. COM/WikimeDaa/CDBHTTPS://Github. COM/WikimeDaa/Oojs举个例子。

RFC信息[编辑]

请求评论(RFC)
发展图书馆
组件 综合
创作日期 2014-1224
作者(S) BDavis(WMF)
文档状态 实施
认可的。斯塔林说话21:45,14月2015日(UTC)
综合2014-1224BDavis(WMF)认可的。斯塔林说话21:45,14月2015日(UTC)

这起源于请求置评“提取、出版和管理图书馆指南”。决定是将这个页面移出RFC空间,并将其作为文档进行改进。

也见[编辑]

推荐信[编辑]