Discussion: changelogs button

[WilcoSp]

I'll would like to make a "changelogs" button for at the package page to allow for quicker checking newer versions of earlier installed packages.
But I do think it's best to discus first how we should get the link for the changelogs.

Atm I'm thinking of the following default behaviour:

1. For repository services that have a {repository}/releasesor equivalent page and is being used have the link go to it.
2. If ^ isn't used/supported then and there is a /changelogs.md file then link to it instead

But some may host their changelogs somewhere else, for this it may be handy to have a way in the package.json to specify where the changelogs are located.
For example Ag grid host their changelog somewhere else and vuetify has their changelogs both at github & their own website.

I was thinking of 2 ways to have this in package.json

1. Have a "changelogs" field in the root of the package.json (example: {"changelogs": "https://example.pkg/changes"})
   • pro: can easier be used by other websites
   • pro: has a (slight) chance of being adopted by npm
   • con: if adopted by npm they could bring breaking changes like with what css nesting did in sass/scss.
2. Have an "npmx" object field and then in there have "changelogs" field (example: {"npmx": {"changelogs": "https://example.pkg/changes"}})

• pro: allows for better control of the definition of the changelogs field even if npm adopts it.
• pro: with the npmx object field other features could also be added in the future.
• con: other website may not use this as they may see it outside of their control

Hopefully discussion brings a lot of ideas & feadback.

Also why not link to specific release changelog:

• in case their are versions between the installed version & latest version it will make the in between versions easier to read/reach.

[serhalp]

Very cool idea!

[ghostdevv]

I've implemented changelog before and what I landed on was (assuming we want to render the changelog, not just link to it)

1. Check the tarball for the CHANGELOG.md file
2. Check the repo for the CHANGELOG.md file
3. Pull from GitHub releases

I'm also looking to re-implement this on the work in progress api, but with better checks for the changelog file since we can process the whole tarball like yarn/algolia does here (although there are even more options I can think of).

con: if adopted by npm they could bring breaking changes like with what css nesting did in sass/scss.

The entire registry is full of inconsistencies so I think we'd be ok!

Have an "npmx" object field and then in there have "changelogs" field (example: {"npmx": {"changelogs": "https://example.pkg/changes"}})

If we could do it without this that'd be cool, especially if it encourages more people to ship a changelog file with their package

[WilcoSp]

I wasn't planning to display the changelogs in npmx but to link to them.
but it could be an idea to display the changelog.md or /releases (if there are api's available) within npmx at a new route, for example (/package-)changelog or (/package-)changes. the package- prefix depends if other routes are being changed or not.

If we could do it without this that'd be cool

It's totally optional and for near 99% of all packages on npm the default will work fine, it's only for those few that host the changelogs somewhere else or where they may have switched between Changelog.md <-> /releases

especially if it encourages more people to ship a changelog file with their package

I rather not encourage including the changelog.md as it does add to the install size and except for npmx it doesn't help developers much when included

The entire registry is full of inconsistencies so I think we'd be ok!

true

[gwennlbh]

yessss that would be a really nice feature. another alternative npm frontend does it like this: https://npm.willow.sh/package/swarpc@0.19.0/changelog

seems like it renders the CHANGELOG.md file and/or (maybe?) reads from the github releases' notes as a fallback

i changed my !npm bang to this frontend instead of npmx for that reason but tbh npmx seems to be developing really fast so ill switch to it i think!

[WilcoSp]

I've checked npm.willow.sh and they uses both readme.md & for github's /releases page with giving the readme.md the propriety.

I was thinking if we display the changelogs in npmx I check best would be to check for both and then check the last update date (not time) and pick which one is last updated, if both have the same date then readme.md gets the priority.

Also with pinia I've noticed that they have "Please refer to CHANGELOG.md for details", should we check for this and then display the referred changelog.md or should we keep it simple and only display the releases from github?

[beeequeue]

just writing down my two cents

i believe using a package's CHANGELOG.md file should be prioritized for various reasons.

as @WilcoSp said in the previous comment some release tabs only point to a changelog file (e.g. pinia, vite)

monorepos that use GH releases will also use them in different ways - some might have one entry listing every package that changed in that release, some will have separate releases for each package in the monorepo (the way Changesets does it)

if the changelog is read from a CHANGELOG.md file included in the package tarball it is also immutable (i think?), for better or for worse

not all (or many?) packages include a changelog file in the tarball of course, so agree with @ghostdevv about the prio order

1. tarball CHANGELOG.md, RELEASES.md, etc.
2. soruce code CHANGELOG.md, RELEASES.md, etc.
3. source forge releases

---

it would also be nice to be able to search for specific version numbers as doing that with GH releases currently is a major pain :)

[gwennlbh]

it would also be nice to be able to search for specific version numbers as doing that with GH releases currently is a major pain :)

We could even split up the changelog file into per-version changes and attach them to each version.

Renovate does this and it's really cool, when you get a upgrade PR for a package it shows the release notes, but only for the versions between the latest and the one you currently have

I searched a bit in their source code, I think the splitting logic is here: https://github.com/renovatebot/renovate/blob/179abe488afe8030b213130578e62791af35efcd/lib/workers/repository/update/pr/changelog/release-notes.ts#L349

I think that it boils down to splitting by heading that have the version in their text (if we had a strict, standardized way to format changelogs it'd be nice but the closest to that is https://keepachangelog.com and it's not that strict and not that popular too, unfortunately)

obviously, for github releases the splitting up part is trivial since each tag has its own release notes

also, seems like there's nuggets of useful information, as Renovate has been parsing changelogs for a pretty wide range of packages for a while:

/**
 * Determine how long to cache release notes based on when the version was released.
 *
 * It's not uncommon for release notes to be updated shortly after the release itself,
 * so only cache for about an hour when the release is less than a week old. Otherwise,
 * cache for days.
 */

(in the same file)

[vinnymac]

To feed the discussion, I put together a proof of concept here

[vinnymac]

@gwennlbh the caching optimization is intriguing, curious how we might do that optimally. Currently in my poc I just piggyback off the analysis in server/api/registry/analysis/[...pkg].get.ts