From 8f5a3c9ce9620acb05be4af94f7ddf0679917f2f Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Tue, 3 Feb 2026 11:42:56 -0800 Subject: [PATCH] Integrate towncrier into build workflow - Add uv install step to workflow - Run towncrier build before docs build (if fragments exist) - Commit changelog updates back to main - Update README: mark Phase 1b complete, add changelog docs Co-Authored-By: Claude Opus 4.5 --- .forgejo/workflows/build-blumeops.yaml | 54 +++++++++++++++++++++++++- docs/CHANGELOG.md | 8 ++++ docs/README.md | 36 +++++++++++------ 3 files changed, 84 insertions(+), 14 deletions(-) diff --git a/.forgejo/workflows/build-blumeops.yaml b/.forgejo/workflows/build-blumeops.yaml index e2bd2bc..a3fa581 100644 --- a/.forgejo/workflows/build-blumeops.yaml +++ b/.forgejo/workflows/build-blumeops.yaml @@ -3,8 +3,7 @@ # Creates a versioned release of BlumeOps with all build artifacts. # Currently includes: # - Documentation site (Quartz static build) -# -# Future additions may include other release artifacts. +# - Changelog (built from towncrier fragments) # # Usage: # 1. Go to Actions > Build BlumeOps > Run workflow @@ -69,6 +68,57 @@ jobs: - name: Checkout uses: actions/checkout@v4 + with: + # Need full history for git operations + fetch-depth: 0 + + - name: Install uv + run: | + curl -LsSf https://astral.sh/uv/install.sh | sh + echo "$HOME/.local/bin" >> "$GITHUB_PATH" + + - name: Build changelog + run: | + VERSION="${{ steps.version.outputs.version }}" + + # Check if there are any changelog fragments + FRAGMENTS=$(find docs/changelog.d -name "*.md" -not -name ".gitkeep" 2>/dev/null | wc -l) + + if [ "$FRAGMENTS" -gt 0 ]; then + echo "Found $FRAGMENTS changelog fragments, building changelog..." + ~/.local/bin/uvx towncrier build --version "$VERSION" --yes + echo "changelog_updated=true" >> "$GITHUB_OUTPUT" + else + echo "No changelog fragments found, skipping towncrier" + echo "changelog_updated=false" >> "$GITHUB_OUTPUT" + fi + id: changelog + + - name: Commit changelog updates + if: steps.changelog.outputs.changelog_updated == 'true' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + VERSION="${{ steps.version.outputs.version }}" + + # Configure git + git config user.name "Forgejo Actions" + git config user.email "actions@forge.ops.eblu.me" + + # Stage changes (CHANGELOG.md updated, fragments removed) + git add docs/CHANGELOG.md docs/changelog.d/ + + # Commit + git commit -m "Release $VERSION: Update changelog + + Built changelog from towncrier fragments. + + [skip ci]" + + # Push to main + git push origin HEAD:main + + echo "Changelog committed and pushed" - name: Build docs run: | diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 48ec64a..bbbe82b 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -8,6 +8,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [0.1.0] - 2026-02-03 +This is a historical release which doesn't actually exist and which aggregates +the changelogs prior to this date. The work on this blumeops project more or +less began around Jan 16 2026. To an extent you can find corroborating details +in the git commit log, but at the beginning (during this initial phase) there +was a fairly large amount of non-source-controlled work. If a more accurate +record is needed for this work, you may find it in borgmatic zk backups from +this time period. + ### Features - Add Grafana Alloy for metrics remote_write to Prometheus diff --git a/docs/README.md b/docs/README.md index b694cb9..76a2d19 100644 --- a/docs/README.md +++ b/docs/README.md @@ -53,17 +53,16 @@ The documentation is being restructured to follow the [Diataxis](https://diataxi **First release:** [v1.0.0](https://forge.ops.eblu.me/eblume/blumeops/releases/tag/v1.0.0) -### Phase 1b: CD & Hosting (Current) -- [ ] Build and tag `quartz` container (`mise run container-tag-and-release quartz v1.0.0`) -- [ ] Create ArgoCD manifests for `quartz` deployment -- [ ] Add `docs.ops.eblu.me` to Caddy reverse proxy -- [ ] Configure deployment with `DOCS_RELEASE_URL`: - ``` - https://forge.ops.eblu.me/eblume/blumeops/releases/download/v1.0.0/docs-v1.0.0.tar.gz - ``` -- [ ] Test end-to-end: commit -> build -> release -> deploy -- [ ] Set up `CHANGELOG.md` with [towncrier](https://towncrier.readthedocs.io/) using news fragments from zk cards -- [ ] Add `docs.ops.eblu.me` link to homepage dashboard +### Phase 1b: CD & Hosting (Complete) +- [x] Build and tag `quartz` container (`mise run container-tag-and-release quartz v1.0.0`) +- [x] Create ArgoCD manifests for `docs` deployment +- [x] Add `docs.ops.eblu.me` to Caddy reverse proxy +- [x] Configure deployment with `DOCS_RELEASE_URL` +- [x] Test end-to-end: commit -> build -> release -> deploy +- [x] Set up `CHANGELOG.md` with [towncrier](https://towncrier.readthedocs.io/) +- [x] Add `docs.ops.eblu.me` link to homepage dashboard (via gethomepage.dev annotations) + +**Docs URL:** https://docs.ops.eblu.me ### Phase 2: Tutorials Learning-oriented content for getting started. @@ -112,7 +111,8 @@ Understanding-oriented discussion of concepts and decisions. ``` docs/ ├── README.md # This file -├── CHANGELOG.md # Documentation changelog (planned) +├── CHANGELOG.md # Release changelog (built by towncrier) +├── changelog.d/ # Towncrier news fragments ├── tutorials/ # Learning-oriented (planned) ├── how-to/ # Task-oriented (planned) ├── reference/ # Information-oriented (planned) @@ -122,6 +122,18 @@ docs/ └── ... # Service-specific cards and notes ``` +## Adding Changelog Entries + +When making changes, add a news fragment to `docs/changelog.d/`: + +```bash +# Format: ..md +# Types: feature, bugfix, infra, doc, misc +echo "Add new feature X" > docs/changelog.d/20260203-feature-x.feature.md +``` + +Fragments are automatically collected into CHANGELOG.md when a release is built. + ## Viewing the ZK Cards To view all BlumeOps zettelkasten cards: