Skip to content

Commit

Permalink
add release notes for the new props and data structures
Browse files Browse the repository at this point in the history
  • Loading branch information
@baronfel
baronfel committed Jan 23, 2022
1 parent 0efed34 commit 7bb768a
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 64 deletions.
24 changes: 12 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ It might be helpful to see how this library can help you. Imagine you have a pr
and a CHANGELOG.md file like this:

```md
# Changelog
# Changelog

## 1.0.0 - 2022-01-14

Expand Down Expand Up @@ -71,18 +71,25 @@ If your changelog has multiple versions, the latest one will be used.

There's really only one property that matters for these targets, and that's `ChangelogFile`. This needs to point to the Changelog file you want to read, but it defaults to `CHANGELOG.md` in the root of a given project in case you want to adhere to defaults.

| Property | Type | Default Value | Description |
| - | - | - | - |
| ChangelogFile | string | CHANGELOG.md | Points to the changelog file to parse. Note that the default value is set to the _project_ root by default, so a repository-wide changelog would require this property be set to a different value, for example in a Directory.Build.props file |
| GenerateAssemblyBuildDateAttribute | boolean | true | If set, an assembly metadata attribute named "BuildDate" will be generated with the date (YYYY-MM-DD) of the parsed release. |
| GenerateVersionForUnreleasedChanges | boolean | true | If set, the assembly/package version and release notes will be set from Unreleased changes, if any are present. |

## API

When the task runs, it writes several output items and properties:

|Name|Type|Description|
|----|----|-----------|
| UnreleasedChangelog | UnreleasedChangelogData option | If present, there was an 'Unreleased' section in the Changelog. This structure will contain the sections present. |
| UnreleasedChangelog | ReleaseChangelogData option | If present, there was an 'Unreleased' section in the Changelog. This structure will contain the sections present, as well as an auto-incremented version number for this release. |
| UnreleasedReleaseNotes | string option | If present, contains the concatenated list of all Changelog sections for the Unreleased section of the Changelog. This is a convenience property so that you don't have to String.Join all the lines in the `ReleaseChangelogData` structure yourself! |
| CurrentReleaseChangelog | ReleaseChangelogData option | If present, there was at least one released logged in the Changelog. This structure will contain the details of each one. |
| AllReleasedChangelogs | ReleaseChangelogData list | Contains the ordered list of all released in the ChangelogFile, descending. |
| LatestReleaseNotes | string option | If present, contains the concatenated list of all Changelog sections for the latest release. This is a convenience property so that you don't have to String.Join all the lines in the `ReleaseChangelogData` yourself! |
| LatestReleaseNotes | string option | If present, contains the concatenated list of all Changelog sections for the latest release. This is a convenience property so that you don't have to String.Join all the lines in the `ReleaseChangelogData` structure yourself! |

### ChangelogData
### ReleaseChangelogData

This TaskItem has metadata for each of the known sections of a Changelog:

Expand All @@ -95,13 +102,6 @@ This TaskItem has metadata for each of the known sections of a Changelog:

In each case, the value of the metadata is the newline-concatenated list of all of the Changelog Entries for that section.

### UnreleasedChangelogData

This structure is a `ChangelogData` with an `Identity` of `"Unreleased"`.

### ReleaseChangelogData

This structure is the same as `ChangelogData`, but it contains two more items of metadata:

In addition,
* the `Identity` of the `TaskItem` is the Semantic Version of the release
* the `Date` of the `TaskItem` is the `YYYY-MM-DD`-formatted date of the release
117 changes: 65 additions & 52 deletions test/Ionide.KeepAChangelog.Test/Program.fs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,14 @@ let singleRelease =
"""

let singleReleaseExpected =
(SemanticVersion.Parse "1.0.0", DateTime(2017, 06, 20), Some {
ChangelogData.Default with
Added = ["- A"]
Changed = ["- B"]
Removed = ["- C"]
})
let singleReleaseExpected =
(SemanticVersion.Parse "1.0.0",
DateTime(2017, 6, 20),
Some
{ ChangelogData.Default with
Added = [ "- A" ]
Changed = [ "- B" ]
Removed = [ "- C" ] })

let keepAChangelog =
"""# Changelog
Expand Down Expand Up @@ -53,14 +54,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
"""

let keepAChangelogExpected: Changelogs =
{
Unreleased = None
Releases = [
singleReleaseExpected
SemanticVersion.Parse("0.3.0"), DateTime(2015, 12, 03), Some { ChangelogData.Default with Added = ["- A";"- B";"- C"]}
]
}
let keepAChangelogExpected: Changelogs =
{ Unreleased = None
Releases =
[ singleReleaseExpected
SemanticVersion.Parse("0.3.0"),
DateTime(2015, 12, 3),
Some { ChangelogData.Default with Added = [ "- A"; "- B"; "- C" ] } ] }

let header =
"""# Changelog
Expand All @@ -81,18 +81,22 @@ let headerAndUnreleased = header + emptyUnreleased
let headerAndUnreleasedAndRelease = header + emptyUnreleased + singleRelease
let headerAndUnreleasedAndReleaseExpected = None, singleReleaseExpected

let sample1Release = """## [0.3.1] - 8.1.2022
let sample1Release =
"""## [0.3.1] - 8.1.2022
### Added
- Add XmlDocs to the generated package
"""

let sample1ReleaseExpected =
SemanticVersion.Parse "0.3.1", DateTime(2022, 1, 8), Some { ChangelogData.Default with Added = ["- Add XmlDocs to the generated package"] }
let sample1ReleaseExpected =
SemanticVersion.Parse "0.3.1",
DateTime(2022, 1, 8),
Some { ChangelogData.Default with Added = [ "- Add XmlDocs to the generated package" ] }

let sample = """# Changelog
let sample =
"""# 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/),
Expand Down Expand Up @@ -124,15 +128,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
* Initial implementation
"""

let sampleExpected: Changelogs = {
Unreleased = None
Releases = [
SemanticVersion.Parse "0.3.1", DateTime(2022, 1, 8), Some { ChangelogData.Default with Added = ["* Add XmlDocs to the generated package"] }
SemanticVersion.Parse "0.3.0", DateTime(2021, 11, 23), Some { ChangelogData.Default with Added = ["* Expose client `CodeAction` caps as CodeActionClientCapabilities. (by @razzmatazz)"; "* Map CodeAction.IsPreferred & CodeAction.Disabled props. (by @razzmatazz)"] }
SemanticVersion.Parse "0.2.0", DateTime(2021, 11, 17), Some { ChangelogData.Default with Added = ["* Add support for `codeAction/resolve` (by @razzmatazz)"] }
SemanticVersion.Parse "0.1.1", DateTime(2021, 11, 15), Some { ChangelogData.Default with Added = ["* Initial implementation"] }
]
}
let sampleExpected: Changelogs =
{ Unreleased = None
Releases =
[ SemanticVersion.Parse "0.3.1",
DateTime(2022, 1, 8),
Some { ChangelogData.Default with Added = [ "* Add XmlDocs to the generated package" ] }
SemanticVersion.Parse "0.3.0",
DateTime(2021, 11, 23),
Some
{ ChangelogData.Default with
Added =
[ "* Expose client `CodeAction` caps as CodeActionClientCapabilities. (by @razzmatazz)"
"* Map CodeAction.IsPreferred & CodeAction.Disabled props. (by @razzmatazz)" ] }
SemanticVersion.Parse "0.2.0",
DateTime(2021, 11, 17),
Some { ChangelogData.Default with Added = [ "* Add support for `codeAction/resolve` (by @razzmatazz)" ] }
SemanticVersion.Parse "0.1.1",
DateTime(2021, 11, 15),
Some { ChangelogData.Default with Added = [ "* Initial implementation" ] } ] }

open FParsec
open FParsec.Primitives
Expand All @@ -141,32 +155,31 @@ let runSuccess label p text expected =
test $"parsing {label}" {

match FParsec.CharParsers.run p text with
| FParsec.CharParsers.Success (r, _, _) ->
Expect.equal r expected "Should have produced expected value"
| FParsec.CharParsers.Failure (m, _, _) ->
failwithf "%A" m
| FParsec.CharParsers.Success (r, _, _) -> Expect.equal r expected "Should have produced expected value"
| FParsec.CharParsers.Failure (m, _, _) -> failwithf "%A" m
}

[<Tests>]
let tests = testList "parsing examples" [
runSuccess "line entry" Parser.pEntry "- A" "- A"
runSuccess "header" Parser.pHeader header ()
runSuccess "unreleased" Parser.pUnreleased emptyUnreleased None
runSuccess "header and unreleased" (Parser.pHeader >>. Parser.pUnreleased) headerAndUnreleased None
runSuccess "release" Parser.pRelease singleRelease singleReleaseExpected
runSuccess "sample 1 release" Parser.pRelease sample1Release sample1ReleaseExpected
runSuccess
"header and unreleased and released"
(Parser.pHeader >>. Parser.pUnreleased
.>>. Parser.pRelease)
headerAndUnreleasedAndRelease
headerAndUnreleasedAndReleaseExpected

runSuccess "keepachangelog" Parser.pChangeLogs keepAChangelog keepAChangelogExpected

runSuccess "lsp changelog" Parser.pChangeLogs sample sampleExpected
]
let tests =
testList
"parsing examples"
[ runSuccess "line entry" Parser.pEntry "- A" "- A"
runSuccess "header" Parser.pHeader header ()
runSuccess "unreleased" Parser.pUnreleased emptyUnreleased None
runSuccess "header and unreleased" (Parser.pHeader >>. Parser.pUnreleased) headerAndUnreleased None
runSuccess "release" Parser.pRelease singleRelease singleReleaseExpected
runSuccess "sample 1 release" Parser.pRelease sample1Release sample1ReleaseExpected
runSuccess
"header and unreleased and released"
(Parser.pHeader >>. Parser.pUnreleased
.>>. Parser.pRelease)
headerAndUnreleasedAndRelease
headerAndUnreleasedAndReleaseExpected

runSuccess "keepachangelog" Parser.pChangeLogs keepAChangelog keepAChangelogExpected

runSuccess "lsp changelog" Parser.pChangeLogs sample sampleExpected ]

[<EntryPoint>]
let main argv =
runTestsWithCLIArgs Seq.empty argv tests
let main argv =
runTestsWithCLIArgs Seq.empty argv tests

0 comments on commit 7bb768a

Please sign in to comment.