search

phly / keep-a-changelog

Tools for manipulating CHANGELOG.md files in Keep A Changelog format, including tagging and releasing.
https://phly.github.io/keep-a-changelog/
BSD 2-Clause "Simplified" License
182 stars 23 forks source link

How to deal with [Unreleased] and preview/beta/alpha versions? #68

Closed paales closed 4 years ago

paales commented 4 years ago

First of all: Thanks for this great tool, I wouldn't be creating issues if I didn't think this has much value and potential :) I'm currently running into some issues that might be because I'm not fully understanding the library..

keepachangelog.com mentions that you can add [Unreleased]: https://keepachangelog.com/en/1.0.0/

I'm not sure how I can create a release based on this? In my case I want to do something like:

keep-a-changelog bump:to-version 1.0.0-preview.0

I would expect it to rename the [Unreleased] section to [1.0.0-preview.0] - TDB and create a new [Unreleased] section. The reason is that I can't know if its a major/minor/patch while creating my changes. If a change becomes breaking, it will become a major of course..

When I manually put [1.0.0-preview.0] - TDB in the CHANGELOG.md file and I know try to run: keep-a-changelog ready -vvv I get:

Setting release date of most recent changelog to "2020-02-24"

In NoMatchingChangelogDiscoveredException.php line 18:

  [Phly\KeepAChangelog\Exception\NoMatchingChangelogDiscoveredException]
  Unable to find un-dated changelog entry in Sites/project-waardijk.nl/vendor/reach-digital/docker-devbox/CHANGELOG.md

Exception trace:
  at .composer/vendor/phly/keep-a-changelog/src/Exception/NoMatchingChangelogDiscoveredException.php:18
 Phly\KeepAChangelog\Exception\NoMatchingChangelogDiscoveredException::for() at .composer/vendor/phly/keep-a-changelog/src/SetDate.php:25
 Phly\KeepAChangelog\SetDate->__invoke() at .composer/vendor/phly/keep-a-changelog/src/ReadyCommand.php:53
 Phly\KeepAChangelog\ReadyCommand->execute() at .composer/vendor/symfony/console/Command/Command.php:255
 Symfony\Component\Console\Command\Command->run() at .composer/vendor/symfony/console/Application.php:982
 Symfony\Component\Console\Application->doRunCommand() at .composer/vendor/symfony/console/Application.php:255
 Symfony\Component\Console\Application->doRun() at .composer/vendor/symfony/console/Application.php:148
 Symfony\Component\Console\Application->run() at .composer/vendor/phly/keep-a-changelog/bin/keep-a-changelog:61

ready [-d|--date DATE]

Also, creating preview releases requires me to know the current version in advance, would be nice if I'd be able to create a beta/alpha/preview/blabla release without creating a new version

weierophinney commented 4 years ago

Sorry I've taken so long to respond to this!

Can you describe the workflow you want to use, please? As an example:

When I type:

$ keep-a-changelog unreleased:create

The tool should create an "Unreleased" level-2 header before the most recent release entry.

Subsequently, when I call the various entry:* commands, these should write to the Unreleased section if present and no specific version is provided via the -r or --release-version flag.

At a later date, I should be able to promote the "Unreleased" section to a specific version:

$ keep-a-changelog unreleased:promote <version>

When this is executed, the "Unreleased" section will be renamed after the provided <version>, with the current date as the release date. An optional --with-date or -d option, when provided, will set a specific date:

$ keep-a-changelog unreleased:promote <version> -d 2020-07-14

If the above works for you, I can get started on that; otherwise, write-up the workflow you'd like to use. (You'll note I didn't specify "ready" as the command for prepping an unreleased version; this is because I do not think the tool should guess whether the next version is a bugfix, feature, or BC-breaking release.)

BTW, the bump:to-version command exists to allow creating a specific version number that falls outside the standard bugfix/feature/major release cycle, such as a dev, alpha, beta, or RC release. These are still considered releases, but just fall outside the more common workflow. As such, I would not like to override this to rename an "Unreleased" section.

PowerKiKi commented 4 years ago

I'm not OP, but the workflow you described would work for me. I would be able to use this for PhpSpreadsheet where we don't plan in advance the version number.