Discussion: changelogs button

[WilcoSp]

in this issue we discuss, come up with ideas, give feedback & contribute to adding & evolving changelogs to npmx.
below is a roadmap and below that there is the original starting message of this discussion.

roadmaps in PRs (updated March 4th)

1. button, page & basic viewers (these will cover most people) (feat: adding gh changelog/releases to npmx #1233 (ready for review & merge), preview)
   • changelog button at button page
   • /package-changes/ page
   • a basic changelog.md viewer component with toc
   • basic releases viewer component
   • automatic scrolling to the as close as possible to the requested version with date+version (fallback to date)
   • check whether the changelog.md from the latest release is in the repository directory specified in the npm package or the root of the package

1.5 some refactoring which isn't possible in a big branch

• refactor the markdown renderer to better share code with the readme renderer

2. most of the other repositories services (if needed this can be spread across multiple PRs for each service)
   • add support for other git service provider documented here for releases
   • add support for other git service providers documented here for changelog.md
   • add support for for automatic links to pull/merge requests (#pr), issues (#issue) and users (@person)
     • parse from plain text to a link
     • parse from link to git provider style for the issue/pr/user
   • improve experience when switching between package version's by using useRouteParamss and only re render when the repository has been changed (example vue 3 <-> vue 2) (this isn't needed anymore, how now background resolving works it gives the same result)
   • have a button to the changelogs page in the package dependencies
   • at the package page have buttons next to selectable package versions (similar to feat: link to releases #1368)

• filters for releases

  • support for filtering for specific packages within releases (does need heading to be package@version)
  • support for filtering to specific version range (for example 3.5.x or 3.x.x)

• more advanced features for changelog.md

  • split the versions by heading (semver regex)

• add npmx.changelog fields for package.json that can't be covered by the PRs above, this will be a separate issue when the time comes

  • add possibility for self hosted repositories give information how their repository platform
    • allow to give information how each url is formatted
    • allow giving info that the git platform is a self hosted version of gitlab, gitea, forgejo etc
  • allow giving where the changelog.md is located in repository (for if it's a very specific)
  • allow to give a website url where the changelog can be found if not hosted on any git provider (self hosted)

those numbered will be made in order, those without are more free in which order they're made after the ordered ones

Also the PRs above aren't final and could be changed till the moment it's merged.
You're free to share your ideas and make your own PRs even if they're not in the roadmap.
PRs can also be merged to my or someone else's fork first and to then together create a bigger PR to npmx

original message

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

[WilcoSp]

I'll be splitting up all the additions into multiple PRs, this is spread the workload and also allow basic functionality be available sooner compared to everything in 1 big PR

I think these will be the PRs

1. button, page & basic viewers (these will cover most people)
   • the changelog button at package page (thanks Vinny for how it should look and for whether it should be shown)
   • a changelog page where basic data is fetched to determine which of the 2 below viewer components should be used.
   • a basic changelog.md viewer component (at least github but if easily done also others) (if possible with links to each version header)
   • a basic gh releases viewer component
2. most of the other repositories services (if needed this can be spread across multiple PRs for each service)
   • if not in PR1, then here changelog.md for the others services
   • the releases api from the other services where possible.

• filters for releases
  • support for monorepos where each package gets their own changelog
  • support to select 1 to multiple versions (if possible even groups of versions, for example only 2.x.x)
• more advanced changelog.md where versions can be split by version headings

those numbered will be made in order, those without are more free in which other they're made after the ordered ones

Also the PRs above aren't final and could have things added to them or even new PRs could be added to the list

Also for the releases APIs can best be made into adapters which so that in components it's easier to request changelogs