Documentation Change Logs are Frequently Outdated

[bradharms]

URL of the page

https://loopback.io/doc/en/lb4/changelog.repository.html
(and possibly others)

Nature of the issue

The change logs for Loopback packages on the official documentation site sometimes go without any updates for a long time after new versions are published on npmjs.org.

Expected behavior

Change logs on the Loopback documentation website should always include information about the most recent versions of Loopback packages published on npmjs.org.

Actual behavior

Today (2021-12-13), I have noted that @loopback/repository 4.0.0 was published 2021-11-18, yet the change log at the time of this writing only reports up to version 3.7.3 and is dated for 2021-10-18.

I have brought up this issue on Slack at #loopback-users and it is the second time I have done so. The first time was 2021-07-20.

Here are slack links to both of these previous reports:

• https://loopbackio.slack.com/archives/C01177XQN8N/p1626802414083800
• https://loopbackio.slack.com/archives/C01177XQN8N/p1639416915225600

Suggested resolution

Updates to change log should be automatically published for new versions at the same time as (or possibly slightly before) the code version, possibly through the use of a web hook or other trigger. This process should occur automatically without human intervention so that it does not accidentally get skipped. Someone should verify that the documentation publication is up to date after the publish of the npmjs.org package updates.

Other Notes

I previously opened this issue report here, but that issue tracker doesn't seem to get very much attention, and I have noticed that many issues for loopbackio/loopback-next are explicitly tagged as "Docs." Therefore I am re-reporting the issue here.

[dhmlau]

@bradharms, thanks for reporting this.

Taking a quick look, I suspect that the changelog is one release behind. For example the change log for @loopback/authentication had it updated for v7.3.4 (the version before 8.0) around the same time as the last release.

In the past, as a temp workaround, I thought a commit in loopback.io repo would force the script to rerun and pick up the latest changelog. However, this PR loopbackio/loopback.io#1268 just merged 3 hours ago, but the changelog wasn't got updated properly.

I'm not sure this problem exists around the time we moved to GitHub Actions. But that's something we need to investigate.

cc @achrinza

[bradharms]

Possibly related: #7483

[achrinza]

Possibly related: #7483

#7483 is a separate issue with regards to how certain terminals parse URLs for @loopback/cli.

@dhmlau @loopback/docs has a version NPM script, but I can't find calls to it. This seems to be responsible for generating the changelogs. Since the changelogs directory is in the gitignore (i.e. not published to NPM), it seems that the NPM Script needs to be called in the loopback.io repo.

[bradharms]

Any updates on this? It still appears to be a problem. Newest version of @loopback/repository listed in the change log is 4.1.2 but npm says 5.0.0.

I think this issue is significant because there are a frequent number of major version updates across Loopback packages over relatively short time frames. Major version updates imply the possibility of breaking changes, but without the change log, what those changes are is not always obvious, and neither is the required local code updates. That makes updating a leap of faith every time.