README

提供关于包变更的信息，基于发布版本附带的变化日志文件，并介绍了从变化日志源生成文档文件（以多种格式和创建自定义模板选项）的工具/命令。

它包含几个命令，有助于开发者在CI中设置自动发布包的逻辑。

有关最近更改的更多信息 在这里（这也作为changelog.json的MD格式示例）。

请注意，只有当您已配置输出生成器时，才会生成变化日志输出。

配置：概述

可以在项目的composer.json中以键值对的形式定义环境变量

{
  "extra": {
    "changelog": {
      "source": "changelog.json"
    }
  }
}

配置：变化日志文件格式

该模块期望在声明新的变化日志记录时使用某些约定，这些约定基于根据语义版本规则对更改进行分组（并提供一些额外的详细信息）：破坏性更改、功能、修复（额外：概述、维护）。

额外键主要用于将一些数据输出到发布说明中关于新发布的一般主题，或者允许为开发者添加一些额外的详细信息。

{
    "1.0.0": {
        "overview": "Some general overarching description about this release; Can be declared as a list",
        "breaking": [
            "code: Something changed in the sourcecode",
            "data: Something changed about the data format",
            "schema: Something changed about the database",
            "config: config path or flag renamed",
            "logic: default/expected execution path of the application/module changed"
        ],
        "feature": [
            "short description about feature1",
            "short description about feature2"
        ],
        "fix": [
            "short description about fix1",
            "short description about fix2"
        ],
        "maintenance": [
            "short description about changing something about the architecture, etc"
        ],
        "branch": "useful for multiple major-release branches and using 'version' and 'info' commands"
    }
}

请注意，所有组都是可选的 - 即使缺少这些组，插件的其他功能和文档生成器也不会出错。

开发者不仅限于这些组，任何其他组最终都会在文档生成器输出中使用。这个规则的例外是“概述”组，它与额外的处理逻辑相关联，在代码中不被视为“更改”组。

配置：添加发布

应按升序添加发布，最新版本始终是最高记录（如所有可能遇到的变化日志一样）。

{
    "2.0.0": {},
    "1.2.1": {},
    "1.1.1": {},
    "1.1.0": {},
    "1.0.0": {}
}

配置：即将发布的版本

为了确保插件的所有命令都按预期工作，应在变化日志中将即将发布的版本标记为“DEV.1.2.3”，这将导致最新版本报告命令跳过它。如果值留为空白，也可以达到同样的效果。

这在多个人正在处理即将发布的版本，并且你想推迟该版本发布的情况下很有用（如果你有一些围绕变化日志版本命令的CI逻辑）。只要存在'DEV.'，开发者就可以将他们的更改组合在同一个变化日志记录下。

{
    "DEV.1.2.3": {
        "feature": [
            "some upcoming, yet to be released feature"
        ]
    }
}

插件使用composer约束验证器，因此任何不符合版本约束的项都将被跳过。

功能：变化日志中的注释

在团队内部有关于如何维护和填充变化日志以及应使用哪些组的具体指南的情况下很有用。

{
    "_readme": "Make sure to follow the conventions: http://some.url/changelog-conventions.html",
    "_guide": "Some tips on how the changelog for this specific package is maintained and updated",
    "1.2.3": {
       "feature": [
           "some feature"
       ]
    }
}

请注意，可以在变化日志的任何级别添加注释，并且变化日志读取器/生成器总会忽略它们。

功能：仓库链接

The changelog generator is capable of adding repository links to the chage log for each version by presenting both source link for certain version as well as diff/comparison for the code when compared to previous release.

This activates in two situations:

• When composer.json of the package has support/source defined (part of the standard Composer package config schema)
• When repository with proper remote destination has been configured (with a well-formed URL)

The variables that become available through this in templates: {{link}}, {{diff}}.

This feature is enabled by default, but can be enabled by defining the following under changelog configuration within the composer.json of the package

{
  "extra": {
    "changelog": {
      "feature": {
        "links": false
      }
    }
  }
}

The links can be disabled for a single generator run as well by overriding the URL configuration with a specific command argument

composer changelog:generate --url=false

Feature: release dates

