keep-a-changelog
keep-a-changelog copied to clipboard
olivierlacan
Unreleased is not clear
Hi,
The [Unreleased] section is not clear to me.
Keep an Unreleased section at the top to track upcoming changes.
To me, "Unreleased" means that the changes do exist, but are not released yet. They may be already present in a develop branch, for example.
People can see what changes they might expect in upcoming releases
So, does it concern planned or only already made changes?
Because of this section, I was considering adding to one of my Changelogs a [Planned] section, to reflect the difference. I've then been thinking that a changelog is a log of changes, and planned changes cannot be logged. Or maybe they can. Because the Changelog can help people prepare for incoming changes.
What do you all think of this question?
I don't know many open source project for which the latest code in master is a "release", therefore what is in master but not in the latest release is unreleased, or not properly released yet.
Does that clarify things for you?
Any project that follows Vincent Driessen's git branching model has the latest release in master. I don't know such project, but this model has some success.
It does clarify thing. So, what about planned changes? Maybe they should simply not be listed in the Changelog but rather in a Todo file? Still, planned changes are changes, not released and not written.
If we follow the rule that says that "Changelogs are for humans, not machines.", anyone may feel free to add any section they consider appropriate, right? Even if it's not in this convention ...
Planned changes do not belong in a changelog, IMO. Ideally, the changelog is injected with lines describing a change as it is merged into the development HEAD, whatever branch that may be.
However, every use case is different than the one before, and there may be situations where [PLANNED] makes sense in a changelog.
I think;
-
[PLANNED]belongs to a file such as todo -
[Unreleased]should not be in the change-log of a master branch. Only bec. the development should be done in a different branch than master (such as develop). (I believe the code in master branch should be the latest stable release, like Vincent Driessen.)
@Arcesilas planned changes should be in the README in a Roadmap section, maybe with links to issues for discussions. See https://www.makeareadme.com/ for recommendation.
A changelog only lists changes actually made.
[Unreleased] is a fairly widespread practice, but the name itself matters less than the practice of staging release information in the changelog prior to release. So I'm going to close this issue.