search

ionide / KeepAChangelog

Parser and MSBuild Targets for using Keep-A-Changelog-formatted Changelogs in your Build
MIT License
30 stars 4 forks source link

README feeback #2

Closed MangelMaxime closed 2 years ago

MangelMaxime commented 2 years ago

Hello really cool project.

It should help me avoid copying my release-nuget script in every one of my repository :)

My first time reading the README.md file, I had a hard time understand what this project was doing.

I knew it was supposed to set the version based on the changelog but I wasn't able to confirm it at first with the documentation.

I think, the reason is because the section about that is only the first paragraph and I was too attracted by the rest of the file. I also think that the word Versions and Package release notes are lost in the rest of the text.

This project implements a Changelog parser according to the spec at KeepAChangelog. It also provides MSBuild tasks and targets to automate the setting of Versions and Package Release Notes for your NuGet packages, so that the Changelogs are your source of truth.

Perhaps, it could help to put them in bold?

Another idea that would have help me is to have an example of the original XML and what it would output.

<?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <ChangelogFile>$(MSBuildThisFileDirectory)/CHANGELOG.md</ChangelogFile>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="Main.fs" />
  </ItemGroup>
</Project>

with the following changelogl:

## 1.0.0 - 2022-01-14

### Added

* Initial release

is equivalent to:

 <?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <ChangelogFile>$(MSBuildThisFileDirectory)/CHANGELOG.md</ChangelogFile>
    <Versions>1.0.0</Versions>
    <ReleaseNotes>
## 1.0.0 - 2022-01-14

### Added

* Initial release
    </ReleaseNotes>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="Main.fs" />
  </ItemGroup>
</Project>
baronfel commented 2 years ago

This is a great idea, I'll do some reworking of the readme to be more direct and example-fied today.

Thank you for the feedback!

baronfel commented 2 years ago

Updated the README, hope that is more clear.

MangelMaxime commented 2 years ago

Looks good to me.

Only remark is you say in the text that it set PackageVersion but it is not shown in the XML example. So perhaps, we can add it to be exhaustive.

I let you close this issue so you can see my message :). For me the problem is now resolved, thank you.