Release notes / Changelog commands?

[RamblingCookieMonster]

Some discussion: https://github.com/RamblingCookieMonster/PSDeploy/issues/37

Given that we already abstract out some PowerShell specific stuff, and have commands to work with module metadata (not markdown though...), this might be a good fit for commands like Get/Set-ReleaseNotes and Get/Set-Changelog (where release notes covers 'stuff consumers care about', and changelog is more descriptive / dev oriented)

[michaeltlombardi]

If we do some work around the Changelog, I suggest we pick/stick to a standard. I have some mixed feels about auto-generating changelog lines - I'm not sure how effectively you could write a changelog message automatically. They need to be more in-depth than commit summaries and typically target different things.

[RamblingCookieMonster]

Ahh good point! Yeah, so I think workflow wise the only sensible thing would be to parse an existing standard format for release notes, inject into psd1.

[midacts]

I would be interested in this functionality as well. It has been something I haven't delved too much into yet, but I know when I do it would be nice to have a command or some automation to take care of it.

I'm not sure what the best way to accomplish this though.

[michaeltlombardi]

So, a couple months on and I'm less sure you can write good, effective changelog entries automatically. I think an Add-ChangelogEntry function might be pretty useful, but the actual writing of the changelog belongs to humans.... and at that point, you're probably better off using an editor and doing it manually.

My reasoning for this is that commits and changelogs are fundamentally for different audiences. Commits are for maintainers first, power users second. Changelogs are for upgrading users first, everyone else second.

The things maintainers / upgrading users need to know about a changeset are radically different in tone, detail, and emphasis.

Edit: I'm in favor of maintaining only two canonical sources of truth/info about the changesets between releases: commit messages and the changelog. In my opinion, you could automatically copy the changelog into the release notes section of a module manifest, for example, but they fulfill the same role.

[midacts]

I agree. I've thought about this since this has been brought up and I haven't been able to come up with a good solution.

What you have stated is correct.

[gaelcolas]

quick brain dump

Sounds like it should be a release pre-check: if you're about to release something, then you should have a changelog (.txt/.md/whatever) and that should call Add-ChangelogEntry during build time to update the artefact's changelog.

[michaeltlombardi]

@gaelcolas, I'm not philosophically opposed to using an Add-ChangelogEntry function, but what would the content be? How does it no what subsection it should be under?

Or are you alluding to it updating the bundled doc to match the project doc? I'm not sure I follow.... but I also haven't had coffee today. :)

[lipkau]

I like to have the PrivateData.PSData.ReleaseNotes of my manifest the same as the last entry in the changelog.

If we stick to to the standard suggested by michaeltlombardi, I would imagine using Add-ChangelogEntry somewhat like

Add-ChangelogEntry -Type "Changed" -Description "Update and improvement of Polish translation from m-aciek."

and have it appended to the [Unreleased] header. And having a Publish-Changelog-like cmdlet to pass the [Unreleased] header a [x.x] - yyyy-mm-dd header

[fourpastmidnight]

I agree with both @michaeltlombardi and @lipkau. Changelogs entries are fundamentally different from git commit messages.

I used to include the entire changelog in the ReleaseNotes section of the PSD1 file. But that quickly became unwieldy, and honestly, of little value. If you want to see the entire history, well, I bundle the Changelog with my modules, and you can always view it at the GitHub repo. What's most important is seeing the most recent entry in the Release Notes file.

Lastly, I'd just like to mention that I had issues with the PowerShell packaging mechanism, where by default, tags are created for each function in your module. With a decently-sized module, it's really easy to overflow the tags field in the NuGet database backend, which is a NVARCHAR(MWX) SQL field, so only 4000 code points are allowed. So that is quickly filled up with your own defined tags and the auto-generated ones. So I've had to resort to forcing PowerShell to NOT auto-create function tags. Bummer.