Skip to content

Templates: Rewrote the architecture guide for the Forgejo theme - #147

Merged
whereareiam merged 4 commits into
devfrom
docs/forgejo-architecture
Oct 28, 2026
Merged

Templates: Rewrote the architecture guide for the Forgejo theme#147
whereareiam merged 4 commits into
devfrom
docs/forgejo-architecture

Conversation

@whereareiam

@whereareiam whereareiam commented Oct 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Lands the whole cleanup stack. This pull request targets dev and carries four commits, each kept as its own commit by the rebase merge: #144 (build cleanup), #145 (preview stamping), #146 (bun drift) and this one (the docs). Merging the stack one pull request at a time would mean rebasing after every merge, because a rebase merge rewrites the commits the next pull request is built on. #144–#146 are closed once this merges. All four are skip-changelog.

Rebased onto dev after the page conversions merged: the hand-written list of page stylesheets that #144 replaces had grown to 16 entries, and the directory read now ships all of them. The wiki test checked that list for wiki.css; it now checks that wiki.css ships in the build. Every commit builds and passes the tests on its own, the shared preview runs from the stamped copy (#145), and bun drift runs.

Summary

ARCHITECTURE.md still described the Gitea CSS generator: it named the project "Gitea GitHub Theme", described a "single-file Gitea constraint", and covered Forgejo only in a short section at the top. CONTRIBUTING.md had stale paths and never mentioned styles/pages.

ARCHITECTURE.md now describes the two parts the theme ships:

  • Theme stylesheets (dist/theme-github-*.css): built from the palette pipeline and the TypeScript overrides in styles/. The pipeline description is kept, in a shorter form.
  • Template pack (dist/forgejo): scripts/assembleForgejo.ts builds it from templates/, components/, styles/pages/ and public/.

It also adds a source layout table and covers how asset links get their content version, the local preview, the release archives and the tests. The key decisions now explain why a rule for Forgejo's own markup belongs in styles/ and a rule for the theme's markup sits beside its template.

CONTRIBUTING.md gains three rules:

  • Where new styles go: styles/ for Forgejo's own markup, components/ for reusable UI, styles/pages/*.css for page-only CSS, and public/ only for assets that a page template links itself.
  • Class naming: theme-* for shared components, github-* for layout and state hooks on overridden templates, and a page prefix such as profile-, org- or actions- for page-only CSS.
  • Stacking order: the z-index scale from motion.css.

The directory table now lists components, styles/pages, public and dev. Stale references now point to base/component_assets.tmpl, components/common/sidebar/toggle, results.js and profile_package_versions.tmpl.

Documentation only; the build output is unchanged.

Release notes

  • The title follows Area: Description with a listed area
  • The title describes the effect in the past tense, for example Branches: Fixed ...
  • Exactly one label: feature, change, bug, dependencies, or skip-changelog
  • bug only for a bug that shipped in a release; a fix for a bug that only existed on dev is skip-changelog
  • major added when admins must act on upgrade, for example a new minimum Forgejo version
  • Upgrade steps or warnings added to .github/release-notes.md, if admins need them

Checks

  • Tests added or updated
  • Checked in the dev preview at desktop and phone width, in dark and light mode

🤖 Generated with Claude Code

@whereareiam whereareiam added the skip-changelog Left out of the release notes label Oct 28, 2026
@whereareiam whereareiam mentioned this pull request Oct 28, 2026
Merged
whereareiam and others added 4 commits October 28, 2026 19:27
@whereareiam @claude
chore(build): one source per shipped file, no gitea reference files
2c8a558 
gitea/ held 15 upstream Gitea files that update:gitea refreshed from
go-gitea at the tag of the theme's own version, a number that follows
this theme's releases and not Gitea's, and nothing read them. They go
with the script, its proxy helper and the undici dependency only it
used.

