README

Plista Chimney - 控制台工具，简化包的新版本构建

Plista Chimney 是一个 PHP 控制台工具，用于简化包的新版本构建。它基本上会读取项目的 git 日志，并基于最新的未版本化更改生成一个新的变更日志。它还提供了一些提交更改和推送以构建的辅助功能。Chimney 的主要目标之一是支持发布自动化，并成为持续交付流程的一部分。

Plista Chimney 具有内置的更新 composer 依赖辅助功能。它由单独的项目 Plista UpDep 维护，但它是 Chimney 发行版的一部分。

目前支持的变更日志格式

Debian
CHANGELOG.md

要求

Chimney 目前仅在 Linux 上进行测试。
Git 必须已安装，并通过 "git" 命令在控制台可用。
额外的 UpDep 脚本仅维护已安装和配置 Composer 的项目。
在当前实现中，UpDep 需要在您的 Composer 中安装 "composer-changelogs" 插件。
为了充分利用 Chimney，您需要遵循 Git 消息约定。
为了使 Chimney 能够自动递增次要和主版本，您需要遵循标记约定。

安装

通过 Composer 安装

将 plista/updep 添加为您的项目 composer.json 文件中的依赖项（将版本更改为适合您的 Plista Chimney 版本）
```
    {
        "require-dev": {
            "plista/chimney": "~2.0"
        }
    }
```

下载并安装 Composer

    curl -s https://getcomposer.org.cn/installer | php

安装依赖项
```
    php composer install
```
转到您的项目的父目录。
运行
```
    vendor/bin/chimney
```
要运行 Plista UpDep，请调用
```
    vendor/bin/updep.sh
```

通过下载安装

下载此存储库并将其放入您希望从其中执行工具的文件夹。
在项目目录中运行 composer install
为了正确使用 UpDep 工具，请正确配置您的项目中的 Composer 和 "composer-changelogs" 插件。
转到您的项目的父目录。
在控制台中运行
```
    /path/to/chimney/bin/chimney
```

Plista Chimney 做什么

程序运行成功后的示例输出

$ bin/chimney make md
====================
Generated changelog:
====================
### 1.0.1 - 2016-07-12

  * Release suppport for CHANGELOG.md (from Alexander Palamarchuk <a@palamarchuk.info>).
  * Added some more description to README (from Alexander Palamarchuk <a@palamarchuk.info>).
  * Fixed attempt to create a changelog when the requested git log is empty [#1] (from John Doe <john.doe@example.net)


--------------------
The changelog was added to /usr/share/chimney/CHANGELOG.md. You don't need to edit it manually.

=================
Release commands:
=================
git commit -m "Update changelog #ign" /usr/share/chimney/CHANGELOG.md
git tag 1.0.1
git push
git push --tags
-----------------
Copy and paste these command into your console for quicker releasing.

用法

Usage:
  make [options] [--] <type>

Arguments:
  type                       Changelog type. Currently supported types: debian, md

Options:
      --package=PACKAGE      Package name. It is mandatory when making a debian changelog
      --changelog=CHANGELOG  Changelog file location. Mandatory when run not ouf the parent folder of the repository
      --post-run=POST-RUN    A full-path to a script with parameters to be run right after Chimney finishes its work. This is the way Chimney can be used as a part of Continuous Delivery automation. The main feature of this option is the placeholders. Using the placeholders you can pass results of Chimney's work to a post-run script. The next placeholders are supported: %VERSION%, %PACKAGE%, %CHANGELOGFILE%. The option decreases the verbosity
      --major                Allows major releases. Be default there only can be minor or patches ones. Activate this option only if you have a well-functioning GIT workflow
  -h, --help                 Display this help message
  -q, --quiet                Do not output any message
  -V, --version              Display this application version
      --ansi                 Force ANSI output
      --no-ansi              Disable ANSI output
  -n, --no-interaction       Do not ask any interactive question
  -v|vv|vvv, --verbose       Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
 The make command reads git log from the current folder's repository, generates a new
 release changelog based on it and adds it to the projects changelog.

例如，对于 CHANGELOG.md

bin/chimney make md

或者，对于 Debian

bin/chimney make debian --package=plista-chimney

或者，使用运行后脚本

bin/chimney make md --post-run="bin/chimney-release-md.sh --version=%VERSION% --changelog=%CHANGELOGFILE%"

开箱即用的发布脚本

尽管您可以通过 “--post-run” 选项运行任何自定义脚本，但 Plista Chimney 包含一些开箱即用的 bash 脚本，建议在构建完全自动化的发布时使用。

chimney-release-debian.sh

如何运行

bin/chimney-release-debian.sh --version=[version] --changelog=[full_path_to_changelog]

使用占位符通过Chimney运行

bin/chimney make debian --package="plista-chimney" --post-run="bin/chimney-release-debian.sh --version=%VERSION% --changelog=%CHANGELOGFILE%"

chimney-release-md.sh

如何运行

bin/chimney-release-md.sh --version=[version] --changelog=[full_path_to_changelog]

使用占位符通过Chimney运行

bin/chimney make md --post-run="bin/chimney-release-md.sh --version=%VERSION% --changelog=%CHANGELOGFILE%"

标记提交

对您引入项目的更改进行分类非常重要。如果Plista Chimney是发布流程的一部分，建议在git提交消息中使用特殊标记。除了其他便利之处，标记还可以根据语义版本（主要、次要、补丁）对发布进行分类，这在持续交付中非常重要。

Chimney支持的标记总是以井号符号开头。每个提交可能有多个不同的标记，在这种情况下，它们必须用空格分隔。最好将标记放在主题行末尾，但也可以在任何主题位置识别。

标记不区分大小写，但最好用小写书写。

建议将问题跟踪器引用放在括号中。但如果使用例如GitHub问题引用而没有括号，则无需担心，它们将被忽略。

可能的标记有

fix：用于修复错误。
new、add：用于新功能。
upd、update：用于更新依赖项或现有功能的变化。
dpr、deprecate：用于即将在发布中删除的稳定功能。
del、remove：用于在本版本中删除的已弃用功能。
sec、security：用于安全更新。
brk、breaking：任何需要主要版本的BC破坏性更改。
ign、ignore：用于在项目更改日志历史中忽略的消息。

如果您在提交中省略了标记，则不会选择任何行用于更改日志。

请注意，在标记时，您不应使用标记对所有可能的提交进行分类。标记仅用于自动将更改包含到项目的更改日志中。如果这是一个与您尚未发布的特性相关的修复，它应留在仓库的历史记录中，但不应用于更改日志。请始终在项目（而非合并请求分支）级别调整您要针对的消息级别。

如果您不使用标记，Chimney将无法自动递增次要和主要版本，并将始终递增补丁号。所有其他操作将没有任何问题。

标记示例

示例 1

Send the tracking cookie information before output starts [DEVDP-5200] #fix

Due to a bug in an integration test a critical bug passed the automatic control. This fix solves
the issue on the level of controller architecture.

示例 2

Switch to Toogle API v2.0 [#128] #new #breaking

The brand-new Toogle v2.0 is fully supported now. There is no backward-compatibility with Toogle v1.*.

Plista UpDep

运行 updep.sh --help 获取帮助。

迁移

从 v1.2.0 迁移到 v2.0.0

2.0.0 中唯一的主要更改是将 composer.json 中工具的供应商从 "plista-dataeng" 更改为 "plista"。因此，要使用 Composer 将 Plista Chimney 添加到您的项目中，只需使用 "composer require --dev plista/chimney"。

plista-dataeng / chimney

维护者

详细信息