Upstream tracking

konnos consists of two layers:

┌─────────────────────────────────────────────────────────┐
│   konnos distribution layer (this repo, our code)      │
│   ─ Theme   (forge/theme/theme-konnos.css)             │
│   ─ Locale  (forge/locale/locale_en-US.ini)            │
│   ─ Templates  (forge/templates/{base,custom,repo,org}) │
│   ─ Brand   (forge/public/{logo,favicon,icon}.svg)     │
│   ─ Compose deploy  (docker-compose.yml)               │
│   ─ Migration script  (scripts/migrate-…)              │
├─────────────────────────────────────────────────────────┤
│   Upstream forge core (vendored as a Docker image)     │
│   image: codeberg.org/forgejo/forgejo:13                │
│   We never modify this. We never fork it. v0.4+.        │
└─────────────────────────────────────────────────────────┘

This guide covers bumping the lower layer — pulling a newer core image without breaking the upper layer. The upper layer is updated through normal git history on code.konnos.org/konnos/konnos.

When to bump

• Patch releases (e.g., 13.0.5 → 13.0.6): bug fixes, security patches. Usually safe; smoke-test the five surfaces below and ship.
• Minor releases (13.0 → 13.1): may add new locale strings, new templates. Run the full validation checklist.
• Major releases (13 → 14): full validation. May rename or remove CSS variables, locale keys, template paths. The distribution layer can break silently.

For the konnos.org reference instance we run a "rolling latest patch" strategy on the pinned major, and bump the major only after the distribution layer is verified.

Subscribing to upstream releases

Three options, pick whichever:

1. GitHub-style RSS — the upstream release feed is at the project's release page. Add to your reader.
2. Codeberg notifications — sign in to codeberg.org, watch the project, opt into release notifications.
3. DNS update checker — the running konnos instance can periodically check a TXT DNS record for new versions. Enabled by default; disable with [cron.update_checker] ENABLED = false in app.ini if you'd rather decide when to upgrade manually.

For konnos.org, we watch on Codeberg + dual-subscribe via RSS. Belt-and-braces.

Bump procedure — patch / minor

git checkout -b bump/forge-core-13-0-6

In docker-compose.yml, change the image tag:

-    image: codeberg.org/forgejo/forgejo:13
+    image: codeberg.org/forgejo/forgejo:13.0.6

Pin to the specific patch for the bump PR. After verification, you can revert to the major-only tag (:13) if you prefer rolling latest.

git add docker-compose.yml
git commit -s -m "chore: bump forge core to 13.0.6"
git push origin bump/forge-core-13-0-6

Open a PR. CI runs (DCO + shellcheck). The PR can't merge without the validation below.

Validation — the five surfaces

For each of these, sign in to a staging konnos instance running the new image and visually verify:

1. Top-left navbar logo — the konnos heart renders. Click it → home page loads.
2. Login page — the konnos brand still shows; sign-in works.
3. Repository view — open any repo; the theme colours match (charcoal background, hot rose only on accents).
4. Footer — reads konnos · v<X.Y.Z> (no upstream branding leak), Page/Template timing chips render.
5. Locale strings — open /admin/config and look for any "missing translation" warnings. New upstream strings will surface as locale gaps; fold them into forge/locale/locale_en-US.ini.

Plus a functional smoke test:

git clone https://staging.your-domain.com/your-org/some-repo.git /tmp/staging-clone
cd /tmp/staging-clone
git push origin main --dry-run     # validates SSH/HTTPS clone path

If any surface fails, the bump PR doesn't ship. Fix the breakage in the distribution layer (most commonly: theme CSS variable was renamed; update forge/theme/theme-konnos.css).

Bump procedure — major

Same as above, plus:

Run the locale diff

The upstream's locale_en-US.ini may have added new keys, removed obsolete ones, or refactored sections. Diff against the source you originally based on:

diff -u .cache/forgejo-upstream/options/locale/locale_en-US.ini \
  forge/locale/locale_en-US.ini | less

For each new upstream key, decide:

• Translation looks fine as-is → no action
• Translation has "Forgejo" or "Gitea" in it → sweep to "konnos"
• Translation refers to a feature konnos doesn't ship yet → leave for now

Use perl -i -pe 's/\bForgejo\b/konnos/g; s/\bGitea\b/konnos/g' to bulk-rebrand, then audit with git diff before committing.

Run the theme variable diff

If the upstream theme's CSS variable names changed, forge/theme/theme-konnos.css may reference variables that no longer exist (silent fallback to defaults — visually breaks the brand).

# extract variable names from upstream
grep -oE -- '--color-[a-z0-9-]+|--steel-[0-9]+' \
  .cache/forgejo-upstream/web_src/css/themes/theme-forgejo-dark.css | sort -u > /tmp/upstream-vars.txt
 
# extract from our overrides
grep -oE -- '--color-[a-z0-9-]+|--steel-[0-9]+' \
  forge/theme/theme-konnos.css | sort -u > /tmp/konnos-vars.txt
 
# variables we override that are no longer defined upstream
comm -23 /tmp/konnos-vars.txt /tmp/upstream-vars.txt

Anything that comes out of comm -23 is a variable we override that the new upstream doesn't define. Either:

• The variable was renamed → update our override to the new name
• The variable was removed → drop our override

Run the template path diff

Upstream may have moved or renamed templates we override (forge/templates/repo/create.tmpl, forge/templates/org/create.tmpl, forge/templates/base/footer_content.tmpl).

for tmpl in forge/templates/**/*.tmpl; do
  rel=${tmpl#forge/templates/}
  upstream=.cache/forgejo-upstream/templates/$rel
  if [ ! -f "$upstream" ]; then
    echo "GONE upstream:  $rel"
  fi
done

For each GONE line, the upstream template was removed or moved. Either remove our override (if the template is no longer used) or relocate it to the new path.

After validation passes

Squash-merge the PR. The konnos-forge Dokploy compose auto-redeploys via webhook on push to main. Monitor the deploy log:

• Image pull from codeberg.org/forgejo/forgejo:<new-tag> succeeds
• Postgres migrations apply (the runtime runs schema migrations at boot for major releases)
• Health check passes
• The five surfaces still look right on production

If anything regresses, roll back: revert the PR, re-deploy, the forgejo_data volume retains the old database state (migrations are forward-only — major rollbacks may need a Postgres restore from backup, see hardening.md).

Cadence

konnos.org follows this cadence:

The 📋 v0.2 — Upstream-tracking workflow ROADMAP item is to automate steps of the above (PR-on-release, automated locale-diff bot, etc.). For v0 it's manual. Get a feel for the manual rhythm before automating.

What about the v0.4+ "fork the core" plan?

Phase v0.4+ in the ROADMAP proposes forking the upstream Go binary so konnos owns the runtime end-to-end. Until that lands, the procedure above is the reality. After v0.4+, this guide becomes "how konnos-server's release process works" — different workflow entirely.