Explicit CHANGELOG.md display

[calimarkus]

Currently the SPI has a prominent tab for release notes. I assume that's powered by GH releases, right?
Would you consider exposing CHANGELOG.md files (if existing) as a tab (or otherwise), similar to what CocoaPods does?

PS: I didn't have any official releases tagged on GH. Thus the tab was fully empty. Should it be hidden in that case?

SPI:

CocoaPods:

[daveverwer]

Currently the SPI has a prominent tab for release notes. I assume that's powered by GH releases, right?

That's correct, yes.

PS: I didn't have any official releases tagged on GH. Thus the tab was fully empty. Should it be hidden in that case?

Possibly. We've also talked about formatting commit messages into that tab, a little like GitHub also does. @Sherlouk even had a prototype of that working but we decided it needed to be a little richer in its display, which makes it a bigger feature to undertake.

Would you consider exposing CHANGELOG.md files (if existing) as a tab (or otherwise), similar to what CocoaPods does?

Certainly it's an interesting idea. I'd be interested to know what percentage of packages use a Changelog before committing to it.

Would you have an interest in working on the feature if that research turned up good numbers?

[calimarkus]

Would you have an interest in working on the feature if that research turned up good numbers?

Possibly yeah!

[daveverwer]

Interesting! Here are some very brief thoughts on what I think will be involved. It's not going to be a trivial feature to implement but is certainly possible.

The first thing we'll need to do is figure out which packages have a Changelog. The best place to do this will probably be the analysis process (which has access to a checked-out version of the repository) and we'll want to store a boolean value in the versions table. We'll probably never use any version record apart from the default branch version record, but we'll need a field in the database so it will need to be there for all. This work should be merged as a PR once completed so that we can run a full re-analysis cycle ahead of time so that the data is all there when the display code goes live.

Then, we'll need to display the changelog for pages where that flag and display a new tab. I don't think it should replace the Release Notes tab as it's quite possible repositories will have both.

In terms of rendering the changelog. I think we should leverage GitHub's rendering as we do for Readme files. They sanitise the HTML and render GFM tags which people may also be doing with their changelogs. We currently scrape the rendered GitHub page, which is not ideal at all (and we have #1095 logged to fix that) and it may make sense to do the same here, but we should check if the API mentioned in #1095 supports Changelog files, too, and if it does, consider prioritising #1095 before implementing this.

If you are interested, we'll need you to sign a standard Apache Contributor License Agreement before starting work. The easiest way to get that organised would be on our Discord.

[calimarkus]

There's the generic /markdown rendering API too, which could work for both cases. The Sublime Plugin facelessuser/MarkdownPreview uses this for previewing markdown.

/markdown has a limit of 400kb for the file size though. It seems like /repos/{owner}/{repo}/readme doesn't have that limitation. Not sure what percentage of repos would go over that limit and if that would be acceptable. We could also try to see what CocoaPods does, if that part is OpenSource.

To sum up your suggestions:

• Decide if Adopt the GitHub API for rendering README files #1095 should be done first
• Update analysis process to store a boolean value in the versions table (requires analysis cycle run)
• Display a new tab, when flag is set, render using GH APIs

[daveverwer]

I'm sure there are a few things we've forgotten, but yes that sounds good!