App Store: changelog shows github tags even when there are no releases

[bergie]

For example:

However, the package does include a formatted CHANGELOG.md:

https://github.com/meri-imperiumi/signalk-meshtastic/blob/main/CHANGELOG.md

[dirkwa]

The current logic is:
a) Prefer Github releases (SignalK Plugins use this and the workfows SK Team uses automate this)
b) if absent - failback to Changelog.md

[clarkbw]

Only adding this for context. The change isn't that large. It's the behaviour that needs to be decided first.

diff --git a/src/appstore/detail.ts b/src/appstore/detail.ts
@@ -114,30 +114,30 @@ export async function buildPluginDetail(
     if (fetched.kind === 'ok') readmeText = fetched.text
   }
 
-  // Prefer GitHub Releases as the changelog source — that's where most
-  // plugin authors put real release notes. Fall back to a CHANGELOG.md in
-  // the published tarball for packages not hosted on GitHub. Rendered to
-  // Markdown via unified/rehype-remark so the existing Changelog tab
-  // renders release notes directly.
+  // Prefer a CHANGELOG.md published in the plugin's tarball — a curated,
+  // intentional artifact the author chose to ship. Fall back to GitHub
+  // Releases for the majority of plugins that don't keep a CHANGELOG.md but
+  // write release notes. Either source is rendered to Markdown (releases via
+  // unified/rehype-remark) so the existing Changelog tab displays it directly.
   let changelog = ''
   let changelogFormat: PluginDetailPayload['changelogFormat'] = 'synthesized'
 
-  const slug = parseGithubSlug(summary.githubUrl)
-  if (slug) {
-    const releases = await fetchReleasesMarkdown(slug.owner, slug.repo)
-    if (releases && releases.trim()) {
-      changelog = releases
-      changelogFormat = 'markdown'
-    }
+  const changelogFile = await fetchText(
+    changelogUrlFor(summary.name, summary.version)
+  )
+  if (changelogFile.kind === 'ok' && changelogFile.text.trim().length > 0) {
+    changelog = changelogFile.text
+    changelogFormat = 'markdown'
   }
 
   if (!changelog) {
-    const fetched = await fetchText(
-      changelogUrlFor(summary.name, summary.version)
-    )
-    if (fetched.kind === 'ok' && fetched.text.trim().length > 0) {
-      changelog = fetched.text
-      changelogFormat = 'markdown'
+    const slug = parseGithubSlug(summary.githubUrl)
+    if (slug) {
+      const releases = await fetchReleasesMarkdown(slug.owner, slug.repo)
+      if (releases && releases.trim()) {
+        changelog = releases
+        changelogFormat = 'markdown'
+      }
     }
   }

[bergie]

The current logic is: a) Prefer Github releases (SignalK Plugins use this and the workfows SK Team uses automate this) b) if absent - failback to Changelog.md

I would think that if both are present, the file actually supplied with the package ought to be more valuable than content retrieved from a proprietary and centralized web service.

Or at least, maybe we need some logic to recognize (and disregard) empty GH Releases, as the ones we have are just a result of a git tag.

[dirkwa]

@tkurki

I can understand both sides. What do you think about this logic change?

[tkurki]

Meshtastic has only tags,no releases https://github.com/meri-imperiumi/signalk-meshtastic/releases so the implementation seems to do something else than preferring releases…

[clarkbw]

oh i see now, @tkurki found a good counter example. releases.atom doesn't only return published Releases; GitHub synthesizes an <entry> for every git tag. So an auto-generated body of literally Release <tag>. The fetchReleasesMarkdown was never really preferring Releases for a tags-only repo, it is rendering tag placeholders, and those crowded out the CHANGELOG.md.

Side-by-side from the live feeds:

# meshtastic (tags, no Releases) — releases.atom
<title>1.4.0</title>
<content type="html">&lt;p&gt;Release 1.4.0&lt;/p&gt;</content>   ← placeholder

# signalk-server (real Releases) — releases.atom
<title>v2.28.0</title>
<content type="html">&lt;h2&gt;🚀 Main New Features&lt;/h2&gt;...   ← real

The atom XML feed is otherwise identical for tags vs Releases (same <id>/<link>/<author>), so the only reliable tell is the placeholder body.

If we filter out the placeholder entries before rendering. If nothing real remains, the existing CHANGELOG.md fallback kicks in; exactly happens for meshtastic. This should prefer releases and only changes behavior for repos whose "releases" were actually just tags.

Something like this:

+function isPublishedRelease(entry: GithubReleaseEntry): boolean {
+  const body = entry.bodyMarkdown.trim()
+  return body !== '' && body !== `Release ${entry.tag}`
+}
...
-  const entries = await parseReleasesFeed(xml)
+  const entries = (await parseReleasesFeed(xml)).filter(isPublishedRelease)

want me to PR that?

[tkurki]

Is there reason not to use a releases specific api?

https://api.github.com/repos/meri-imperiumi/signalk-meshtastic/releases
https://api.github.com/repos/signalk/signalk-server/releases

[clarkbw]

Assuming we can stay within the rate-limits that path works. Unauthenticated its a 60 req / hr limit so when someone first opens up the page they could possibly hit that limit. After first run it's pretty unlikely.

[tkurki]

Right. Is the current way more rate limit friendly?

[bergie]

Note on rate limits: Starlink recycles IPs quite aggressively, so boats using Starlink are very likely to hit rate limits before they get even one request through.

[clarkbw]

The atom feed is the more rate-limit friendly of the two. releases.atom is served off github.com, not api.github.com, so it doesn't touch the 60/hr unauthenticated REST budget. The /releases REST endpoint does count against it. I double checked even though Claude agreed.

For most people the 60/hr ceiling won't matter, but it could bite exactly the users
we care about, new users and those on starlink. Opening the App Store shouldn't be the thing that trips it.

Implementing both with some failover is too complicated. I'd lean toward staying on atom and just filtering the tag placeholders. It keeps us on the cheaper endpoint and only changes behavior for repos whose "releases" were never real releases to begin with. meshtastic falls back to its
CHANGELOG.md, signalk-server keeps its real notes.

I think this is the best path forward.

[bergie]

Doesn't seem to work reliably yet.

Examples:
https://github.com/BoatHacks/signalk-stowage-mgmt/blob/main/CHANGELOG.md

https://github.com/meri-imperiumi/signalk-logbook/blob/main/CHANGELOG.md

@tkurki can you reopen?