Refactor changelog management and update workflows for version-first authoring

mitchdowney · mitchdowney · commit 6355dbb9fc92 · 2026-04-24T00:01:20.000-05:00
- Transitioned from `CHANGELOG-UPCOMING.md` to semver-named changelog files located in `docs/development/CHANGELOGS/`, enabling continuous updates during development.
- Updated `publish-main.yml` and `publish-staging.yml` workflows to read release notes from the new semver changelog files.
- Enhanced `bump-version.sh` to create and stage the changelog file upon version bump, ensuring immediate availability for updates.
- Deprecated the use of `CHANGELOG-UPCOMING.md` in documentation and workflows, streamlining the changelog process for both staging and main releases.
- Added a new changelog file for version 0.1.10 to reflect the migration to the new system.
diff --git a/.cursor/skills/cursor-copilot-sync/SKILL.md b/.cursor/skills/cursor-copilot-sync/SKILL.md
@@ -44,4 +44,5 @@ Use this workflow whenever customization files are changed.
 
 - Rules are transformed from Cursor frontmatter (`globs`, `alwaysApply`) to Copilot frontmatter (`applyTo`).
 - Skill frontmatter is normalized so `name` matches the skill folder name.
+- Skill markdown should keep exactly one blank line between closing frontmatter (`---`) and content.
 - Validation enforces source/mirror parity for skills, rules, and `.cursorrules`/`copilot-instructions`.
diff --git a/.cursor/skills/release-changelog/SKILL.md b/.cursor/skills/release-changelog/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: release-changelog
-description: "Keep the upcoming release note buffer updated on develop; ties into publish-staging and publish-main (RTM) and GitHub release/archive automation."
+description: "Use version-first changelog files (docs/development/CHANGELOGS/X.Y.Z.md): bump version at start of work and write release notes continuously for staging and main releases."
 ---
 
 # Release changelog (Metaboost)
@@ -11,13 +11,15 @@ When you ship or finish work that is **worth calling out** in preprod/prod relea
 
 ## What to update
 
-- Edit [docs/operations/CHANGELOG-UPCOMING.md](../../docs/operations/CHANGELOG-UPCOMING.md) on **`develop` only** (promotion branches are triggers only—see [PUBLISH.md](../../PUBLISH.md)).
+- Use [docs/development/CHANGELOGS/X.Y.Z.md](../../docs/development/CHANGELOGS/) where `X.Y.Z` is the current base version in `package.json`.
+- Bump version **at the start of work** with `scripts/publish/bump-version.sh` so `docs/development/CHANGELOGS/X.Y.Z.md` exists before implementation.
+- Keep updating that same semver file continuously as work lands.
 
 ## Conventions
 
 1. **Order** — **Most important first** (safety, security, data, then big features, then smaller fixes; skip low-signal items).
 2. **Wording** — Short, clear lines; link issues/PRs if useful.
-3. **Markers** — Put new bullets between `UPCOMING-AUTO-START` and `UPCOMING-AUTO-END` so post-publish automation can reset that block via PR. Notes **above** the block are not auto-cleared.
+3. **Single source** — Staging prereleases and main production releases both read the same `X.Y.Z.md` file.
 4. **Brevity** — Concise, not a duplicate of git log.
 
 ## Naming in CI
diff --git a/.github/skills/cursor-copilot-sync/SKILL.md b/.github/skills/cursor-copilot-sync/SKILL.md
@@ -44,4 +44,5 @@ Use this workflow whenever customization files are changed.
 
 - Rules are transformed from Cursor frontmatter (`globs`, `alwaysApply`) to Copilot frontmatter (`applyTo`).
 - Skill frontmatter is normalized so `name` matches the skill folder name.
+- Skill markdown should keep exactly one blank line between closing frontmatter (`---`) and content.
 - Validation enforces source/mirror parity for skills, rules, and `.cursorrules`/`copilot-instructions`.
