doc: Changelogs (#611)

Automatically generates changelogs based on git history

Author: elementbound

.github/workflows/check-uids.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Setup Godot
         uses: chickensoft-games/setup-godot@v1
         with:

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Lint
         run: sh/lint.sh
   test:

.github/workflows/publish-site.yml

@@ -18,7 +18,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 
-        uses: actions/checkout@v2
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
       - name: Setup Pages
         uses: actions/configure-pages@v3
       - name: Setup Python
@@ -47,5 +49,7 @@ jobs:
         run: sh/setup-plantuml.sh
       - name: Generate API docs
         run: sh/apidocs.sh
+      - name: Generate changelog
+        run: sh/changelog.ts > docs/changelog.md
       - name: Build
         run: PLANTUML_URL=http://localhost:8080/ sh/push-docs.sh

.github/workflows/release.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Setup Godot
         uses: chickensoft-games/setup-godot@v1
         with:

.github/workflows/validate-site.yml

@@ -13,7 +13,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 
-        uses: actions/checkout@v2
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Validate checkout
+        run: git branch -a && git tag && git log --format=oneline
       - name: Setup Python
         uses: actions/setup-python@v5
       - name: Setup Bun
@@ -41,6 +45,8 @@ jobs:
         run: sh/setup-plantuml.sh
       - name: Generate API docs
         run: sh/apidocs.sh
+      - name: Generate changelog
+        run: sh/changelog.ts > docs/changelog.md
       - name: Build
         run: PLANTUML_URL=http://localhost:8080/ NOPUSH=yes sh/push-docs.sh
 

.gitignore

@@ -32,6 +32,9 @@ docs/class-reference/*
 apidocs/
 classdb.json
 
+# Changelog - generated by sh/changelog.ts
+docs/changelog.md
+
 # Only for local use
 sh/ensure-uids.sh
 

docs/.gdignore

@@ -1 +0,0 @@
-

mkdocs.yml

@@ -30,6 +30,7 @@ markdown_extensions:
 nav:
   - 'index.md'
   - 'upgrading.md'
+  - 'changelog.md'
   - 'made-with-netfox.md'
   - 'faq.md'
   - 'external-tutorials.md'

sh/changelog.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env bun
+
+import { $ } from "bun";
+
+const ERR_NO_TAGS = 1;
+
+const REPO_LINK = "https://github.com/foxssake/netfox";
+const LATEST_REF = "HEAD";
+
+interface Semver {
+  prefix: string | undefined;
+  major: number;
+  minor: number;
+  patch: number;
+  suffix: string | undefined;
+}
+
+interface Commit {
+  hash: string;
+  description: string;
+}
+
+function parseSemver(version: string): Semver | undefined {
+  const pattern = /(v?)(\d+)\.(\d+)\.(\d+)([\.-].*)?/;
+  const matches = pattern.exec(version);
+  if (matches === null) return undefined;
+
+  const result = {
+    prefix: matches[1],
+    major: parseInt(matches[2]),
+    minor: parseInt(matches[3]),
+    patch: parseInt(matches[4]),
+    suffix: matches[5],
+  } as Semver;
+
+  if (result.suffix === "") result.suffix = undefined;
+
+  return result;
+}
+
+function compareSemver(a: Semver, b: Semver): number {
+  if (a.major != b.major) return a.major - b.major;
+  if (a.minor != b.minor) return a.minor - b.minor;
+  if (a.patch != b.patch) return a.patch - b.patch;
+  if (a.suffix != b.suffix) {
+    if (a.suffix === undefined) return 1; // a has no suffix, therefore it's more mature
+    if (b.suffix === undefined) return -1; // b has no suffix, therefore it's more mature
+    if (a.suffix !== undefined && b.suffix !== undefined)
+      return a.suffix.localeCompare(b.suffix);
+  }
+  return 0;
+}
+
+function stringifySemver(version: Semver): string {
+  return `${version.prefix ?? ""}${version.major}.${version.minor}.${version.patch}${version.suffix ?? ""}`;
+}
+
+function parseOnelineCommit(line: string): Commit | undefined {
+  const pattern = /([\w\d]+) (.+)/;
+  const matches = pattern.exec(line);
+  if (matches === null) return undefined;
+
+  return {
+    hash: matches[1],
+    description: matches[2],
+  };
+}
+
+function renderCommitDescription(description: string): string {
+  const pattern = /(.*)\(#([\d]+)\)$/;
+  const matches = pattern.exec(description);
+  if (matches === null) return description;
+
+  const body = matches[1];
+  const pullId = matches[2];
+  const link = `${REPO_LINK}/pull/${pullId}`;
+  return `${body}([#${pullId}](${link}))`;
+}
+
+function renderCommit(commit: Commit): string {
+  const link = `${REPO_LINK}/commit/${commit.hash}`;
+  const body = renderCommitDescription(commit.description);
+  return `${body} [🔗](${link})`;
+}
+
+function renderRelease(tag: string, commits: Commit[]): string {
+  const title = tag === LATEST_REF ? "Latest" : tag;
+  const body = commits.map((it) => "* " + renderCommit(it)).join("\n");
+  return `## ${title}\n${body}`;
+}
+
+async function main(): Promise<number> {
+  const versions = (await Array.fromAsync($`git tag`.quiet().lines()))
+    .filter((it) => it.startsWith("v"))
+    .map((it) => parseSemver(it))
+    .filter((it) => it !== undefined)
+    .sort(compareSemver)
+    .reverse()
+    .map(stringifySemver);
+
+  if (versions.length == 0) {
+    console.error("No version tags found!");
+    return ERR_NO_TAGS;
+  }
+
+  versions.unshift(LATEST_REF);
+
+  const logIntervals = versions.map((it, idx) => [
+    it,
+    versions.at(idx + 1) ?? "",
+  ]);
+
+  const logs = await Promise.all(
+    logIntervals
+      .map(([from, to]) =>
+        to !== ""
+          ? $`git log --format=oneline ${to}..${from}`.quiet().lines()
+          : $`git log --format=oneline ${from}`.quiet().lines(),
+      )
+      .map((it) => Array.fromAsync(it))
+      .map((it) =>
+        it.then((lines) =>
+          lines
+            .map(parseOnelineCommit)
+            .filter((commit) => commit !== undefined),
+        ),
+      ),
+  );
+
+  const releaseNotes = versions.map((version, idx) => [
+    version,
+    logs.at(idx) ?? [],
+  ]) as [string, Commit[]][];
+
+  console.log("# Changelog\n");
+  console.log(
+    releaseNotes
+      .map(([version, commits]) => renderRelease(version, commits))
+      .join("\n\n"),
+  );
+
+  return 0;
+}
+
+process.exit(await main());