The module will try to resolve the release date of certain version from the package repository when it's available. The available options to be used in output templates are: {{date}}, {{time}}.

This feature is enabled by default, but can be enabled by defining the following under changelog configuration within the composer.json of the package

{
  "extra": {
    "changelog": {
      "feature": {
        "dates": false
      }
    }
  }
}

Output: generators

This example is based on making Sphinx documentation generation available.

{
  "extra": {
    "changelog": {
      "source": "changelog.json",
      "output": {
        "sphinx": "docs/changelog.rst"
      }
    }
  }
}

Available types: html, md, rst, slack, sphinx, txt, yml

Output: templates

The plugin ships with built-in templates for each of the generators, which can be configured by defining generators in an extended format.

{
  "extra": {
    "changelog": {
      "source": "changelog.json",
      "output": {
        "sphinx": {
          "path": "docs/changelog.rst",
          "template": "my/template/path/template123.mustache"
        }
      }
    }
  }
}

Note that the template file path is relative to the package root that owns the changelog configuration.

Templates use Mustache syntax with some extra helpers (for which the built-in templates serve as documentation/examples).

When relying on the generators to produce the changelog documentation, make sure to add the output path to VCS ignore file as well to avoid producing unintended modifications. The file will be overwritten if it exists in the repository before the documentation generation is called.

The generator does support Mustache partials as well in which case the template paths should be given as a dictionary where the entry point template has been defined under the key "root".

{

  "template": {
    "root": "my/template/path/custom_root.mustache",
    "mypartial": "my/template/path/release.mustache"
  }
}

In this example, the choice to define a template for the key "mypartial" derives directly from referring to such a Mustache partial in the template that's defined in "root".

The reserved names for partials in this plugin are:

• root - main entry-point for the renderer
• release - used by default to output certain changelog group/version and its details, AND by changelog:info

The base files for each template can be found from HERE.

Commands

# Generate documentation pages from changelog configuration
composer changelog:generate 

# Generate changelog with version-bound (src) and (diff) links for each release
# Will override the default setting configured for the module
changelog:generate --url ssh://hg@bitbucket.org/some/repository

# Report latest valid version from changelog (skip over the ones that are yet to be released)
composer changelog:version

# Report latest valid version for release/1.X
composer changelog:version --branch release/1.X

# Report latest release record from changelog (might be same as last valid)
composer changelog:version --tip

# Report upcoming release version from changelog (returns blank if there is no upcoming version)
composer changelog:version --upcoming

# Report current latest version without PATCH version
composer changelog:version --segments 2

# Report latest release details (in requested format)
composer changelog:info

# Validate changelog files content
composer changelog:validate

# Setup basic usage of the changelogs for a module
composer changelog:bootstrap

Upgrading The Module

When upgrading the module, one might encounter odd crashes about classes not being found or class constructor arguments being wrong.

This usually means that the class structure or constructor footprint in some of the classes have changed after the upgrade, which means that the plugin might be running with some classes from the old version and some classes from the new version.

It is safe to ignore these errors when running the composer update command again does not produce any side-effects.

Development

The modules ships with a dedicated development branch devbox which contains configuration for spinning up a dedicated development environment that can be used together with VSCode's Remote Containers.

Note that there is no strict requirement to use such a setup, but it's what was used to author the plugin and if you want to be sure that you have everything up and running without hick-ups, you can just as well take the shortcut.

System requirements

1. 已安装Docker。
2. 已安装VSCode并安装了'Remote - Containers'扩展。
3. 已安装Mutagen（用于选择同步）。

设置

1. git checkout devbox .devcontainer Dockerfile docker-compose.yml mutagen.yml
2. git reset .devcontainer Dockerfile docker-compose.yml mutagen.yml
3. [使用已安装远程容器扩展的VSCode打开项目]
4. [在打开的提示中，使用'在容器中重新打开'选项]
5. (仅在Windows上) mutagen project start
6. 使用'终端 > 新建终端'在IDE内打开终端。
7. [从终端中可以安装包、触发调试器等]

注意，此设置附带预先启动的xDebugger，您只需在VSCode中使用运行菜单并开始通过终端监听和触发命令即可。