[Downloader] Cog update changelogs

[Ray-MRQ]

Cog update should work like v2, show whats being updated and if you would like something specfic to be updated.

[tekulvw]

This is a much larger discussion than just adding in the update information.

V2 worked by looking at the git commit history. Personally, I don't think that's a good way to handle changelogs and feel like we should have a dedicated change log somewhere in the repo that Downloader can use to display update information. However, the format and name of this hypothetical changelog file still needs to be discussed.

[Ray-MRQ]

surely just showing what cogs has been updated is enough no? or does that require something more

[palmtree5]

To your second point:
"if you would like something specific to be updated" [p]cog update has a cog_name parameter for exactly that.

[Redjumpman]

What if cog creators made their own change logs located in the root of their repository. This might force some people to start writing a more concise list of changes. In the past, you could have a cog get updated, and the commit information be complete garbage, since someone just put "lol I made a mistake".

It's more work for the creator, but at least you could enforce a specific format so you don't have to clean up the data before you output it each time.

[mikeshardmind]

I'd prefer ^ myself. My commit messages are often more for myself, and I would have no issue creating a changelog and documentation.

[Tobotimus]

Initially I was thinking "changelogs don't really make sense without releases", since we're just pulling commits from a resository. However I've changed my mind about that - cog creators could simply create a "release" branch if they'd like to have it set up that way.

[Redjumpman]

Tobotimus said...

However I've changed my mind about that [change logs don't make sense without releases]

Are you saying you would want to pull git commits, but only from a release branch?

[aikaterna]

It hasn't really been codified anywhere yet but downloader in v3 is not going to spit out a ton of commit messages on a cog update like v2 does. I do like the changelog idea, and it could be enforceable as part of the cog QA guidelines in the future.

[Tobotimus]

It's up to the cog creator really, but currently, [p]cog update just pulls from whatever upstream branch is set. If the cog creator wanted to show a changelog every time something updated, they'd have to write in the changelog for every commit. My suggestion for a "release branch" is just something the cog creator could do if they wanted to do larger changelogs, but less frequently.

How the changelog would be formatted is another question - we'd have to somehow identify which parts of the changelog are actually relevant, likely with commit hashes. Never mind I'm an idiot, we could just use the diff pre- and post-merge on the changelog

[mikeshardmind]

I've already transitioned to using feature branches and merging into it on my v3 repo. We're far enough into V3 that I shouldbe be committing directly to it at this point. so I'm set for the above, but I feel like it could be neat to provide a actual formatted changelog (with a spec) in each cog's folder as an alternative. (and fall back to getting commit from git)

[Redjumpman]

With the release branch... if you update two different cogs and two different intervals... Say One day I update casino, and then 10 days later I update shop. Is it still possible to pull the change log for casino? Basically, how do you determine which commit to pull all the information from?

Either way, if we have a dedicated changelog file, or pull from commit history, I think having some type of prompt like

Cog update completed successfully.
Would you like to see the changes?

In the case of several cogs having a changelog / changes pulled from git, just pagify it so they can type more to see the next set of changes.

[mikeshardmind]

@Redjumpman Yes:

 git log -q --follow -- casino/

Would want more customization on that command, but you can specify which paths you care about in git log.

[Redjumpman]

FWIW I still think having a dedicated change log that the downloader looks for to display updates would be best. Commit history is typically garbage for many users. Having a dedicated file affords the opportunity for us to establish a standard. If someone deviates from it or makes a mistake, it's easy to fix or make compliant.

I hope other cog creators will add to this discussion, since I think this is a matter that affects that group the most.

[mikeshardmind]

I'd like a markdown or serialized embed format which the info file can point to for a changelog with a standardized format which would allow the downloader to easily parse what it hasn't seen in the changelog prior for this, but a fallback to parsing the file's commit history. (easier barrier to entry for newer devs, more functionality for those willing to put in the time)

[laggron42]

Maybe we could combine this with the release feature of github, which would include changelogs

[Tobotimus]

As of #2165, [p]cog update will now show which cogs were updated, and prompt of a reload for all of these cogs or none of them. Changelogs still not supported though.

[TurnrDev]

How about a CHANGELOG.md in each cog folder based on the Keep a Changelog format along with a version key in info.json and/or __version__ in the cogs __init__.py?

[TurnrDev]

Or alternatively, again in info.json. changelog would point to a dict of keys for releases, with free-flowing strings of any format (but markdown is recommended as it parses well in embeds)

{
  "author": ["TurnrDev"],
  "description": "Generic cog lol",
  "end_user_data_statement": "N/A",
  "min_bot_version": "3.4.0",
  "version": "1.4.0",
  "changelog": {
    "1.4.0": "## Added\n  - Added Changelog",
    "1.3.0": "## Added\n  - Added version"
  }
}