diff --git a/.github/skills/release-changelog/SKILL.md b/.github/skills/release-changelog/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: release-changelog
-description: "Keep the upcoming release note buffer updated on develop; ties into publish-staging and publish-main (RTM) and GitHub release/archive automation."
+description: "Use version-first changelog files (docs/development/CHANGELOGS/X.Y.Z.md): bump version at start of work and write release notes continuously for staging and main releases."
 ---
 
 # Release changelog (Metaboost)
@@ -11,13 +11,15 @@ When you ship or finish work that is **worth calling out** in preprod/prod relea
 
 ## What to update
 
-- Edit [docs/operations/CHANGELOG-UPCOMING.md](../../docs/operations/CHANGELOG-UPCOMING.md) on **`develop` only** (promotion branches are triggers only—see [PUBLISH.md](../../PUBLISH.md)).
+- Use [docs/development/CHANGELOGS/X.Y.Z.md](../../docs/development/CHANGELOGS/) where `X.Y.Z` is the current base version in `package.json`.
+- Bump version **at the start of work** with `scripts/publish/bump-version.sh` so `docs/development/CHANGELOGS/X.Y.Z.md` exists before implementation.
+- Keep updating that same semver file continuously as work lands.
 
 ## Conventions
 
 1. **Order** — **Most important first** (safety, security, data, then big features, then smaller fixes; skip low-signal items).
 2. **Wording** — Short, clear lines; link issues/PRs if useful.
-3. **Markers** — Put new bullets between `UPCOMING-AUTO-START` and `UPCOMING-AUTO-END` so post-publish automation can reset that block via PR. Notes **above** the block are not auto-cleared.
+3. **Single source** — Staging prereleases and main production releases both read the same `X.Y.Z.md` file.
 4. **Brevity** — Concise, not a duplicate of git log.
 
 ## Naming in CI
diff --git a/.github/workflows/publish-main.yml b/.github/workflows/publish-main.yml
@@ -103,12 +103,12 @@ jobs:
             const owner = context.repo.owner;
             const repo = context.repo.repo;
             const fs = require("fs");
