vz-changelog-generator-beta v1.0.5
Adobe Changelog Generator
Adobe Changelog Generator is the core package that is uses to generate changelog file.
- Usage
- Commands
- Config example
- Config options
- Template example
- Template declaration
- Extensibility and customization
Custom template
Custom template directive
Custom template repeat Custom release parser Custom writer Custom loader Custom filters Custom group
Installation
$ aio plugins:install -g @adobe/aio-cli-plugin-changelog
$ # OR
$ aio discover -i
$ aio changelog --help...
$ aio config set <GITHUB_TOKEN>
Commands
aio changelog
Changelog generation tool
USAGE
$ aio changelog
OPTIONS
-c, --config-path=config-path Local config path
-n, --namespace=namespace [default: ] Namespace, example: organization/repository:branch
-t, --path-type=absolute|relative [default: absolute] Local config path type
EXAMPLE
$ aio changelog
Config example
{
"<organization>/<repository>:<branch>" {
"releaseLine": <from>..<to>@<version>:<filter>
"combine": {
"<organization>/<repository>:<branch>": {
"releaseLine": <from>..<to>@<version>:<filter>
},
"<organization>/<repository>:<branch>": {
"releaseLine": <from>..<to>@<version>:<filter>
}
},
"loader": {
"name": <loader-name>,
"config": {
"exclude": {
"<filter>": <filter-config>
},
"groupBy": {
"name": <group-name>,
"config": {
<configuration>
}
}
}
}
"output": {
"strategy": "<strategy-type>",
"template": "<template-name>",
"filename": "<file-name>",
"projectPath": "<project-path>"
}
}
}
Config options
<organization>/<repository>:<branch>
- combination of organization, repository and branch is named namespace. Config can contain multiple namespaces. Tool will asynchronously generate changelog for each namespace.<organization>
- required<repository>
- required<branch>
- optional
combine
- provide a list of related namespaces. In case if you project consist of multiple repositories and you want to create changelog that contains data from all repositories you should use this option.- combine - optional
releaseLine
- define from-to brackets to collect content.<from>
- Starting point.
Optional
Default: current.
Can be one of the next type:tag
- Github tag. Example: 1.0.0hash
- Github commit hash. Example: fd7ebb1d0cd224e0957c035faafdffd9bd2b2b87date
- Date in ISO8601 format. Example: YYYY-MM-DDspecial-words
- application supports the list of predefined special-words:now
- Current date and timecurrent
- Start date of ongoing version not released yet.start
- Start date of first existing release.
<to>
- Ending point.
Optional
Default: now
Can be one of the next type:tag
- Github tag. Example: 1.0.0hash
- Github commit hash. Example: fd7ebb1d0cd224e0957c035faafdffd9bd2b2b87date
- Date in ISO8601 format. Example: YYYY-MM-DDspecial-words
- application supports the list of predefined special-words:now
- Current date and timecurrent
- Start date of ongoing version not released yet.start
- Start date of first existing release.
<version>
- the version of ongoing release.
Optional
Default: patch. Can be one of the next type:patch
- Increment patch version of last release.minor
- Increment minor version of last release.major
- Increment major version of last release.version
- Custom version. Example: 1.0.1-custom.
<filter>
- Filter RegExp. Optional. Use it for exclude some releases. Example: ^1.1
loader
- responsible to load Pull Request or Issue data from Github. Required.name
- loader name.- Available options:
- pullrequest
- Available options:
config
- loader config.exclude
- excludes some data based on specific criteria. Optional.<filter>
- name of the filter.- Available options:
- labels
- Available options:
<filter-config>
- Specific filter configuration.
groupBy
- group loaded data based on specific criteria. Optional.name
- group name- Available options:
- labels
- Available options:
config
- configuration specific to group type
output
- configuration of result file.strategy
- responsible for output file. Will it be merged to an existing file or creating new one.- Available options:
merge
create
- Available options:
format
- format of output file.- Default:
md
- Available options:
md
- Default:
template
- required. Name of template.- Available templates:
- PullRequest
- Available templates:
filename
- required. Name of output file.projectPath
- required. Path to the project folder.
Template example
<!--repeat_namespaces|scope_content-->
{{namespace|namespace_format:short|capitalize}}
=============
<!--repeat_releases-->
## {{tag}} ({{created_at|date_format:dd-MM-yy}}) {{repository}} or {{organization}} or {{branch}}
<!--repeat_contributionTypes-->
### {{contribution_type}}
<!--repeat_items-->
* [{{organization}}/{{repository}}#{{number}}](https://github.com/{{organization}}/{{repository}}/pull/{{number}})
-- {{title}} by [@{{author}}](https://github.com/{{author}})
<!--repeat_items_end-->
<!--repeat_contributionTypes_end-->
<!--repeat_releases_end-->
<!--repeat_namespaces_end-->
Template declaration
Template repeats
Repeats created to iterate list of entities.
There are multiple type of repeats are available now:
<!--repeat_namespaces--> <!--repeat_namespaces_end-->
- Iterate namespaces.
For more details about namespaces see config options(#config options). * Allowed:: Everywhere<!--repeat_releases--> <!--repeat_releases_end-->
- Iterate release versions.- Allowed:: in scope of
repeat_namespaces
- Allowed:: in scope of
<!--repeat_contributionTypes--> <!--repeat_contributionTypes_end-->
- Iterate list of contribution types (Use it only if you use data grouping)- Allowed:: in scope of
repeat_releases
- Allowed:: in scope of
<!--repeat_items--> <!--repeat_items_end-->
- Iterate list of items (Pull Requests, Issues, etc)- Allowed:: in scope of
repeat_releases
orrepeat_contributionTypes
- Allowed:: in scope of
Template tags
Application provide the list of tags that are allowed to use in any template. The tags will be replaced to real data in the scope of changelog generation. The tags can mixed in any way to build custom template that will cover project needs.
List of the tags:
{{namespace}}
- combination of Github organization, repository and branch- Format:
<organization>/<repository>:<branch>
- Allowed: in scope of
repeat_namespaces
- Modification: format can be changed by
namespace_format
directive
- Format:
{{organization}}
- Github organization name- Format:
<organization>
- Allowed: in scope of
repeat_namespaces
- Format:
{{repository}}
- Github repository name- Format:
<repository>
- Allowed: in scope of
repeat_namespaces
- Format:
{{branch}}
- Github branch name- Format:
<repository>
- Allowed: in scope of
repeat_namespaces
- Format:
{{tag}}
- release version- Format:
<tag>
- Allowed: in scope of
repeat_releases
- Format:
{{created_at}}
- release version created_at- Format:
<yyyy-MM-dd>
- Allowed: in scope of
repeat_releases
- Modification: format can be changed by
date_format
directive
- Format:
{{contribution_type}}
- item (PR/Issue) contribution type- Format:
<contribution_type>
- Allowed: in scope of
repeat_contributionTypes
- Format:
{{number}}
- item (PR/Issue) number- Format:
<number>
- Allowed: in scope of
repeat_items
- Format:
{{title}}
- item (PR/Issue) title- Format:
<text>
- Allowed: in scope of
repeat_items
- Format:
{{author}}
- item (PR/Issue) author- Format:
<author>
Allowed: in scope of
repeat_items
- Format:
Template directives
Directives used for modifying/transforming value.
Multiple directives:
Application allows use multiple directives on single data item. Directives will be applied from left to right.
Example: {{namespace|namespace_format:short|capitalize}}
Firstly will be applied namespace_format
directive and capitalize
next
Directives list:
namespace_format
- change view format of namespaces.- Format:
{{<namespace>|namespace_format:<option>}}
- Options:
- Short
- Long
- Format:
date_format
- change view format of date. Allowed to any date values.- Format:
{{<created_at>|date_format:<option>}}
- Options: Any datetime format
- Format:
capitalize
- Transform first letter in passed string. Allowed to any string values.- Format:
{{<namespace>|capitalize}}
- Format:
Template repeat directives
Template repeat directives works like template directives but on repeats level.
Repeat directives list:
scope_content
- system directive. The directive add invisible scope tags to output file.
This invisible scope tags used for output file parsing that is required in case when strategy config option(#config options) is merge.
Extensibility and customization
Custom template
Application supports custom templates, for that you need:
- Create new
<custom_name>.md
file insrc/templates
folder. - Declare custom template uses
template repeats
,template tags
,template directives
. - Set your custom template name to
output.template
config option.
Custom template directive
- Create new
<custom_name>.js
file insrc/template-directives
folder. - Create new class implementing corresponding interface. (
src/api/template-directive-interface
)
Note: The name of the class will be used as directive name. - Use custom directive in template uses custom directive class name as the directive name.
Custom template repeat
- Create new
<custom_name>.js
file insrc/template-handlers
folder. - Create new class implementing corresponding interface. (
src/api/template-handler-interface
)
Note: The name of the class will be used as repeat name. - Use custom repeat in template uses custom repeat class name as the directive name.
Custom release parser
Application supports multiple type of declaration of version ranges, but you can simply create new one!
- Create new
<custom_name>.js
file insrc/release-parsers
folder. - Create new class implementing corresponding interface. (
src/api/release-parsers-interface
)
Note: The name of the file will be used as parser name. - The release parser will be automatically registered in application and available to use in configuration
Custom writer
Application supports multiple type of declaration of version ranges, but you can simply create new one!
- Create new
<custom_name>.js
file insrc/writers
folder. - Create new class implementing corresponding interface. (
src/api/changelog-writer-interface
)
Note: The name of the file will be used as writer name. - Set your custom writer name to
output.format
config option.
Custom loader
Custom loaders allow you to collect specific set of data from Github.
- Create new
<custom_name>.js
file insrc/loades
folder. - Create new class implementing corresponding interface. (
src/api/loader-interface
)
Note: The name of the file will be used as loader name. - Set your custom loader name and configuration to
loader.name
andloader.config
config options.
Custom loader configuration example:
"loader": {
"name: "<customFileName>"
}
Custom filters
Filters are responsible for filter data received from loader.
- Create new
<custom_name>.js
file insrc/filters
folder. - Create new class implementing corresponding interface. (
src/api/filter-interface
)
Note: The name of the file will be used as filter name. - Set your custom filter name and configuration to
loader.config.exclude
config option.
Custom group
Filters are responsible for filter data received from loader.
- Create new
<custom_name>.js
file insrc/groups
folder. Note: The name of the file will be used as group name. - Set your custom group name and configuration to
loader.config.groupBy.name
config option.
Example:
"groupBy": {
"name: "<customFileName>"
}
Maintainers and Contributors
This project is maintained by Open Contribution Office.