Keep unreleased changelog section when promote to new version

[vilinski]

Description

• Make the function Changelog.promoteUnreleased to keep the ### Unreleased section in the changelog according to https://keepachangelog.com/en/1.0.0/#effort
• Add CHANGELOG.md file format sample to module documentation. This is actually not related to the first change.

Explanation

There is nothing big, but still. For example if we have following changelog:

# Changelog

All notable changes to this project will be documented in this file.

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

## [Unreleased]

Next big release

### Fixed
- Nothing else than bugfixes. That was long overdue

## [0.2.0] - 2020-03-17
Second release

### Changed
- All features are changed, because we can

## [0.1.0] - 2020-03-17
First release

### Added
- This release already has lots of features

[0.1.0]: https://github.com/user/MyCoolNewLib.git/releases/tag/v0.1.0

Now we call in the build.fsx something like this:

changelog 
|> Changelog.promoteUnreleased "0.3.0"
|> Changelog.save "CHANGELOG.md"

After that only one line is changed - there is ## [0.3.0] - 2020-03-07 instead of ## [Unreleased].

• All unreleased changes are migrated to the 0.3.0 release section, which is correct.
• But the line ## [Unreleased] is deleted, which is not needed, because it must be added every time manually for future changes again.

This change just brings the section ## [Unreleased] back.
I don't see it as breaking change, because after that it is the manual change anyway, I guess.

TODO

Feel free to open the PR and ask for help

• New (API-)documentation for new features exist (Note: API-docs are enough, additional docs are in help/markdown)

• unit or integration test exists (or short reasoning why it doesn't make sense)

  Note: Consider using the CreateProcess API which can be tested more easily, see https://github.com/fsharp/FAKE/pull/2131/files#diff-4fb4a77e110fbbe8210205dfe022389b for an example (the changes in the DotNet.Testing.NUnit module)

• boy scout rule: "leave the code behind in a better state than you found it" (fix warnings, obsolete members or code-style in the places you worked in)

• (if new module) the module has been linked from the "Modules" menu, edit help/templates/template.cshtml, linking to the API-reference is fine.

• (if new module) the module is in the correct namespace

• (if new module) the module is added to Fake.sln (dotnet sln Fake.sln add src/app/Fake.*/Fake.*.fsproj)

• Fake 5 API guideline is honored

[matthid]

@vilinski Thanks! As I'm not too familiar with this module, would you like to explain a bit what this changes? Is this a breaking change? What is the impact?

[vilinski]

Added more description

[matthid]

Aha thanks a lot! That indeed sounds very useful, just to be absolutely sure: Do we have another API that will read the latest version and if there is one will it still read the same version as before?
Because some people (including FAKE itself) take the version from the release file, so as far as I understand your description this still has the potential to break those people because now they might get "unreleased" instead of the proper version in their release automation.
Do you think this might happen or do you think this is unlikely in such a way that we can do this change?

[vilinski]

Yes, there is also ReleaseNotes module in the same subproject. It is also used in the FAKE, and to my understanding also in most other projects. The module has own parser for RELEASE_NOTES.md files, and own NuGetVersion property.

Changelog module reads CHANGELOG.md files. You can get the version from Changelog.LatestSection.NuGetVersion, from the latest released section only.
Unreleased record representing the unreleased section has no version properties and because of this no impact to the version

[matthid]

Thanks again!