README

这个名字不恰当的工具可能有一天会取代旧的 构建工具。

DEV_MODE

通过在 .env 文件中添加 DEV_MODE=1 来启用 DEV_MODE。这将阻止向 GitHub 推送。

如果之前在该目录上使用过 DEV_MODE，请不要在该目录上执行发布，因为步骤将出错。相反，删除运行过 DEV_MODE 的目录，并禁用 DEV_MODE 重新开始整个发布过程。

.env 文件需要位于 /cow 目录中，而不是 releases 目录中。例如，如果您的 cow 目录位于 ~/Releases/cow，则创建 .env 文件为 ~/Releases/cow/.env

安装

需要 Docker。

您不需要了解 Docker 的工作原理，但您需要安装并运行它 安装并运行。

出于生产目的，应通过包含在 ./docker/bin 目录中的基于 Docker 的脚本运行 Cow，而不是直接在您的机器上运行。这确保了使用所有第三方库和工具的统一版本，并且是唯一支持的安装选项。

已在 Linux 和 macOS 上测试，但也应在 Windows 上工作（使用 Cygwin 或 WSL）。

安装后，要运行 Cow，请启动 ./docker/bin/run 脚本。这将自动下载 Cow Docker 映像的最新发布版本，并在您的终端中透明地启动它。

发布版本时，请使用 ./docker/bin/release 脚本。这与 run 类似，但运行 SSH-Agent 并执行一些额外的检查。

在编写本说明（2020-02-03）时，您需要 GITHUB_TOKEN（作用域：repo 和 read:packages）。

然后您需要通过运行以下命令来配置 Cow 分发的 composer

./docker/bin/composer config -g github-oauth.github.com TOKEN

有关这些和其他可用脚本的更多详细信息，请参阅 docker/README.md。

将 Cow 添加到您的 $PATH（可选）

如果您想全局运行 Cow，您可以在包含在您的 $PATH 中的文件夹中创建指向 docker/bin/release 的符号链接。

以下是一个示例（您可以将任何现有文件夹从您的 $PATH 中重用）

mkdir -p ~/.local/bin;  # ensure existing ~/.local/bin
ln -s ./docker/bin/release ~/.local/bin/cow  # create symlink to the launcher and name it cow
echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc  # add ~/.local/bin to the $PATH

在重新加载您的会话后（例如，重新打开终端），您可以从系统的任何位置启动 cow

cd ./my-project;
cow moo

本地

要无 Docker 运行 Cow，请参考 Dockerfile 中的系统要求。

额外设置

• 在发布到 GitHub 时，请确保您有运行中的 ssh-agent 并且已加载 SSH 密钥（运行 ssh-add）。

命令

Cow 是由顶级命令分组的不同工具（步骤）的集合。思考不仅限于可用的命令，还有每个命令包含的每个步骤。

通常建议您使用 -vvv 详细标志运行，以便在发布过程中查看错误。

例如，我会运行以下命令来发布 3.1.14-rc1。

cow release 3.1.14-rc1 -vvv

一旦我确认一切正常，并且我 100% 确信此代码准备就绪。

cow release:publish 3.1.14-rc1 -vvv

发布

cow release <version> <recipe> 将执行发布任务的第一个部分。

• <version> 是必需的，并且必须是发布的确切标签名称。
• <recipe> 允许您发布除 'silverstripe/installer' 之外的食谱。

此命令有以下选项：

• -vvv 确保所有底层命令都会被回显。
• --directory <directory> 指定创建或查找此项目的文件夹。如果您未指定此选项，它将在当前目录的 ./release-<version> 路径中安装。
• --repository <repository> 允许指定自定义的 composer 包 URL。例如 http://packages.cwp.govt.nz 注意：如果您在设置期间指定了仓库，它将被用于后续命令，除非删除了 .cow.repository 文件。
• --branching <type> 将指定一个分支策略。这允许以下选项：
  • auto - 默认选项，除非进行非稳定标签（例如 rc1），否则将分支到小版本（例如 1.1）。
  • major - 如果不在更具体的小版本上，则将所有仓库分支到主版本（例如 1）。
  • minor - 将所有仓库分支到小版本 semver 分支（例如 1.1）。
  • none - 从当前分支发布，不进行分支。
• --skip-tests 跳过测试。
• --skip-i18n 跳过更新本地化。

release 实际上具有几个子命令，可以独立运行。以下为这些子命令：

• release:create 创建项目文件夹。
• release:plan 启动发布规划工具以预览发布依赖版本。
• release:branch 如果需要，将所有模块分支。
• release:translate 更新翻译并将更改提交到源代码控制。
• release:test 运行单元测试。
• release:changelog 仅生成变更日志并将更改提交到源代码控制。

发布版本

cow release 将仅构建发布。一旦完成上述所有步骤，有必要将完成的发布推向开源社区。需要另一个主要命令 cow release:publish 来执行最终步骤。此命令的格式如下：

cow release:publish <version>

此命令有以下选项：

• -vvv 确保所有底层命令都会被回显。
• --directory <directory> 指定要查找之前步骤中创建的项目文件夹。与上面一样，如果省略，将进行猜测。您可以在 ./release-<version> 目录中运行此命令并省略此选项。

发布过程，就像初始的 cow release 命令一样，实际上将包含多个子命令，每个子命令都可以单独运行。

• release:tag 向每个模块添加注释标签并进行推送。

在推送步骤之后，release:publish 将自动等待此版本在 packagist.org 上可用，然后再继续。

创建变更日志

cow release:changelog 将创建一个变更日志，该日志被分类到各种更改类型集合中，例如增强、错误修复、API 变更和安全修复。

变更日志命令接受以下参数和选项：

• version 您要发布项目的版本。
• recipe 您要发布的食谱。
• --include-other-changes 如果提供，未分类的提交也将包含在“其他更改”部分中。请注意，匹配 ChangelogItem::isIgnored() 的提交仍然会被排除，例如合并提交。
• --changelog--use-legacy-format 如果提供，将回退到旧的变更日志格式（在 2020 年 10 月之前使用）。
• --changelog--audit-mode 将变更日志格式切换到审计模式，这将打开 include-upgrade-only 标志并使用审计模板生成变更日志日志（包括每个更改）。

小贴士： 此命令的一部分涉及计划生成和/或确认，并且您可以通过提供 --skip-fetch-tags 选项来防止 Cow 重新从 origin 获取所有标签，如果您已经这样做并且只想进行快速更改。

变更日志模板

您可以通过在.cow.json中的changelog-template配置中指定一个文件，用作生成新变更日志的模板。这个模板可以使用Twig语法来注入相关信息。

• {{ version }}将注入正在生成变更日志的版本（例如1.2.3）。
• {{ logs }}将注入带有前后定界的提交日志，这样可以在不破坏内容其他更改的情况下稍后更新它们。

GitHub API速率限制

运行cow github:ratelimit以检查您的当前GitHub API速率限制状态。

注意：所有GitHub API命令在使用之前都需要设置GITHUB_ACCESS_TOKEN环境变量。它可以在.env文件中（参见开发模式）。

模式

此项目的根目录中有cow模式文件。

您可以通过运行cow schema:validate来检查您项目或模块中的.cow.json配置文件，以确保它符合Cow模式。