Make PENDING.md less scary

[rigelrozanski]

Going to list off a bunch of ideas of how to make our pending file much nicer, and generally the process flow of using our pending file. I'm still very much in favour of switching to pending files which get compiled into the changelog on release - however that sounds more of post-launch idea.

In the meantime this thing is hard to read and much of the labelling is totally counter intuitive to me and generally a bit of headache to use.

Here are some of the idea's I'd improve to quell my pending anxieties around this file

• Rename it PENDING.md -> CHANGELOG_PENDING.md
  • it's really clear when we used to refer to the changelog, using the language pending become disconnected from the changelog altogether, I'd like to bring those two concepts back together, as in I find myself saying things in commit messages like update pending whereas it's a bit confusing and I'd rather see things like changelog update which would only really make sense if we had the renamed file proposed
• Remove links from pending
  • I think it would be dope to have the links final changelog file, we even already have a script to add that in quickly. However in the changelog_pending - which is mostly being opened in text editors, it just becomes really distracting to have all the links in there
• Make better use of new lines, some of entries get really long
• List the categories at the top of the pending file. (it's difficult to know what goes where on first glance as there is no overview)
• Revise the categories we are using - a lot of the separation is totally arbitrary for the time being and often I find it confusing as to where to put a change as they could go in multiple categories
  • I'd suggest to remove the Gaia category and just use SDK
  • with this Gaia CLI (gaiacli) should just be CLI
  • and Gaia REST API (gaiacli advanced rest-server) just REST

LASTLY maybe I'm totally crazy, but using stars (*) as bullet points makes me feel uneasy, I'm a much bigger fan of the dash bullet point (-) -> this is of course minor

[ValarDragon]

I Agree with Changelog_Pending, and only the release creator including links. (Including them was my bad, just wanted to show the script worked. In hindsight, there are better ways to do that lol)

I agree with the changing categories. I also think we should add the following categories:
Go API (or alternatively SDK API), and Security. (We should get in the habit of making a separate security updates section, which should be important for downstream users)

Not really sure I agree with * vs - personally, but since you have a preferrence, I'm fine with changing to -.

[alessio]

How about dropping PENDING.md altogether and coming up with a convention for machine-readable tags to be used in PR/commit messages?
Such tags could be parsed by a script at release time that will eventually generate a changelog.

[alexanderbez]

Agreed on all counts @rigelrozanski. re; * vs -, agree to use - as * are typically used for ordered lists. To add to that, the markdown should be valid overall. It was annoying to see tabs and spaces of 2 and 4 spaces used all over the place.

MR tags, I like the idea but it may be harder to enforce or easier to end up missing a few changes, no?

[alessio]

Well, many projects have commit messages guidelines. Certainly committers/mergers would need to comply.

[rigelrozanski]

@alessio RE: MR tags

This was one of proposed solutions previously with the team surrounding this issue, we decided that it would be less complicated, more explicit to simply introduce a folder we new files for each changelog entry which get added to the changelog during release. Of course, I also really like the commit message idea, wish I could remember the reasons we decided against it (also can't find the old issue... CC @ebuchman)

I think that by adding entries to the description field on commits (where there can be multiple lines) we would probably pretty easily parse the commits to create the changelog entries

Although really cool, all this is of course post-launch

[rigelrozanski]

Looks like somebody has had this idea already: https://github.com/saschagrunert/git-journal
Although briefly skimming their work, I think it may be better to quickly generate our own repo to do this in golang, and have it more suited to our needs

[alexanderbez]

What is the latest on this @rigelrozanski? Can we close this?

[rigelrozanski]

do not close - many issues still relevant and unaddressed - thanks for the ping

[alessio]

I wrote a small thing to maintain changelogs in YAML format:

• https://github.com/alessio/cledit

[alexanderbez]

Great. I do like @alessio's proposal. It prevents some margin of error.

[rigelrozanski]

@alessio this looks great - let's fix our changelog situation once and for all. I like the idea of populating changelog entries and then compiling them for a release through a tool like the one you've created - I think the biggest recommendation is adding pending changelog entries as unique files in a pending directory instead of a yaml file - this could save oodles of time ..... the amount of time I have to fix merge conflicts for pending log entries is outragous

the cool thing about using a utility to perform these edits is it would justify having pending changelog entries in a hidden folder (which could still be accessed by the changelog utility)

[alessio]

I mean, I have no preferences really. We could either use my tool (BTW, feel free to test it, break it, crack it, improve it, open PRs, migrate it under cosmos/ - whatever toasts your bread is fine for me) or adopt another solution. I'm up for anything really - the current state of things is horrible, horrible...