Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions .github/workflows/prepare-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Start a release from GitHub (Actions → Prepare release → Run workflow): raises the version on a copy of dev, writes
# its CHANGELOG.md section (yarn release), and opens the pull request "Release v<version>" into dev. Review and edit the
# changelog there, merge it, then open dev → main as usual.
# RELEASE_TOKEN (a fine-grained token: this repo, Contents and Pull requests read and write) opens the pull request as
# you, so `check` and the preview run on it; GitHub doesn't start workflows for pull requests its own token opens.
name: Prepare release

on:
workflow_dispatch:
inputs:
kind:
description: 'patch (fixes), minor (new tools or features) or major (breaks how people use Ream)'
type: choice
options: [patch, minor, major]
default: minor

permissions:
contents: write
pull-requests: write

concurrency: prepare-release

jobs:
prepare:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v7
with:
ref: dev
fetch-depth: 0 # the tags and history the changelog is made from
token: ${{ secrets.RELEASE_TOKEN || github.token }}
- uses: actions/setup-node@v7
with:
node-version: 22 # scripts/release.ts is TypeScript, run directly; it needs only git
- name: Raise the version and write the changelog
id: release
run: |
node scripts/release.ts prepare "${{ inputs.kind }}"
echo "version=$(node scripts/release.ts version)" >> "$GITHUB_OUTPUT"
- name: Open the pull request into dev
env:
GH_TOKEN: ${{ secrets.RELEASE_TOKEN || github.token }}
VERSION: ${{ steps.release.outputs.version }}
run: |
branch="release/v$VERSION"
if git ls-remote --exit-code --heads origin "$branch" >/dev/null; then
echo "::error::$branch already exists: merge or delete its pull request first."
exit 1
fi
git config user.name 'github-actions[bot]'
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
git switch -c "$branch"
git add package.json CHANGELOG.md
git commit -m "Release v$VERSION"
git push origin "$branch"
{
echo "Raises the version to $VERSION and adds its changelog section. Edit \`CHANGELOG.md\` here if the wording needs it; after merging, open the pull request from \`dev\` into \`main\` to release."
echo
node scripts/release.ts notes
} > body.md
gh pr create --base dev --head "$branch" --title "Release v$VERSION" --body-file body.md
6 changes: 4 additions & 2 deletions .github/workflows/web.yml
Original file line number Diff line number Diff line change
Expand Up @@ -127,10 +127,12 @@ jobs:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
command: pages deploy dist --project-name ream --branch main --commit-hash "${{ github.sha }}" --commit-message "v${{ steps.version.outputs.version }}"
- name: Tag the release and write its notes (the pull requests merged since the last one)
- name: Tag the release, with its CHANGELOG.md section as the notes
env:
GH_TOKEN: ${{ github.token }}
run: gh release create "v${{ steps.version.outputs.version }}" --repo "${{ github.repository }}" --target "${{ github.sha }}" --title "v${{ steps.version.outputs.version }}" --generate-notes
run: |
node repo/scripts/release.ts notes > notes.md
gh release create "v${{ steps.version.outputs.version }}" --repo "${{ github.repository }}" --target "${{ github.sha }}" --title "v${{ steps.version.outputs.version }}" --notes-file notes.md
# the image for self-hosting: Intel/AMD and ARM, tagged with the version and latest. The site is built once, on
# the runner's own platform; each platform's image only copies the files, so no emulation is needed.
- uses: docker/setup-buildx-action@v4
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ To add a tool: manifest, run, panel, three registry entries, and tests. Reuse th
- Routes (`App.tsx`, hash based): `#/tool/<id>` the tool page, `#/tools`, `#/tools/pdf` and `#/tools/image` the tools home for a category (`Home.tsx`, `filterHref` in `TopBar.tsx`), `#/licence` and `#/notices` (`Legal.tsx`: the repo's `LICENSE` and `THIRD-PARTY-NOTICES.md`, imported `?raw` when the page opens) and `#/` (`Landing.tsx`); any other hash shows the landing page. The web-only pages share `Marketing.tsx` (nav, footer, `primary`/`secondary` link styles); app pages render `TopBar` (logo on the left; search and theme on the right; 1600 px like the pages) and `Breadcrumb` under it (All tools, the category, the tool; every level a link). The breadcrumb replaces visible headings on the tools home and tool pages (the `h1` is `sr-only`); on All tools the PDF tools and Image tools section titles link to their category. `focus` in `TopBar.tsx` is the shared focus ring.
- 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 (`yarn version patch|minor|major`; `node scripts/release.ts check` fails on a version already tagged or older); the merge deploys production, tags `v<version>` and creates a GitHub Release with generated notes. 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` 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).
- 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`: the `serviceWorker` plugin in `vite.config.ts` writes it into `dist` after the build with every file's name (minus `.woff` fallbacks and the non-Latin Office fonts, which it keeps when first used) and a version hashed from their contents. The page is kept as `./` because Pages redirects `index.html` to `/`. 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).

Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Changelog

What changed in each release of Ream. `yarn release patch|minor|major` writes a section from the pull requests merged since the last release; edit it in the release pull request.

## 0.2.0 (2026-10-27)

- Faster tool processing ([#7](https://github.com/Deityhub/ream/pull/7))
- A changelog for each release, written by `yarn release` or the Prepare release workflow, and used as the release notes

## 0.1.0 (2026-10-27)

- The first release: Ream as a web app at ream.deityhub.com that installs as a PWA and works offline, with 37 tools for PDFs, images and Office files that run on your device.
- Docker image on GitHub Container Registry and Docker Hub, MIT licence and third-party notices.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Add tests with your change: engines and tools are tested in plain Node, and a to
## Branches and releases

- Branch from `dev` and open your pull request into `dev`. It runs `check` and gets a preview deploy, linked in a comment.
- A release is a pull request from `dev` into `main` that raises the version with `yarn version patch|minor|major`. Merging it deploys ream.deityhub.com, tags the version and publishes the release notes and Docker image. See [docs/deploy.md](docs/deploy.md).
- A release is a pull request from `dev` into `main` that raises the version and adds its `CHANGELOG.md` section, both written by `yarn release patch|minor|major`. Merging it deploys ream.deityhub.com, tags the version and publishes the release notes and Docker image. See [docs/deploy.md](docs/deploy.md).

## Ground rules

Expand Down
7 changes: 5 additions & 2 deletions docs/deploy.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,11 @@ Ream is a progressive web app. `apps/web/public/manifest.webmanifest` and the ic
The release version is the root `package.json` `version` (semantic versioning: `major.minor.patch`).

1. Work reaches `dev` through pull requests; each gets a preview.
2. A release is a pull request from `dev` into `main` that raises the version: `yarn version patch` (fixes), `minor` (new tools or features) or `major` (anything that breaks how people use Ream). `check` fails while the version is one already released or older (`node scripts/release.ts check`).
3. Merging it deploys production with the version in Cloudflare's deployment message, tags `v<version>`, creates a GitHub Release whose notes list the pull requests since the last one, and publishes the Docker image.
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`).
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`.

The footer shows the version, so a bug report can say which one it was.

Expand Down
5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "ream",
"version": "0.1.0",
"version": "0.2.0",
"private": true,
"license": "MIT",
"type": "module",
Expand All @@ -14,7 +14,8 @@
"build": "yarn workspace @ream/web build",
"test": "vitest run",
"typecheck": "tsc -p tsconfig.json",
"pdf": "node scripts/pdf.ts"
"pdf": "node scripts/pdf.ts",
"release": "node scripts/release.ts prepare"
},
"devDependencies": {
"@types/node": "^26.6.5",
Expand Down
Loading
Loading