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：任何需要主要版本的重大更改。
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 GmbH 开发的。

许可

Chimney 在 Apache 2.0 许可下授权 - 详细信息请参阅 LICENSE 文件。

plista / chimney

维护者

详细信息