README

官方 Fluid 驱动的 TYPO3 Gizzle 实现

这是什么？

Gizzle 是 Claus Due 编写的一个轻量级 GitHub webhook 监听器。尽可能简单地说，Gizzle 在您的仓库中发生活动时监听来自 GitHub 的请求。这个包是在 composer 项目中实现的 Gizzle，并包含了一些关键的插件，它们提供了与提交、拉取请求和 TYPO3 扩展仓库的集成。

以下插件包含其中

• FormalitiesPlugin，它将分析提交；使用 CodeSniffer 和 FluidTYPO3 规则集验证 .php 文件的编码风格，并验证提交消息是否符合 TYPO3 标准关于前缀、大小写等。
• SiteDeployPlugin，顾名思义，部署仓库（对于 Fluid 驱动的 TYPO3 扩展，每个三个主要分支都部署到单独的站点，对于 master，部署到 fluidtypo3.org 本身）。

此外，该包还利用了

• gizzle-typo3-plugins 集中的插件集，我们利用它来在创建新 git 标签时自动上传到 TYPO3 扩展仓库。

这些插件共同构成了一个近乎实时的反馈系统，用于拉取请求（如果违反了 CGL，则会在每一行上进行注释，并说明违规的性质），并在 GitHub 上显示在拉取请求的 HEAD 提交上的状态指示器；以及一个自动发布系统，它像 Packagist 一样使用标签来检测新版本——但然后将发布到 TER。

姐妹实现

fluidtypo3-gizzle 的 Gizzle 实现有一个姐妹项目 fluidtypo3-development，旨在帮助在本地开发遵循 Fluid 驱动的 TYPO3 编码风格和规则的 TYPO3 扩展仓库。 fluidtypo3-development 包含一系列命令行实用工具，用于验证或操作仓库中的代码；例如，在 composer.json 和 ext_emconf.php 文件中一致地更新版本号，并手动上传新版本到 TER（这是 fluidtypo3-gizzle 自动化的操作）。它还会安装 git 命令的钩子，用于验证提交消息并在允许提交文件之前运行编码风格验证和单元测试。实际上，fluidtypo3-gizzle 利用 fluidtypo3-development 来实现一些功能以及官方仓库中使用的持续集成。

所以，当 fluidtypo3-gizzle 可以验证通过 GitHub 发生的事情时，fluidtypo3-development 可以在它到达 GitHub 之前进行验证。

结合使用两者应确保在审查拉取请求时人类参与的最低限度，以及为贡献者带来的最低限度的挫败感，因为使用 fluidtypo3-development，如果他们即将提交错误代码，他们会提前得到警告——即使他们使用 GitHub 的网络界面创建成为拉取请求的提交（但遗憾的是，直到它实际上成为拉取请求）。

DIY 指令

以下指令教您如何 Fork、安装和必要时修改 fluidtypo3-gizzle 以为您自己的仓库执行完全相同的事情。

安装文件和 HTTPD vhost

首先，请将仓库分叉以便您可以提交和推送您需要的任何更改，并在您自己的仓库中保留它们。然后，将您的分叉仓库克隆到您的Web服务器。

git clone https://github.com/YOURNAME/fluidtypo3-gizzle.git

然后切换到这个目录并运行Composer的安装。

cd fluidtypo3-gizzle
composer install --no-dev

如果您打算开发，我们建议移除--no-dev，以便安装phpunit和其他实用工具。如果没有使用--no-dev安装，此包将添加一个新命令，您只需调用一次，即可启用上述本地开发助手。

./vendor/bin/make

只需调用此命令一次即可 - 之后，它将自动在您每次提交之前调用，触发代码风格验证和单元测试。

最后，创建一个虚拟主机，指向项目内的web文件夹（找到您选择的HTTPD的正确说明）。可选地，您还可以设置Apache的DirectoryIndex或相应HTTPD的选项，以将github-webhook.php文件作为默认文件提供服务，这可以让您缩短用于GitHub web hooks的URL。

准备凭证

Gizzle至少需要一个所谓的secret文件，该文件包含您在GitHub中安装web hook URL时使用的秘密。您现在可以选择此秘密并在创建每个web hook时记住它。在项目根目录中创建该文件。

echo "mysecretphrase" > .secret

在GitHub上添加的所有web hooks中，都有一个专用的输入字段用于您的secret - 在您创建的所有web hooks（当然，这些web hooks由本主机接收）中输入您在此文件中放置的相同的secret。

不要将这些文件提交到您的仓库！相反，将它们添加到.gitignore中。

根据您预期要使用的插件，您可能还需要以下一个或两个：

GitHub个人访问令牌

