From 3a2fae1ac584900c01ec6c23af4b6c398b14428a Mon Sep 17 00:00:00 2001 From: Hannah Wolfe Date: Sat, 15 Aug 2026 16:35:34 +0100 Subject: [PATCH] Updated public app release documentation (#29986) Brings the public-app package READMEs up to date and documents how these apps are released. --- apps/admin-toolbar/README.md | 21 ++++++++-- apps/admin-toolbar/package.json | 1 + apps/announcement-bar/README.md | 29 ++++++++------ apps/announcement-bar/package.json | 1 + apps/comments-ui/README.md | 28 +++++++------ apps/comments-ui/package.json | 1 + apps/portal/README.md | 64 +++++++++++++++++------------- apps/portal/package.json | 1 + apps/signup-form/README.md | 40 ++++++++++--------- apps/signup-form/package.json | 1 + apps/sodo-search/README.md | 28 +++++++------ apps/sodo-search/package.json | 1 + 12 files changed, 128 insertions(+), 88 deletions(-) diff --git a/apps/admin-toolbar/README.md b/apps/admin-toolbar/README.md index 81daa495c7c..788bb5addc1 100644 --- a/apps/admin-toolbar/README.md +++ b/apps/admin-toolbar/README.md @@ -1,9 +1,7 @@ # Admin Toolbar -Frontend staff toolbar for Ghost sites. Uses Preact (~3KB) instead of React -(~40KB) since this is a lightweight public-facing widget that only needs basic -rendering and hooks — the same rationale applies to any future small public -scripts where bundle size matters more than ecosystem compatibility. +Frontend staff toolbar for Ghost sites. It uses Preact to keep the public-facing +bundle small while providing the rendering and hooks the toolbar needs. ## Development @@ -26,6 +24,21 @@ that URL to `/ghost/assets/admin-toolbar/admin-toolbar.min.js`, which the dev gateway serves straight off disk from this package's `umd/` directory — so the watcher's output is picked up on the next request. +## Release + +Patch releases are automatic. When Admin Toolbar changes on `main`, CI publishes +the next patch version to npm and clears the jsDelivr cache. Sites using that +major/minor line receive the patch without a Ghost release. + +For an intentional minor or major release: + +1. From a clean branch, run `pnpm ship` and select a minor or major version +2. Merge the release commit to `main` +3. Wait for a public Ghost release to ship the new default version line + +`pnpm ship` updates both the package version and Ghost's default Admin Toolbar +version. + # Copyright & License Copyright (c) 2013-2026 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/Ghost/blob/main/LICENSE). diff --git a/apps/admin-toolbar/package.json b/apps/admin-toolbar/package.json index 7417932f95b..a0209443e15 100644 --- a/apps/admin-toolbar/package.json +++ b/apps/admin-toolbar/package.json @@ -2,6 +2,7 @@ "name": "@tryghost/admin-toolbar", "type": "module", "version": "0.1.11", + "description": "Frontend staff toolbar for Ghost sites", "license": "MIT", "repository": "https://github.com/TryGhost/Ghost", "author": "Ghost Foundation", diff --git a/apps/announcement-bar/README.md b/apps/announcement-bar/README.md index 8567ff7a3e5..19f22e32861 100644 --- a/apps/announcement-bar/README.md +++ b/apps/announcement-bar/README.md @@ -1,5 +1,7 @@ # Announcement Bar +Announcement banner injected into Ghost sites. + ## Development ### Pre-requisites @@ -14,25 +16,28 @@ Start Ghost with the public-app watchers enabled: pnpm dev:public ``` -This starts the standard development environment and the Announcement Bar watcher. To run only the package's build watcher, use `pnpm dev` from this directory. - -## Release +This starts the standard development environment and the Announcement Bar +watcher. To work on this package by itself, run these commands from this +directory: -A patch release can be rolled out instantly in production, whereas a minor/major release requires the Ghost monorepo to be updated and released. -In either case, you need sufficient permissions to release `@tryghost` packages on NPM. +```bash +pnpm build # one-off build +pnpm dev # watch and rebuild the UMD bundle +pnpm test # run unit tests once +pnpm lint # lint source and tests +``` -### Patch release +## Release -1. Run `pnpm ship` and select a patch version when prompted -2. Merge the release commit to `main` +Patch releases are automatic. When Announcement Bar changes on `main`, CI publishes the next patch version to npm and clears the jsDelivr cache. Sites using that major/minor line receive the patch without a Ghost release. -### Minor / major release +For an intentional minor or major release: -1. Run `pnpm ship` and select a minor or major version when prompted +1. From a clean branch, run `pnpm ship` and select a minor or major version 2. Merge the release commit to `main` -3. Wait until a new version of Ghost is released +3. Wait for a public Ghost release to ship the new default version line -To use the new version of Announcement Bar in Ghost, update the version in Ghost core's default configuration (currently at `core/shared/config/default.json`) +`pnpm ship` updates both the package version and Ghost's default Announcement Bar version. # Copyright & License diff --git a/apps/announcement-bar/package.json b/apps/announcement-bar/package.json index 3633c400780..d341c9ef7e0 100644 --- a/apps/announcement-bar/package.json +++ b/apps/announcement-bar/package.json @@ -2,6 +2,7 @@ "name": "@tryghost/announcement-bar", "type": "module", "version": "1.1.28", + "description": "Announcement banner for Ghost sites", "license": "MIT", "repository": "https://github.com/TryGhost/Ghost", "author": "Ghost Foundation", diff --git a/apps/comments-ui/README.md b/apps/comments-ui/README.md index d4c19b62a86..428a4f7195b 100644 --- a/apps/comments-ui/README.md +++ b/apps/comments-ui/README.md @@ -16,26 +16,28 @@ Start Ghost with the public-app watchers enabled: pnpm dev:public ``` -This starts the standard development environment and the Comments UI watcher. To run only the package's build watcher, use `pnpm dev` from this directory. +This starts the standard development environment and the Comments UI watcher. +To work on this package by itself, run these commands from this directory: -## Release - -A patch release can be rolled out instantly in production, whereas a minor/major release requires the Ghost monorepo to be updated and released. In either case, you need sufficient permissions to release `@tryghost` packages on NPM. +```bash +pnpm build # one-off build +pnpm dev # watch and rebuild the UMD bundle +pnpm test # run type checks and unit tests +pnpm test:acceptance # run browser acceptance tests +pnpm lint # lint code and check types +``` -### Patch release +## Release -1. Run `pnpm ship` and select a patch version when prompted -2. Merge the release commit to `main` +Patch releases are automatic. When Comments changes on `main`, CI publishes the next patch version to npm and clears the jsDelivr cache. Sites using that major/minor line receive the patch without a Ghost release. -### Minor / major release +For an intentional minor or major release: -1. Run `pnpm ship` and select a minor or major version when prompted +1. From a clean branch, run `pnpm ship` and select a minor or major version 2. Merge the release commit to `main` -3. Wait until a new version of Ghost is released +3. Wait for a public Ghost release to ship the new default version line -### JsDelivr cache -If the CI doesn't clear JsDelivr cache to get the new version out instantly, you may want to do it yourself manually ([docs](https://www.notion.so/ghost/How-to-clear-jsDelivr-CDN-cache-2930bdbac02946eca07ac23ab3199bfa?pvs=4)). Typically, you'll need to open `https://purge.jsdelivr.net/ghost/comments-ui@~${COMMENTS_UI_VERSION}/umd/comments-ui.min.js` and -`https://purge.jsdelivr.net/ghost/comments-ui@~${COMMENTS_UI_VERSION}/umd/main.css` in your browser, where `COMMENTS_UI_VERSION` is the latest minor version in `ghost/core/core/shared/config/defaults.json` ([code](https://github.com/TryGhost/Ghost/blob/0aef3d3beeebcd79a4bfd3ad27e0ac67554b5744/ghost/core/core/shared/config/defaults.json#L198)) +`pnpm ship` updates both the package version and Ghost's default Comments version. # Copyright & License diff --git a/apps/comments-ui/package.json b/apps/comments-ui/package.json index 31bdc724c2c..71771804ddd 100644 --- a/apps/comments-ui/package.json +++ b/apps/comments-ui/package.json @@ -2,6 +2,7 @@ "name": "@tryghost/comments-ui", "type": "module", "version": "1.6.0", + "description": "Comments interface for Ghost posts", "license": "MIT", "repository": "https://github.com/TryGhost/Ghost", "author": "Ghost Foundation", diff --git a/apps/portal/README.md b/apps/portal/README.md index 828bf1d890a..24da81967d6 100644 --- a/apps/portal/README.md +++ b/apps/portal/README.md @@ -6,9 +6,11 @@ ## Usage -Ghost automatically injects Portal script on all sites running Ghost 4 or higher. +Ghost automatically injects the Portal script on all sites running Ghost 4 or +higher. -Alternatively, Portal can be enabled on non-ghost pages directly by inserting the below script on the page. +Alternatively, Portal can be enabled on pages outside Ghost by adding this +script: ```html @@ -20,7 +22,10 @@ The `data-ghost` attribute expects the URL for your Ghost site, which is the onl By default, the script adds a default floating trigger button on the bottom right of your page which is used to trigger the popup on screen. -Its possible to add custom trigger button of your own by adding data attribute `data-portal` to any HTML tag on page, and also specify a specific [page](https://github.com/TryGhost/Ghost/blob/main/ghost/portal/src/pages.js#L13-L22) to open from it by using it as `data-portal=signup`. +You can add a custom trigger by adding the `data-portal` attribute to any HTML +element. Set its value to choose a specific +[Portal page](https://github.com/TryGhost/Ghost/blob/main/apps/portal/src/pages.js), +for example `data-portal="signup"`. Share modal can be opened with `data-portal="share"` (or `#/share`). @@ -38,62 +43,65 @@ Troubleshooting missing preview metadata: 1. Verify the template includes `{{ghost_head}}`. 2. Verify rendered HTML contains canonical + OG/Twitter tags. -The script also adds custom class names to this element for open and close state of popup - `gh-portal-open` and `gh-portal-close`, allowing devs to update its UI based on popup state. +The script adds `gh-portal-open` and `gh-portal-close` classes to custom triggers +to reflect the popup state. -Refer the [docs](https://ghost.org/help/setup-members/#customize-portal-settings) to read about ways in which Portal can be customized for your site. +See the [Portal settings documentation](https://ghost.org/help/setup-members/#customize-portal-settings) +for ways to customize Portal for your site. ## Develop -Portal runs automatically when using Ghost's development command from the monorepo root: -``` +Portal runs automatically with Ghost's standard development command from the +monorepo root: + +```bash pnpm dev ``` -This starts all frontend apps (including Portal.) Portal is served via the dev gateway at `http://localhost:2368/ghost/assets/portal/portal.min.js` and is loaded into theme pages on the dev site. +This starts Ghost, Admin, and Portal. Portal is served through the development +gateway at `http://localhost:2368/ghost/assets/portal/portal.min.js` and loaded +into theme pages on the development site. Use `pnpm dev:public` when changing +Portal alongside the other public apps. ## Build -To create a production minified bundle in `umd/portal.min.js`: -``` +From this directory, create a production minified bundle in +`umd/portal.min.js` with: + +```bash pnpm build ``` ## Test -To run tests in watch mode: -``` +From this directory, run unit tests once or in watch mode with: + +```bash pnpm test +pnpm test:watch ``` ### Ghost e2e tests -Portal is primarily tested via Ghost's e2e Playwright tests in the `e2e/` directory. Run them from the monorepo root: -``` +Portal is primarily tested through Ghost's Playwright tests in the `e2e/` +directory. Run them from the monorepo root: +```bash pnpm test:e2e ``` ## Release -A patch release can be rolled out instantly in production, whereas a minor/major release requires the Ghost monorepo to be updated and released. In either case, you need sufficient permissions to release `@tryghost` packages on NPM. +Patch releases are automatic. When Portal changes on `main`, CI publishes the next patch version to npm and clears the jsDelivr cache. Sites using that major/minor line receive the patch without a Ghost release. If you're releasing new code that should not immediately go live _always_ use a minor or major version when publishing. -In order to have Ghost's e2e tests run against the new code on CI or to test the new code in staging, you need to publish to npm following the Minor / major release process below. - -### Patch release - -1. Run `pnpm ship` and select a patch version when prompted -2. Merge the release commit to `main` - -### Minor / major release +For an intentional minor or major release: -1. Run `pnpm ship` and select a minor or major version when prompted +1. From a clean branch, run `pnpm ship` and select a minor or major version 2. Merge the release commit to `main` -3. Wait until a new version of Ghost is released +3. Wait for a public Ghost release to ship the new default version line -### JsDelivr cache -If the CI doesn't clear JsDelivr cache to get the new version out instantly, you may want to do it yourself manually ([docs](https://www.notion.so/ghost/How-to-clear-jsDelivr-CDN-cache-2930bdbac02946eca07ac23ab3199bfa?pvs=4)). Typically, you'll need to open `https://purge.jsdelivr.net/ghost/portal@~${PORTAL_VERSION}/umd/portal.min.js` and -`https://purge.jsdelivr.net/ghost/portal@~${PORTAL_VERSION}/umd/main.css` in your browser, where `PORTAL_VERSION` is the latest minor version in `ghost/core/core/shared/config/defaults.json` ([code](https://github.com/TryGhost/Ghost/blob/0aef3d3beeebcd79a4bfd3ad27e0ac67554b5744/ghost/core/core/shared/config/defaults.json#L185)) +`pnpm ship` updates both the package version and Ghost's default Portal version. # Copyright & License diff --git a/apps/portal/package.json b/apps/portal/package.json index 3f18c0e1041..16e4f487aaa 100644 --- a/apps/portal/package.json +++ b/apps/portal/package.json @@ -2,6 +2,7 @@ "name": "@tryghost/portal", "type": "module", "version": "2.69.16", + "description": "Drop-in membership interface for Ghost sites", "license": "MIT", "repository": "https://github.com/TryGhost/Ghost", "author": "Ghost Foundation", diff --git a/apps/signup-form/README.md b/apps/signup-form/README.md index 1ad1b85455a..2433c04a5d4 100644 --- a/apps/signup-form/README.md +++ b/apps/signup-form/README.md @@ -20,41 +20,43 @@ This starts the standard development environment and the Signup Form watcher. ### Running the standalone demo page -Run `pnpm dev:standalone` (in this package folder) to start the standalone development server with HMR for testing/developing the form in isolation. -- This serves the demo page at http://localhost:6173 +Run `pnpm dev:standalone` from this directory to start the standalone +development server with HMR. It serves the demo page at +. `pnpm dev` on its own (in this package folder) only builds `umd/signup-form.min.js` and watches for changes — it does not bind a port. The UMD is served by Caddy at http://localhost:2368/ghost/assets/signup-form/signup-form.min.js when you run `pnpm dev:public` from the monorepo root. ### Using the UMD build during development -Vite by default only supports HRM with an ESM output. But when loading a script on a site as a ESM module (`