Parse references at end of changelog as separate part of a changelog.

[florenzen]

Description

The references to tags or compare links at the end of a changelog file are parsed into a separate member of the Changelog record. Before, lines like

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

ended up in the Changes list of the last ChangelogEntry. In certain situations, this lead to undesired modifications by PromoteUnreleased since these reference lines were reproduced in a release entry.

When saving and converting a Changelog to a string, these references are also included as the last lines of the changeling file.

[xperiandri]

Could you explain when this is used? I'm not familiar with this piece of functionality

[florenzen]

Could you explain when this is used? I'm not familiar with this piece of functionality

Hello @xperiandri,

the Changelog module is, e.g., used in the the MiniScaffold template to manipulate the CHANGELOG.md file during a release build.

When you have a change log like this:

# 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

### Changed
- Foo 2

## [0.1.0-pre.2] - 2023-10-19

### Added
- Foo 1

## [0.1.0-pre.1] - 2023-10-11

### Added
- Foo 0

[Unreleased]: https://github.com/florenzen/Foo/compare/v0.1.0-pre.2...HEAD
[0.1.0-pre.2]: https://github.com/florenzen/Foo/releases/tag/v0.1.0-pre.2
[0.1.0-pre.1]: https://github.com/florenzen/Foo/releases/tag/v0.1.0-pre.1

and then run the following code, that is a stripped down excerpt from the build code of MiniScaffold to move the unreleased and the pre-release entries to a new release section

#r "nuget: Fake.Core.ReleaseNotes"

open System
open System.IO
open Fake.Core

let chglog = Changelog.parse (File.ReadAllLines("CHANGELOG.md"))

let newVersion = SemVer.parse ("0.1.0")

let versionTuple version =
    (version.Major, version.Minor, version.Patch)

let prereleaseEntries =
    chglog.Entries
    |> List.filter (fun entry ->
        entry.SemVer.PreRelease.IsSome
        && versionTuple entry.SemVer = versionTuple newVersion)

let prereleaseChanges =
    prereleaseEntries |> List.collect (fun entry -> entry.Changes) |> List.distinct

let assemblyVersion, nugetVersion = Changelog.parseVersions newVersion.AsString

let description, unreleasedChanges =
    match chglog.Unreleased with
    | None -> None, []
    | Some u -> u.Description, u.Changes

let newEntry =
    Changelog.ChangelogEntry.New(
        assemblyVersion.Value,
        nugetVersion.Value,
        Some DateTime.Today,
        description,
        unreleasedChanges @ prereleaseChanges,
        false
    )

let newChangelog =
    Changelog.Changelog.New(chglog.Header, chglog.Description, None, newEntry :: chglog.Entries)

File.WriteAllText("CHANGELOG1.md", newChangelog.ToString())

you get:

# 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).

## [0.1.0] - 2024-07-26

### Changed
- Foo 2

### Added
- Foo 1

- Foo 0
[Unreleased]: https://github.com/florenzen/Foo/compare/v0.1.0-pre.2...HEAD
[0.1.0-pre.2]: https://github.com/florenzen/Foo/releases/tag/v0.1.0-pre.2
[0.1.0-pre.1]: https://github.com/florenzen/Foo/releases/tag/v0.1.0-pre.1

## [0.1.0-pre.2] - 2023-10-19

### Added
- Foo 1

## [0.1.0-pre.1] - 2023-10-11

### Added
- Foo 0

[Unreleased]: https://github.com/florenzen/Foo/compare/v0.1.0-pre.2...HEAD
[0.1.0-pre.2]: https://github.com/florenzen/Foo/releases/tag/v0.1.0-pre.2
[0.1.0-pre.1]: https://github.com/florenzen/Foo/releases/tag/v0.1.0-pre.1

All the links from the bottom are part of the Foo 0 added entry since by the parsing mechanics of the Changelog modules, they are considered to be part of that entry.

By moving them to a separate component of the changeling record type, this does not happen anymore.

[xperiandri]

@TheAngryByrd any remarks?

[TheAngryByrd]

Overall love it :)

Probably needs some extra tests to make sure we don't mess up files or regress.

[xperiandri]

Can you give any particular advice?

[TheAngryByrd]

Can you give any particular advice?

@florenzen has an example here that would be useful as a test case.

[xperiandri]

Should it be added as a test?

[florenzen]

I'll add it as a test as soon as I find a minute for it. Thanks for your feedback so far.

[florenzen]

I added several test cases. Glad to receive your feedback on these, @TheAngryByrd.

[florenzen]

Any chance of getting this one merged and closed or should I make some more changes to it?

[xperiandri]

@TheAngryByrd could you have a look?

[xperiandri]

@florenzen could you submit release notes file update describing this fix?

[florenzen]

@xperiandri, where should I submit the release notes line?

I think, it would read like this:

* ENHANCEMENT: Parse references at end of changelog as separate component, thanks @florenzen - https://github.com/fsprojects/FAKE/pull/2779

Thanks for accepting the contribution.

[xperiandri]

I’ll push manually, thanks