-            const path = "docs/operations/CHANGELOG-UPCOMING.md";
+            const path = "docs/development/CHANGELOGS/" + base + ".md";
             let body;
             if (fs.existsSync(path)) {
               body = fs.readFileSync(path, "utf8");
             } else {
-              body = "Production build; no " + path + " at this commit.";
+              body = "Production build; no " + path + " at this commit. Bump version on develop at the start of work and write notes continuously in that file.";
             }
             try {
               await github.rest.git.createRef({
diff --git a/.github/workflows/publish-staging.yml b/.github/workflows/publish-staging.yml
@@ -282,13 +282,14 @@ jobs:
         with:
           script: |
             const version = "${{ needs.reserve-version.outputs.version }}";
-            const path = "docs/operations/CHANGELOG-UPCOMING.md";
+            const baseVersion = version.replace(/-(staging|alpha|beta)\.\d+$/, "");
+            const path = "docs/development/CHANGELOGS/" + baseVersion + ".md";
             const fs = require("fs");
             let body;
             if (fs.existsSync(path)) {
               body = fs.readFileSync(path, "utf8");
             } else {
-              body = "Prerelease; no " + path + " at this commit.";
+              body = "Prerelease build; no " + path + " at this commit. Bump version on develop at the start of work and write notes continuously in that file.";
             }
             const tag = version;
             const owner = context.repo.owner;
@@ -301,74 +302,3 @@ jobs:
             await github.rest.repos.createRelease({
               owner, repo, tag_name: tag, name: tag, body, prerelease: true,
             });
-
-  changelog-pr-to-develop:
-    needs: [github-prerelease-create, reserve-version, verify-published-tags]
-    if: success()
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: develop
-          persist-credentials: false
-      - name: Write archive and reset UPCOMING markers
-        uses: actions/github-script@v7
-        env:
-          PUBLISH_SHA: ${{ github.sha }}
-          PUBLISH_VERSION: ${{ needs.reserve-version.outputs.version }}
-          RUN_ID: ${{ github.run_id }}
-          REF_NAME: ${{ github.ref_name }}
-        with:
-          script: |
-            const fs = require("fs");
-            const owner = context.repo.owner;
-            const repo = context.repo.repo;
-            const ref = process.env.PUBLISH_SHA;
-            const version = process.env.PUBLISH_VERSION;
-            const runId = process.env.RUN_ID;
-            const refName = process.env.REF_NAME || "unknown";
-            const label = refName === "main" ? "production" : refName;
-            const upcomingPath = "docs/operations/CHANGELOG-UPCOMING.md";
-            let upcoming = "";
-            try {
-              const { data } = await github.rest.repos.getContent({ owner, repo, path: upcomingPath, ref });
-              if (data && data.type === "file" && "content" in data && "encoding" in data && data.encoding === "base64") {
-                upcoming = Buffer.from(String(data.content).replace(/\n/g, ""), "base64").toString("utf8");
-              }
-            } catch (e) {
-              if (e.status === 404) { upcoming = ""; } else { throw e; }
-            }
-            const safe = version.replace(/\./g, "-");
-            const dir = "docs/operations/CHANGELOG-ARCHIVE";
-            fs.mkdirSync(dir, { recursive: true });
-            const head =
-              "# Release " + version + " (" + label + ")\n\n" +
-              "From [`" + ref.substring(0, 7) + "`](https://github.com/" + owner + "/" + repo + "/commit/" + ref + "]) — " +
-              "[workflow run](https://github.com/" + owner + "/" + repo + "/actions/runs/" + runId + ").\n\n";
-            fs.writeFileSync(dir + "/RELEASE-" + safe + ".md", head + (upcoming || "_(no CHANGELOG-UPCOMING at that commit.)_\n"));
-            if (fs.existsSync(upcomingPath)) {
-              let s = fs.readFileSync(upcomingPath, "utf8");
-              if (s.includes("UPCOMING-AUTO-START") && s.includes("UPCOMING-AUTO-END")) {
-                s = s.replace(
-                  /<!--\s*UPCOMING-AUTO-START\s*-->[\s\S]*?<!--\s*UPCOMING-AUTO-END\s*-->/m,
-                  "<!-- UPCOMING-AUTO-START -->\n" +
-                    "<!-- Add concise bullets (most important first) for the next significant changes. -->\n" +
-                    "<!-- UPCOMING-AUTO-END -->\n"
-                );
-                fs.writeFileSync(upcomingPath, s, "utf8");
-              }
-            }
-      - uses: peter-evans/create-pull-request@v6
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          commit-message: "chore: archive changelog for ${{ github.ref_name }} ${{ needs.reserve-version.outputs.version }}"
-          title: "chore: archive changelog for ${{ needs.reserve-version.outputs.version }} (${{ github.ref_name }})"
-          body: |
-            Automated follow-up to a successful [publish](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}) on `${{ github.ref_name }}`.
-          base: develop
-          branch: automation/changelog-${{ github.ref_name }}-${{ needs.reserve-version.outputs.version }}-${{ github.run_id }}
-          delete-branch: true
-          signoff: false
diff --git a/.llm/history/active/semver-changelog-workflow/semver-changelog-workflow-part-01.md b/.llm/history/active/semver-changelog-workflow/semver-changelog-workflow-part-01.md
@@ -0,0 +1,33 @@
+### Session 1 - 2026-04-23
+
+#### Prompt (Developer)
+
+how are these PRs supposed to work? i think we need a different, and simpler system. instead of using a "recent" file to accumulate changelog, the changelog should simply be written by the LLM continuosly as it goes. to make this work, we will now make it a part of our process to bump the version at the BEGINNING of work, rather than at the end of work. since we bump at the beginning, LLM will know which changelog to write as we go. make sure there are vs code and cursor skills to remind you of this. the change logs should go in their own separate files named after the semver. we do not need separate staging changelogs, these changelogs represent the version number which will eventually be graduated to production anyway
+
+https://github.com/podverse/podverse/pull/154
+
+Start implementation
+
+#### Key Decisions
+
+- Switched from `CHANGELOG-UPCOMING.md` accumulation to semver-named changelog files at `docs/development/CHANGELOGS/X.Y.Z.md`.
+- Updated staging and main publish workflows to read release notes from the base semver changelog file.
+- Removed staging post-publish changelog archive/reset PR job from publish workflow.
+- Updated `scripts/publish/bump-version.sh` to create and stage the semver changelog file during version bump so changelog writing starts immediately.
+- Updated publish docs and release-changelog skill guidance to enforce version-first changelog authoring.
+- Ran Cursor-to-Copilot sync/check so mirrored `.github` customization files stay aligned with `.cursor` source changes.
+
+#### Files Modified
+
+- .llm/history/active/semver-changelog-workflow/semver-changelog-workflow-part-01.md
+- .cursor/skills/release-changelog/SKILL.md
+- .github/skills/release-changelog/SKILL.md
+- .github/workflows/publish-staging.yml
+- .github/workflows/publish-main.yml
+- scripts/publish/bump-version.sh
+- docs/PUBLISH.md
+- docs/operations/CHANGELOG-UPCOMING.md
+- docs/operations/CHANGELOG-ARCHIVE/DOCS-OPERATIONS-CHANGELOG-ARCHIVE.md
+- docs/development/CHANGELOGS/0.1.10.md
+- .github/instructions/*.instructions.md (sync rewrite updates)
+- .github/skills/*/SKILL.md (sync rewrite updates)
diff --git a/docs/PUBLISH.md b/docs/PUBLISH.md
@@ -10,7 +10,7 @@ Two workflows cover release artifacts:
 | `staging`  | Full build + push    | `X.Y.Z-staging.N` (N via Git ref API)   | `staging`         |
 | `main`     | Promote (crane copy) | `X.Y.Z` (from root `package.json` base) | `prod`            |
 
-**Changelog (staging only):** The **staging** workflow reads [`docs/operations/CHANGELOG-UPCOMING.md`](operations/CHANGELOG-UPCOMING.md) on the build commit, creates a **prerelease** GitHub Release, and opens a **PR to `develop`** to append [`CHANGELOG-ARCHIVE/`](operations/CHANGELOG-ARCHIVE/DOCS-OPERATIONS-CHANGELOG-ARCHIVE.md) and clear the `UPCOMING` auto block. See the [release-changelog skill](../.cursor/skills/release-changelog/SKILL.md). The **main** workflow uses `CHANGELOG-UPCOMING` on the promote commit for the RTM release body when present.
+**Changelog:** Both **staging** prereleases (`X.Y.Z-staging.N`) and **main** RTM releases (`X.Y.Z`) read release notes from [`docs/development/CHANGELOGS/X.Y.Z.md`](development/CHANGELOGS/). Bump the base version at the start of work with `scripts/publish/bump-version.sh` so the semver changelog file exists immediately, then update that file continuously as work lands.
 
 **Promotion:** all product changes land on **`develop`**. **Promotion branches** (mirrors) are: **`sync-develop-to-staging.sh`**, **`sync-develop-to-main.sh`**. There is no **`beta`** publish line.
 
@@ -30,7 +30,7 @@ Pre-release image tags use **`X.Y.Z-staging.N`** and a floating **`:staging`** s
 
 ## What the staging branch is for
 
-The **`staging`** branch is the preprod build line. Default development branch remains **`develop`**. When you fast-forward `staging` from `develop` (or run **Publish (staging)** via **Run workflow** on a chosen ref), the GitHub Action validates, reserves `X.Y.Z-staging.N`, builds images, pushes to GHCR, verifies tags, creates a matching **Git tag**, and creates/updates a **prerelease GitHub Release** (see [CHANGELOG-UPCOMING](operations/CHANGELOG-UPCOMING.md)).
+The **`staging`** branch is the preprod build line. Default development branch remains **`develop`**. When you fast-forward `staging` from `develop` (or run **Publish (staging)** via **Run workflow** on a chosen ref), the GitHub Action validates, reserves `X.Y.Z-staging.N`, builds images, pushes to GHCR, verifies tags, creates a matching **Git tag**, and creates/updates a **prerelease GitHub Release** from `docs/development/CHANGELOGS/X.Y.Z.md`.
 
 No Kubernetes manifests are applied from this repo to remote clusters. Clusters consume image pins from your **GitOps** repository (e.g. Argo CD `Application` `targetRevision`, Kustomize `newTag`).
 
diff --git a/docs/development/CHANGELOGS/0.1.10.md b/docs/development/CHANGELOGS/0.1.10.md
@@ -0,0 +1,7 @@
+# Changelog 0.1.10
+
+_Update this file continuously during development for version 0.1.10._
+
+## Highlights
+
+- Migrate changelog process to semver-named files and version-first authoring.
diff --git a/docs/operations/CHANGELOG-ARCHIVE/DOCS-OPERATIONS-CHANGELOG-ARCHIVE.md b/docs/operations/CHANGELOG-ARCHIVE/DOCS-OPERATIONS-CHANGELOG-ARCHIVE.md
@@ -1,5 +1,7 @@
 # Archived release notes (generated)
 
+> Deprecated: release notes now come directly from `docs/development/CHANGELOGS/X.Y.Z.md` files.
+
 This directory is populated by automation after a successful publish (GitHub Actions) from `alpha`, `beta`, or `main`.
 
 Each `RELEASE-*.md` archives [CHANGELOG-UPCOMING.md](../CHANGELOG-UPCOMING.md) as of the build commit, with metadata.
diff --git a/docs/operations/CHANGELOG-UPCOMING.md b/docs/operations/CHANGELOG-UPCOMING.md
@@ -1,5 +1,7 @@
 # Changelog (upcoming)
 
+> Deprecated: use `docs/development/CHANGELOGS/X.Y.Z.md` instead. Release workflows now read changelog content from semver-named files.
+
 **Edit on `develop` only.** This file powers GitHub release notes and archive files when a publish runs from `alpha` (prerelease tags `X.Y.Z-staging.N` + float `:staging`), `beta` (`-beta.N` + `:beta`), or `main` (RTM `X.Y.Z` + `:prod`). See [PUBLISH](../PUBLISH.md).
 
 List **most important** user-facing or ops changes first. Keep the list concise, not a git log.
diff --git a/scripts/publish/bump-version.sh b/scripts/publish/bump-version.sh
@@ -42,6 +42,23 @@ if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
   exit 1
 fi
 
+CHANGELOG_DIR="$REPO_ROOT/docs/development/CHANGELOGS"
+CHANGELOG_FILE="$CHANGELOG_DIR/$VERSION.md"
+
+mkdir -p "$CHANGELOG_DIR"
+if [[ ! -f "$CHANGELOG_FILE" ]]; then
+  cat > "$CHANGELOG_FILE" << EOF
+# Changelog $VERSION
+
+_Update this file continuously during development for version $VERSION._
+
+## Highlights
+
+- Add notable changes for this version.
+EOF
+  echo -e "${GREEN}Created changelog file:${NC} $CHANGELOG_FILE"
+fi
+
 CURRENT_BRANCH=$(git branch --show-current)
 echo -e "${YELLOW}Bumping version to $VERSION on branch '$CURRENT_BRANCH'...${NC}"
 
@@ -91,6 +108,7 @@ for ws in $WORKSPACES; do
     git add "$ws/package-lock.json"
   fi
 done
+git add "$CHANGELOG_FILE"
 
 git commit --no-verify -m "chore: bump version to $VERSION"
 echo -e "${YELLOW}Pushing to origin/$CURRENT_BRANCH...${NC}"
