Skip to content

Fork dev-env setup and containerization#1

Draft
tiffehr wants to merge 57 commits into
mainfrom
staging
Draft

Fork dev-env setup and containerization#1
tiffehr wants to merge 57 commits into
mainfrom
staging

Conversation

@tiffehr

@tiffehr tiffehr commented Jun 29, 2026

Copy link
Copy Markdown

This pull request adds a self-contained development environment for Ghost theme development using VS Code Dev Containers and Docker Compose.

The setup enables rapid local development, testing, and validation of the theme with both development (SQLite) and production-like (MySQL) Ghost instances, and includes extensive documentation, recommended extensions and optimized Docker configuration.

Work

  • Added a .devcontainer setup and a multi-service Docker Compose configuration for both development and production-like Ghost instances, to help provide seamless local development, testing and integration
  • Introduced a .dockerignore file to exclude unnecessary files and an .editorconfig file to enforce consistent code style across editors for all supported file types
  • Added GitHub Actions workflows:
    • test.yml for automated testing on PRs and pushes.
    • deploy-theme.yaml for automated version bumping, building, testing, releasing and deploying the theme to Ghost, with rollback instructions
    • rollback-theme.yaml to allow manual rollback of theme releases and optional deletion of failed releases
  • Introduced a Dependabot configuration to automate dependency updates, with separate strategies for fork-specific and upstream-managed dependencies
  • Added global Copilot instructions and a PR template to enforce clear, consistent pull request formatting and adherence to project conventions
  • Updated .gitattributes to exclude certain files from export, streamlining distribution