Vite copied public/ into dist/ and the assembler then copied the page
stylesheets into the Forgejo tree twice, once from public/ and once
from dist/. Vite now leaves public/ alone (publicDir: false), so dist/
holds only the themes and the assembler copies public/ itself. The
assembler also copies every stylesheet in styles/pages instead of a
hand-written list; a test checks that each one is linked from
component_assets.tmpl, so a new page stylesheet only needs that link.
dist/forgejo is byte for byte the same as before.

The preview ran its one-off chown and cleanup containers on Forgejo
16.0.3 while Compose ran 17.0.0; the constant now names 17.0.0 and a
test keeps it equal to the Compose service's image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@whereareiam @claude
fix(preview): stamp a preview copy of the build, not dist
1fed0d9 
The preview added ?preview=<revision> to the auto themes' imports in
dist/forgejo itself, so src/build-output.test.ts failed after any
dev:forgejo session until the next bun bundle. The stamp also went
after the path, before the content version the bundle had already
appended, which made links with two question marks such as
theme-github-dark.css?preview=<id>?v=<hash>.

ThemeSynchronizer now copies the built css and js into
dev/.generated/public/assets, and the reloader stamps that copy and
writes preview-revision.json there. The Compose file mounts it instead
of dist, and a sync recreates the container rather than restarting it,
so a preview started before this change picks up the new mounts. The
revision joins any existing query with &, keeping one query per link.

The fixture README explains how to sign in as sam, whose password is
preview-fixture like every fixture user other than alex.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@whereareiam @claude
feat(templates): add bun drift to compare overrides with forgejo
c209a0e 
The template overrides are copies of Forgejo's templates, but nothing
recorded which release they came from, so an upgrade showed no sign of
the overrides that fell behind.

The forgejo field of package.json now pins that release. The preview
derives its image from it, which also replaces the 16.0.3 image its
docker run commands still named, and a test checks that
docker-compose.yml runs the same release.

bun drift checks out the templates of a release into
node_modules/.cache/forgejo with a sparse git clone and lists each
override by the lines the theme added and removed, then the templates
Forgejo does not have. Given two releases, it lists the overridden
templates Forgejo changed between them with Forgejo's diff, and the
ones it added or removed, so a maintainer knows what to port.
CONTRIBUTING.md describes the steps in a new Upgrading Forgejo section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@whereareiam @claude
docs(architecture): describe the forgejo theme and where styles go
b82f91d 
ARCHITECTURE.md still described the Gitea CSS generator, with a short
Forgejo section on top and a single-file Gitea constraint. It now
describes the two parts the theme ships: the theme stylesheets built
from the palette pipeline and styles/, and the template pack that
scripts/assembleForgejo.ts puts together from templates, components,
page CSS and public assets. It covers asset versions, the local preview
and the release archives, and the palette pipeline is kept, shorter.

CONTRIBUTING.md gains where new styles go (styles/ for Forgejo's own
markup, components/ for reusable UI, styles/pages for one page, public/
for an asset one template loads), the class prefixes and the z-index
scale from motion.css. Its directory table lists components, page CSS,
public and dev, and stale references now name component_assets.tmpl,
the sidebar toggle component, results.js and the select example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@whereareiam
whereareiam force-pushed the feat/template-drift-check branch from 6f68928 to c209a0e Compare October 28, 2026 18:28
@whereareiam
whereareiam force-pushed the docs/forgejo-architecture branch from f093fce to b82f91d Compare October 28, 2026 18:28
@whereareiam
whereareiam changed the base branch from feat/template-drift-check to dev October 28, 2026 18:28
@whereareiam
whereareiam enabled auto-merge (rebase) October 28, 2026 18:28
This was referenced Oct 28, 2026
Closed
Closed
Closed
@whereareiam
whereareiam merged commit 617b6bb into dev Oct 28, 2026
6 of 12 checks passed
@whereareiam
whereareiam deleted the docs/forgejo-architecture branch October 28, 2026 18:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

skip-changelog Left out of the release notes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@whereareiam