FAQ : What should we do about draft/milestone release?

[crakjie]

It's could be nice to have a part on draft in the FAQ.

Should the stable version contain all change of each drafts? Or should it just have the changes that was made since the last draft?
Should we keep draft in changelog when the stable version is released ?

[rdeago]

I thought I'll write my 2 cents, as this is an issue I'm trying to address in my own projects.

TL;DR: I think a changelog has to be consolidated and revised just before releasing a stable version, leaving no trace of drafts.

---

Drafts, prereleases, alpha / beta (/ gamma / ... / omega) test versions, or whatever it's trendy to call them these days, are all about making changes, possibly break things, and correct what's broken before coming to a stable version.

As long as one follows semantic versioning rules, version 3.3.8-pre1 of a project is not apt to break much of anything. To tell the truth, version 3.3.8-pre1 could as well not exist in the first place, depending upon the nature of the modifications involved.

On the other hand, version 4.0.0-pre1 could introduce some breaking changes that later get reverted, or modified in a yet-more-breaking way, in a subsequent prerelease, before the code is stabilized and v4.0.0 (a stable version, case in point) is released.

Personally, once a stable version is released, I don't see any value in leaving trace of the drafts in a changelog. Changelogs are for users, and users will hardly be interested in how a change came to be the way it is; otherwise they'd just read the source control log.

Say you're updating a dependency of a project of yours, from v3.3.4 to v4.0.6. You reach to the changelog to learn about how the changes made between those two versions affect your use case. Which of the following two changelog snippets would you find more useful, this...

## [4.0.0] - 2020-02-09
[...]

## [4.0.0-pre2] - 2020-02-02
### Changed
- Restored the `color` parameter in `DrawGizmo()`, making it optional - turns out AI gets the color wrong in some edge cases.
[...]

## [4.0.0-pre1] - 2020-01-31
### Changed
- Removed the `color` parameter from `DrawGizmo()` - now the gizmo's color is determined automatically by our shiny new AI algorithm.
[...]

...or this one?

## [4.0.0] - 2020-02-09
### Changed
- The `color` parameter in `DrawGizmo()` is now optional. If omitted, a color will be automatically chosen by our shiny new AI algorithm.
[...]

[oxr463]

Typo: FQA -> FAQ