renovate Bot and others added 26 commits May 19, 2026 12:16
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
theme-translations was bumped to 0.0.21 (it/tr/vi strings) and cssnano to
v8 (#507) without rebuilding themes, so built output drifted from source.

- Propagates Italian, Turkish and Vietnamese locale updates into all 16
  themes (they currently ship empty strings for these)
- Regenerates screen.css under cssnano v8 — declaration reordering only,
  no functional or visual change
- gscan: all themes pass (Ghost 6.x compatible)
Standardises the Themes monorepo on pnpm, matching the standalone theme
repos (Casper, Ease-Help, Edition-Changelog, ...) that already migrated, so
contributors and CI agree on a single pinned package manager and lockfile
format. The previous setup relied on unpinned yarn classic.

- Pin pnpm via the root `packageManager` field so corepack and CI agree on
  a version, and mirror the pin into every theme package so the
  subtree-pushed standalone repos (e.g. `TryGhost/Alto`) are migrated too
- Declare the workspace in `pnpm-workspace.yaml` with
  `linkWorkspacePackages: true` to mirror yarn workspaces behaviour:
  `@tryghost/shared-theme-assets@2.7.1` keeps resolving to the local
  `packages/_shared`, while `@tryghost/theme-translations@^0.0.9` keeps
  installing from the registry (verified identical to the yarn layout)
- Classify the only flagged build script: `dtrace-provider` (optional
  bunyan bindings via gscan) is denied since themes never need it built
- Add `glob` as an explicit root devDependency: the root gulpfile requires
  it but only resolved it through yarn hoisting, which pnpm's isolated
  `node_modules` correctly refuses
- Swap all 17 workflows to digest-pinned `pnpm/action-setup` +
  `setup-node` with pnpm store caching and `--frozen-lockfile` installs;
  job structure, gating, and digests are otherwise untouched
- Exclude `pnpm-debug.log`/`pnpm-lock.yaml` instead of `yarn-error.log`
  in every zip task, update README/AGENTS docs, and regenerate the
  lockfile as `pnpm-lock.yaml` (yarn.lock dropped)

Remove the unused `concurrently` devDependency while here — nothing in
the repo references it and it only generated pointless Renovate bumps.
Under yarn, `@tryghost/shared-theme-assets` was hoisted to the repo root,
so the committed source maps referenced shared CSS four directories up
(`../../../../node_modules/...`). pnpm links the package into each
theme's own `node_modules`, so rebuilt maps now point two directories up
(`../../node_modules/...`) — without committing this relocation, every
`pnpm build` dirties 16 source maps in the working tree. The new paths
also resolve correctly in the standalone subtree repos, which have no
root-level `node_modules`; the old hoisted paths were broken there.

The compiled CSS itself is byte-identical; only the maps change. Dope's
`main.min.js` is content-identical too — gulp just normalises away a
stray executable bit on the committed file.
The root `pnpm-workspace.yaml` carries the `dtrace-provider` build-script
denial, but it does not propagate to the standalone repos that CI
subtree-pushes from `packages/<theme>` (e.g. `TryGhost/Alto`). Those
repos now pin pnpm via `packageManager`, so without a policy of their
own, `pnpm install` in a standalone checkout exits non-zero with
ERR_PNPM_IGNORED_BUILDS (verified in a clean simulation).

Ship a settings-only `pnpm-workspace.yaml` inside each theme so the
standalone repos install cleanly. pnpm ignores the nested files when
installing from the monorepo root — verified that all 19 workspace
projects still resolve and the lockfile is unchanged.
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Added stable `All tests pass` gates to the per-theme monorepo workflows and package-level `AGENTS.md` guidance so standalone theme repositories keep agent instructions after sync. Added missing README files for Episode and Taste using the existing official theme README pattern, and documented how package changes flow through the existing root workflows, deploy, and subtree sync.
Added subtree-persisted workflow files under each theme package so standalone mirror repositories run `pnpm zip` and fatal `gscan` before Renovate or direct PRs can be considered passing. Documented that these package-local workflows are for mirror repositories, while monorepo package validation remains owned by the existing root workflows.
The broad theme zip tasks could include the agent guidance files added to theme roots. Added explicit exclusions for AGENTS.md and CLAUDE.md in the monorepo zip task and each package-local zipper so generated theme archives stay limited to runtime theme content.
Added package-level `.gitattributes` files so subtree-published theme repositories omit agent docs and workspace metadata from GitHub-generated source archives. This keeps the files available in source checkouts while preventing `archive/main.zip` downloads from including `AGENTS.md`, `CLAUDE.md`, or `pnpm-workspace.yaml`.
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
@tiffehr tiffehr self-assigned this Jun 29, 2026
@tiffehr tiffehr added documentation Improvements or additions to documentation enhancement New feature or request labels Jun 29, 2026
tiffehr and others added 17 commits June 29, 2026 06:11
add Node.js version specification to 24, even though the root Action is pinned to 20 for now

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <copilot@github.com>
- devcontainer definitions for VS code and sibling editors
- Ghost frontend and admin support
- Dockerized Ghost instance and MySQL db
- commands to run it all in the container
- repo upgrades for package.json (about to change, as we pull in the root theme rebase)
- editor setup and behavior (on save)
- code-pattern checks
- agentic instructions for AI-assisted development and troubleshooting
-  documentation about all this and more
- minimal conflicts with the parent theme, even though this is much souped-up
- refactored content or work into other tools, within the relationship between this forked theme and the parent repo
- also, CoPilot/Claude LOVES creating new markdown files for no actual reader
- Added sync/README.md for upstream sync procedures and conflict resolution
- Ensured all references to npm commands are replaced with equivalent pnpm commands
- Enhanced clarity on protected files and conflict resolution strategies during upstream sync
tiffehr added 12 commits June 30, 2026 18:02
- Created candidate profile template with campaign finance summary, election history, and contributions
- Created office profile template displaying office details and historical finance data
- Created election year template showcasing election summary and race details
- Introduced campin explorer template for overall campaign finance data analysis
- Updated default layout to include data loader script for dynamic data fetching
- Enhanced gulpfile to support data loader build process and mock data management
- Added routes for new templates in routes.yaml
- Created mock data package for development, simulating the structure of the production data package -- ready to adopt for a in-theme testing rig separate from whatever exists in the `data` sibling repo
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants