How should code changes be documented?

[MadcapJake]

CHANGELOG, CHANGES, .md, .rst, .pod, no extension—there are tons of ways to do it, what should be the Perl 6 way? How was it done in the past (Perl 5)? What are some things that need to be considered for maximum exposure, easy parsing for tools/frontends, and greatest accessibility? Add a full plan or just some tidbits that you think are important! Please use the GH reaction system for upvotes/agreement.

Note: this is regarding modules/software made with Perl 6.

[coke]

Define "code changes"? Do you mean for the compiler releases? (and by extension, the star releases?) Those have (for years now) been documented in docs/Changelog, and summarized for each release in docs/announce/*

[MadcapJake]

Woops! I wasn't very clear on that, I mean for modules/software made with Perl 6. I added a note for clarity on that.

[zoffixznet]

I find the P5's format suitable for all things. You save it in Changes file that follows this format: https://metacpan.org/changes/distribution/Mojo-PDF (note the use of sections in 1.002001 release).

However, what I find with P6 is that lacking any proper release mechanism—as is the case right now—I often forget to update the Changes file or tag a release, rendering the file useless. So I no longer use it for any new dists and remove it from my old dists when I make an update.

[MadcapJake]

In learning more about that format @zoffixznet mentioned, I came across an article detailing the spec and other changelog specs out there. Seems reasonable to me! If others find this format agreeable, I think—as a community—we should converge on this and make it a standard. Better now than later when changelogs have already been written. Also, perhaps we should allow more markdown formatting (allow #'s before version lines, allow links for git diffs, and maybe more?). This way, if you include an .md extension, github (also bitbucket and gitlab) will render them.