diff --git a/.github/workflows/web.yml b/.github/workflows/web.yml index 7675f19..33ebbba 100644 --- a/.github/workflows/web.yml +++ b/.github/workflows/web.yml @@ -1,7 +1,8 @@ # Ream's pipeline. Linux only, a few minutes a run, inside GitHub's free allowance. # pull request into dev check, then a preview deploy (.ream-bqb.pages.dev) with its link on the PR -# pull request into main check, and the version must be new (a release: see CONTRIBUTING.md) -# merge into main check, then production (ream.deityhub.com), the v tag, a GitHub Release and the +# pull request into main check; a new version is a release (see CONTRIBUTING.md), the same version as the last +# release is not (a docs-only change) and ships nothing +# merge into main check, then, only when the version is new, production (ream.deityhub.com), the v tag, a GitHub Release and the # Docker image (ghcr.io/deityhub/ream, docker.io/deityhub/ream) # A released version can be put back with the Deploy a version workflow (deploy-version.yml). # Plain pushes to other branches run nothing. `check` is the status the branch rules require @@ -26,6 +27,8 @@ jobs: check: runs-on: ubuntu-latest timeout-minutes: 20 + outputs: + release: ${{ steps.release.outputs.release }} steps: - uses: actions/checkout@v7 with: @@ -37,6 +40,8 @@ jobs: - name: The version is new (releases only) if: github.base_ref == 'main' || github.ref == 'refs/heads/main' run: node scripts/release.ts check + - id: release # false when v is already tagged: production and the tag are skipped + run: echo "release=$(node scripts/release.ts pending)" >> "$GITHUB_OUTPUT" - run: yarn install --immutable - run: yarn typecheck - run: yarn test @@ -106,7 +111,7 @@ jobs: gh pr comment ${{ github.event.pull_request.number }} --repo ${{ github.repository }} --body "$body" --edit-last --create-if-none production: - if: github.event_name == 'push' && github.ref == 'refs/heads/main' + if: github.event_name == 'push' && github.ref == 'refs/heads/main' && needs.check.outputs.release == 'true' needs: check runs-on: ubuntu-latest timeout-minutes: 10 diff --git a/AGENTS.md b/AGENTS.md index 44de923..995972f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -159,7 +159,7 @@ To add a tool: manifest, run, panel, three registry entries, its page text in `p - SEO (`seo.ts`, `seoHead.ts`, `seoPlugin.ts`, `ToolAbout.tsx`, `packages/tools/src/seo/`): the build (`seoPlugin`, after the bundle) writes one HTML file per route from the built `index.html` (`tool/merge-pdf/index.html`...): its own ``, description, canonical address, Open Graph and Twitter tags, JSON-LD (landing: `WebSite` + `WebApplication`; tools: `WebApplication` + `BreadcrumbList`; marked `data-seo`) and plain text inside `#root` (`main.seo`, styled in `index.css`) that the app replaces when it starts. It also writes `404.html` (needed: without it Cloudflare Pages treats the site as an SPA and answers every unknown address with 200) and `sitemap.xml` (indexable routes only: not the licence, notices or 404 pages). `pageSeo(route)` is the one source for all of it; `seoHead.applyHead` (lazy) keeps the head in step while moving around the app. A tool's words (`title` at most 60 characters ending in "| Ream", `description` 70 to 155, `intro`, three `points`, two or more `faq`) live in `packages/tools/src/seo/{pdf,convert,image}.ts` and also show under the tool (`ToolAbout`, lazy: four framed cells, shown only while no file is added). Write only what the tool really does and where it stops (no OCR, no certificate signatures, Office conversions are approximate). `SITE` (`https://ream.deityhub.com`) in `seo.ts` is every canonical address, also from a self-hosted copy. The social card is `apps/web/public/og.png`, made by `node scripts/og.ts`. - Tools home (`Home.tsx`, at most 1600 px wide) is drop-first: the `Dropzone` `bar` layout, and dropped files handed to a tool through `handoff.ts`, the same mechanism as "Use in another tool". - Docker: `Dockerfile` builds the site with Node (on the build machine's platform) and serves it with `nginxinc/nginx-unprivileged` (non-root, port 8080). Its NGINX site is generated from `apps/web/public/_headers` by `scripts/nginx-conf.ts`, so change headers there only. The image build skips the typecheck (tests are left out by `.dockerignore`; CI typechecks anyway). `check` builds and runs it and checks the page, the headers, `sw.js` not being cached, the manifest's type, a 404 and a non-root user; the release pushes amd64 and arm64 images to `ghcr.io/deityhub/ream` and, with `DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN` set, `docker.io/<user>/ream`, tagged with the version and `latest`. Containers can't start in this Mac's Docker; test a server inside a throwaway `docker build` (start it in a `RUN`, query it with curl) or rely on CI. -- Versions: the root `package.json` `version` (semver, starting at 0.1.0) is the release version. A pull request into `main` must raise it and have its `CHANGELOG.md` section: `yarn release patch|minor|major` (`scripts/release.ts prepare`) writes both, the section from the pull requests merged since the last tag (first-parent merges of `dev`, their titles and links; earlier releases skipped), and `node scripts/release.ts check` fails on a version already tagged or older or one without a section. The merge deploys production, tags `v<version>` and creates a GitHub Release whose notes are that section (`release.ts notes`). `.github/workflows/prepare-release.yml` (Actions → Prepare release) runs `prepare` on `dev` and opens the "Release v<version>" pull request into `dev`, as the `RELEASE_TOKEN` secret so `check` and the preview run on it. The version is in the footer (`__APP_VERSION__`, defined in `vite.config.ts`, declared in `version.d.ts`) and in the offline cache's name. `.github/workflows/deploy-version.yml` builds a released tag again and deploys it to production (rollback when the Cloudflare dashboard's can't). +- Versions: the root `package.json` `version` (semver, starting at 0.1.0) is the release version. A pull request into `main` that ships a change must raise it and have its `CHANGELOG.md` section (leaving the version as the last release's makes it a non-release, such as a docs-only change: `check` passes and the merge skips production, the tag and the image, through `release.ts pending`): `yarn release patch|minor|major` (`scripts/release.ts prepare`) writes both, the section from the pull requests merged since the last tag (first-parent merges of `dev`, their titles and links; earlier releases skipped), and `node scripts/release.ts check` fails on a version older than the latest tag or one without a section. The merge deploys production, tags `v<version>` and creates a GitHub Release whose notes are that section (`release.ts notes`). `.github/workflows/prepare-release.yml` (Actions → Prepare release) runs `prepare` on `dev` and opens the "Release v<version>" pull request into `dev`, as the `RELEASE_TOKEN` secret so `check` and the preview run on it. The version is in the footer (`__APP_VERSION__`, defined in `vite.config.ts`, declared in `version.d.ts`) and in the offline cache's name. `.github/workflows/deploy-version.yml` builds a released tag again and deploys it to production (rollback when the Cloudflare dashboard's can't). - Crawlers: `apps/web/public/robots.txt` allows search engines and blocks AI training crawlers only (AI search and assistant fetchers and link-preview bots stay allowed, on purpose); `crawlers.test.ts` pins both lists, so adding a bot to one list means changing the test too. `_headers` ends with host rules (`https://:project.pages.dev/*`) that make the `pages.dev` addresses `noindex`; `scripts/nginx-conf.ts` skips rules for a whole address. - Hosting: Cloudflare Pages, deployed by `.github/workflows/web.yml`: a pull request into `dev` runs `check` and gets a preview (its link is commented on the PR), a pull request into `main` runs `check`, a merge into `main` runs `check` and deploys production. Plain pushes run nothing. `check` is the status `.github/rulesets/protect-dev-main.json` requires (import it under Settings → Rules once the repo is public: rulesets aren't free on private repos). `apps/web/public/_headers` holds the security headers: the CSP allows only the site's own files, plus `api.fontsource.org` and `cdn.jsdelivr.net` in `connect-src` for Download free fonts, and no inline scripts or styles (`style-src 'self'`: React's `style` props are fine, `<style>` elements and `style="..."` strings are not). A new network host or inline style needs the policy changed, and the user asked first (the network rule above). Check with `wrangler pages dev` and a `securitypolicyviolation` listener. - PWA: `manifest.webmanifest` and `icons/` in `apps/web/public` (PNGs from `apps/web/icons/icon.svg` by `node scripts/icons.ts`; square, full bleed, the mark inside the maskable safe zone). `apps/web/sw.js` is plain JS, outside `src`, registered as `/sw.js` with scope `/`: the `serviceWorker` plugin in `vite.config.ts` writes it into `dist` after the build with every file's name (minus `.woff` fallbacks, the non-Latin Office fonts, which it keeps when first used, and what only crawlers or the 404 need) and a version hashed from their contents. Each page is kept under its folder's address (`./`, `tool/merge-pdf/`) because Pages redirects `.../index.html` to the folder. A navigation that fails offline gets its own kept page, else `./` (the app routes by address). Cache lookups use `ignoreVary` (a host sending `Vary: Origin` made every module script miss its kept copy). Navigations are network first, everything else cache first. A new version waits until the user clicks Reload in `UpdateBar.tsx` (`pwa.ts` posts `switch`; the page reloads on `controllerchange` only after that, since the first worker's `clients.claim` changes the controller too). `pwa.ts` also keeps the `beforeinstallprompt` event for the landing page's Install Ream button. The worker is registered in production builds only: `yarn dev` has none. To test offline for real, serve the build with `wrangler pages dev`, let the worker fill its cache, then stop the server (CDP's offline emulation doesn't reach the worker's own requests). diff --git a/docs/deploy.md b/docs/deploy.md index 583fc49..a53872a 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -38,7 +38,7 @@ The release version is the root `package.json` `version` (semantic versioning: ` 1. Work reaches `dev` through pull requests; each gets a preview. 2. To release, run Actions → **Prepare release** → Run workflow and pick `patch`, `minor` or `major`. It does the step below on a copy of `dev` and opens the pull request "Release v<version>" into `dev`; edit the changelog there if needed and merge it. It needs the `RELEASE_TOKEN` secret to get `check` and a preview on that pull request (see below); without it the pull request opens with no checks. Or do it by hand: branch from `dev` (`release/v<version>`) and run `yarn release patch` (fixes), `minor` (new tools or features) or `major` (anything that breaks how people use Ream). It raises the version (counted from the latest tag: `git fetch --tags` first) and adds a section to `CHANGELOG.md` listing the pull requests merged since the last release, each with its link. Edit the section into plain words if you like, commit `Release v<version>`, and merge it into `dev` through a pull request. -3. Open the pull request from `dev` into `main`. `check` fails while the version is one already released or older, or `CHANGELOG.md` has no section for it (`node scripts/release.ts check`). +3. Open the pull request from `dev` into `main`. A version that is already released means this is not a release (a docs-only change): `check` passes and the merge deploys nothing, tags nothing and builds no image. Otherwise `check` fails while the version is older than the latest release, or `CHANGELOG.md` has no section for it (`node scripts/release.ts check`). 4. Merging it deploys production with the version in Cloudflare's deployment message, tags `v<version>`, creates a GitHub Release whose notes are the version's `CHANGELOG.md` section, and publishes the Docker image. `RELEASE_TOKEN` is a fine-grained personal access token (GitHub → Settings → Developer settings → Fine-grained tokens): repository access only `Deityhub/ream`, permissions **Contents** and **Pull requests** read and write. Save it as a repository secret (Settings → Secrets and variables → Actions). It expires on the date you choose; make a new one when it does. GitHub doesn't run workflows for pull requests its own token opens, which is why the workflow uses yours. Like any manual workflow, **Prepare release** shows in the Actions tab only once it is on `main`. diff --git a/scripts/release.ts b/scripts/release.ts index 058e58b..6ca7eda 100644 --- a/scripts/release.ts +++ b/scripts/release.ts @@ -1,6 +1,7 @@ // The release version (the root package.json's "version", tagged v<version> when it reaches main) and its CHANGELOG.md section. // node scripts/release.ts prepare patch|minor|major raise the version and write its changelog section (yarn release ...) -// node scripts/release.ts check fail unless the version is new, higher than every released one, and in the changelog (PRs into main) +// node scripts/release.ts check PRs into main: pass when the version is already released (nothing ships, e.g. a docs-only change); otherwise it must be higher than every released one and in the changelog +// node scripts/release.ts pending print true when v<version> isn't tagged yet (a merge into main releases), else false // node scripts/release.ts version print it (the release job's tag and deploy message) // node scripts/release.ts notes print its changelog section (the GitHub Release's text) import { execFileSync } from 'node:child_process' @@ -30,6 +31,7 @@ const latest = () => .filter((v): v is number[] => !!v) .sort(newer) .at(-1) +const released = () => git('tag', '--list', `v${version}`).trim() !== '' const changelog = () => (existsSync(logPath) ? readFileSync(logPath, 'utf8') : '') /** the text under "## <v>" up to the next section, or null when there is none */ const section = (v: string) => { @@ -57,7 +59,12 @@ function entries(from: string | null): string[] { const mode = process.argv[2] if (mode === 'version') console.log(version) else if (mode === 'notes') console.log(section(version) ?? fail(`CHANGELOG.md has no section for ${version}.`)) +else if (mode === 'pending') console.log(!released()) else if (mode === 'check') { + if (released()) { + console.log(`Version ${version} is already released: this change is not a release, so nothing will be deployed.`) + process.exit(0) + } const last = latest() if (last && newer(own, last) <= 0) fail(`Version ${version} is already released or older than the latest release (${last.join('.')}). Raise it in this pull request: yarn release patch, minor or major.`) if (!section(version)) fail(`CHANGELOG.md has no section for ${version}, or it is empty. yarn release patch, minor or major writes one.`)