个人访问令牌可以通过GitHub的账户设置生成，一旦生成，就允许像使用您的账户一样使用Gizzle等应用程序。个人访问令牌对于fluidtypo3-gizzle能够使用FormalitiesPlugin是必需的，因为它可以在提交中评论文件；并且它是更新拉取请求状态所必需的。

在创建您的个人访问令牌时，您决定它应该拥有哪些权限。与fluidtypo3-gizzle一起使用的最低要求是“公共仓库”和“评论”权限；如果您计划创建自己的Gizzle插件，您还需要使用任何其他权限。

如果您决定使用个人访问令牌，一旦创建并赋予它权限，请将其添加到项目根目录。

echo "1234567890abcdef1234567890abcdef" > .token

像保护您的GitHub登录名和密码一样保护您的个人访问令牌。 不要将这些文件提交到您的仓库！

TYPO3凭证

为了在创建新的git标签时启用自动上传仓库到TYPO3扩展仓库，fluidtypo3-gizzle需要一个包含明文用户名和密码的.typo3credentials文件。

echo "username:password" > .typo3credentials

保护您的凭证。确保只有您信任的人才能访问它！ 不要将这些文件提交到您的仓库！

在仓库中安装web hooks

一旦您准备好了凭证，Gizzle将能够验证来自GitHub的请求，并确保您不会收到来自其他来源的请求。

您应该首先将钩子添加到您对 fluidtypo3-gizzle 的分支中。您在这里添加的Web钩子应该运行 SelfUpdate.yml 设置文件，它基本上执行以下操作：1）从远程跟踪分支拉取更改，2）在项目本身中运行 composer install。这允许您将更改推送到您的分支，并立即部署它们。要添加此Web钩子，编辑仓库设置，然后在“Web服务和钩子”类别中选择创建新的Web钩子。在URL字段中，输入您的虚拟主机公共URL并引用设置文件

http://mydomain.com/github-webhook.php?settings=settings/SelfUpdate.yml

...并选择只发送“推送事件”。

您可以测试钩子以确认至少您的 secret 文件正在工作，但测试请求不会触发任何操作。

然后，在每个您希望使用我们或您自己的规则集自动验证编码风格的仓库中，添加另一个Web钩子，这次引用 PullRequest.yml 设置文件

http://mydomain.com/github-webhook.php?settings=settings/PullRequest.yml

但确保此钩子只接收“拉取请求”事件！一旦添加，此Web钩子将监听新的拉取请求和对现有拉取请求的更改，当这些发生时，将捕获被修改的文件和提交，并根据配置的规则进行验证。

fluitypo3-gizzle 提供的最终清单是 ExtensionRelease.yml 设置文件。引用此文件允许您捕获仅标记新版本的的事件

http://mydomain.com/github-webhook.php?settings=settings/ExtensionRelease.yml

并且对于此钩子，请确保它只接收“推送事件”。这意味着监听器在创建任何类型的提交（不仅仅是标签）时都会收到事件，但插件会过滤这些事件，但只识别以特殊前缀 heads/tags/ 开头的“refs”。

最后一点：您可以在每个Web钩子中分发多个设置清单

http://mydomain.com/github-webhook.php?settings[]=settings/Manifest1.yml&settings[]=settings/Manifest2.yml

请注意，settings 参数被转换为数组；可以添加任意数量的清单（只要生成的URL长度仍然有效）。但是：在以这种方式组合设置清单时要小心 - 确保所有涉及的插件实际上都匹配事件类型，否则您很快会发现添加了大量的事件，许多冗余事件，结果导致向您的Web钩子监听器发送许多不必要的HTTP请求。

设置清单和插件引用

“settings”目录中的每个 .yml 清单文件都包含一个或多个要执行的插件的配置，以及执行的参数。要了解更多关于如何创建此类清单的信息，请参阅 官方Gizzle配置参考。

每个插件支持的参数在插件所属的仓库中有文档说明；除了针对Fluid驱动的TYPO3扩展而量身定制的 SiteDeploy 和 Formalities 插件之外，这些插件只支持在设置文件中已定义的参数，没有更多，也没有更少。

涉及的插件和库位于以下仓库中

• https://github.com/NamelessCoder/gizzle-git-plugins，它用于通过清单触发标准的git命令。
• https://github.com/NamelessCoder/gizzle-typo3-plugins，它用于扩展发布逻辑。
• https://github.com/NamelessCoder/typo3-repository-client，它承载实际的扩展上传逻辑 - 并有您可用于相同目的的CLI命令。
• https://github.com/FluidTYPO3/fluidtypo3-gizzle，这是本项目及其分支的上游。