Provide a ChangeLog with only a limited range versions

[llaville]

Hello,

It will be helpful if merge command has an option to limit range of versions when building the final CHANGELOG.md

Some projects has adopted the way to split CHANGELOG into many files organized by major or minor version series.

• PHPUnit
• PHP CompatInfoDB

I'm preparing the next major release 5.0.0 of CompatInfoDB, and I've noticed that I should remove by hand all 4.x versions if I want to have a clean CHANGELOG.md file.

See commit llaville/php-compatinfo-db@675da34

[miniscruff]

Hmm, I think that sounds reasonable for some use cases. My issue comes with the inevitable manual file changes required to move from one version to another as Changie's purpose is to not have any manual changes ( it does allow for some when it comes to adding custom things but normal operations shouldn't ).

The problems I see are:

1. When releasing a new major version you would have to first move the old version to a new file
2. Potentially modify the header to mention what version is contained in the changelog
3. Then whenever you merge you must also specify any semver range you want to export to the one changelog file

Generally speaking, any argument you need for "every" batch or merge should be in the config. Therefore, I feel the best approach ( as of the short time thinking about it ) would be to expand the https://changie.dev/config/#config-changelogpath to optionally be an array of "ChangelogOutputs". Something like:

changelogOutputs:
  - file: CHANGELOG-10.md
    range: >=10
    header: header.tpl.md // this is maybe a future idea, but a different header file per output might also be good
  - file: ./.changes/CHANGELOG-archive.md
    range: <10
    header: header-archive.tpl.md

The current changelog path would basically just be a shorthand for:

changelogOutputs:
  - file: <changelogPath>
    header: <headerPath>
    range: >0 // all versions

Now releasing a new major version would then require config changes in this case, maybe it could be templated with a {{.Major}} for this use case but it would really depend on your use case so I am not sure we can mitigate that. It would however, not require arguments for every batch or merge which is important.

I would probably say I need more examples to justify the extra work and to see how they might be splitting it. Some projects might just have an arbitrary split where it got too big or something like that.

[llaville]

First, I would like to thanks you for your answer, that allow me to think again and re-discover basic feature of changie v1.10

I've tested v1.10.1 (thanks too for this new version), but v1.10.0 already allows to apply use case I've with major versions.
I'll try to explain.

• I want to keep change fragments history in GIT repo => make different sub-directory into .changes, one for each major version or major/minor

.changes/
├── 4.x
│   ├── 4.0.0.md
│   ├── 4.10.0.md
│   ├── 4.1.0.md
│   ├── 4.2.0.md
│   ├── 4.3.0.md
│   ├── 4.4.0.md
│   ├── 4.5.0.md
│   ├── 4.6.0.md
│   ├── 4.6.1.md
│   ├── 4.7.0.md
│   ├── 4.7.1.md
│   ├── 4.8.0.md
│   └── 4.9.0.md
└── 5.x
    ├── 5.0.0.md
    ├── header.tpl.md
    └── unreleased

• .changes/5.x/header.tpl.md may contains specific contents for versions 5.x

<!-- markdownlint-disable MD013 MD024 -->
# Changes CompatInfoDB 5.x

All notable changes of the CompatInfoDB 5 release series will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
and is generated by [Changie](https://github.com/miniscruff/changie).

• main config file identify current major version with specific sub-directory

changesDir: .changes/5.x
unreleasedDir: unreleased
headerPath: header.tpl.md
changelogPath: CHANGELOG.md
versionExt: md
versionFormat: '## {{.Version}} - {{.Time.Format "2006-01-02"}}'
kindFormat: '### {{.Kind}}'
changeFormat: '- {{.Body}}'
kinds:
    - label: Added
    - label: Changed
    - label: Deprecated
    - label: Removed
    - label: Fixed
    - label: Security
newlines:
    afterHeaderTemplate: 0
    beforeKind: 1
    afterKind: 1
    beforeVersion: 1
    endOfVersion: 1
envPrefix: CHANGIE_

• When I want to create a new change fragment, I continue to did it as previous with batch command

• When I want to create a new CHANGELOG for major versions 5.x, I continue to did it as previous with merge command

• Last case I don't know, if we can make a full CHANGELOG with all changes fragments 4.x and 5.x

PS: my use cas is available at https://github.com/llaville/php-compatinfo-db/tree/master/.changes/