ci: add release-please and pull request title check

Author: abraham

.github/CONTRIBUTING.md

@@ -58,6 +58,6 @@ This fixes #20 by removing styles that leaked which would cause the page to turn
 
 3.  **At least one test for each bug fixed or feature added** as part of the pull request. Pull requests that fix bugs or add features without accompanying tests will not be considered.
 
-If a proposed change contains multiple commits, please [squash commits](https://www.google.com/url?q=http://blog.steveklabnik.com/posts/2012-11-08-how-to-squash-commits-in-a-github-pull-request) to as few as is necessary to succinctly express the change. A Polymer author can help you squash commits, so don’t be afraid to ask us if you need help with that!
+4.  **A [Conventional Commits](https://www.conventionalcommits.org/) title**, for example `fix(web): show session times in the event time zone`. Pull requests are squash merged and the title becomes the release note, so mark breaking changes with `!` and explain them in the description. See [docs/releases.md](../docs/releases.md#pull-requests).
 
 _Copied from [Polymer Elements contributing guide](https://github.com/PolymerElements/ContributionGuide)_

.github/dependabot.yml

@@ -4,6 +4,8 @@ updates:
     directory: '/'
     schedule:
       interval: monthly
+    commit-message:
+      prefix: ci
   - package-ecosystem: npm
     directories:
       - '/'
@@ -13,6 +15,9 @@ updates:
       - '/packages/storage'
     schedule:
       interval: monthly
+    commit-message:
+      prefix: chore
+      include: scope
     open-pull-requests-limit: 25
     groups:
       rollup:

.github/workflows/pr-title.yaml

@@ -0,0 +1,20 @@
+name: PR Title
+on:
+  # Only reads the PR title and never checks out PR code, so pull_request_target is safe here.
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  conventional-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-please.yaml

@@ -0,0 +1,19 @@
+name: Release Please
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v5
+        with:
+          # Falls back to GITHUB_TOKEN, which does not trigger CI on the release PR.
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "3.1.0"
+}

AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md
+
+Hoverboard is a conference website template. Organizers fork it, configure it and deploy it to their own Firebase project. The web app is built with Lit and Vite, data lives in Firestore, and Cloud Functions handle schedule generation, notifications, image optimization and Mailchimp.
+
+## Layout
+
+| Path                        | What it is                                                                                   |
+| --------------------------- | -------------------------------------------------------------------------------------------- |
+| `packages/web`              | The web app: Lit components, Redux Toolkit store, Vite build, Workbox service worker         |
+| `packages/server/functions` | Cloud Functions (v2 API). Must stay self-contained, because `firebase.json` deploys it alone |
+| `packages/cli`              | The `hbd` CLI (`./hbd <command>`), run with `tsx`, no build step                             |
+| `packages/storage`          | Firestore and Storage security rules, indexes, and the rules tests                           |
+| `config/`                   | Build-time site config (`development.json`, `production.json`), selected by `BUILD_ENV`      |
+| `packages/web/public/data/` | Site text and settings (`resources.json`, `settings.json`), FAQ, code of conduct, blog posts |
+| `docs/`                     | Tutorials and the release policy                                                             |
+
+Each package has its own `package.json` and `package-lock.json`. The root is a thin orchestrator: its scripts delegate with `npm --prefix ./packages/<name>`.
+
+## Setup
+
+- Node.js and npm versions come from `engines` in the root `package.json`. CI uses the same file.
+- `npm ci` at the root also installs every package through `postinstall`.
+- Java is needed for the Firestore emulator, which the rules tests and `npm start` use.
+- Some commands expect a `serviceAccount.json` at the root. For local checks, `echo "{}" > serviceAccount.json` is enough. Never commit a real one.
+
+## Commands
+
+Run from the repo root.
+
+| Command                        | Does                                                                                 |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| `npm test`                     | All Vitest projects: Web, Functions, CLI, Firestore (starts the emulator)            |
+| `npx vitest run --project Web` | One project. Add a path to run one file                                              |
+| `npm run lint`                 | ESLint, Prettier, syncpack, lit-analyzer and type checks for web, server and storage |
+| `npm run fix`                  | ESLint and Prettier autofix                                                          |
+| `npm run build`                | Production build of the web app to `packages/web/dist`                               |
+| `npm start`                    | Emulators, functions and web app in watch mode                                       |
+| `./hbd doctor`                 | Checks the local setup, Firebase login, project and billing plan                     |
+
+Before finishing a change, run `npm run lint` and `npm test`, or at least the affected Vitest project and type check.
+
+## Conventions
+
+- **TypeScript** is strict, with `verbatimModuleSyntax`. Use `import type` for type-only imports. Custom elements register as a side effect, so import them with `import './my-element'` where they are used.
+- **Components** use `@customElement`, extend `ThemedElement` (which adds the shared theme styles), and read store state with the `@fromStore` decorator. Use theme CSS variables from `src/styles/theme.ts`, not hard-coded colors.
+- **Tests** sit next to the code as `*.test.ts`. Web tests run in jsdom: render with `fixture` from `packages/web/__tests__/helpers/fixtures.ts`, set state with `setStoreState`, and assert with the jest-dom matchers. Every bug fix or feature needs a test.
+- **Vitest** is configured once in the root `vitest.config.ts`. Do not add `vitest` to a package's `package.json`, because a second copy breaks `expect.extend` from setup files.
+- **Dependencies** shared by several packages must use the same version range. `npm run lint:syncpack` checks this.
+- **Paths.** Vite runs with `packages/web` as the working directory, so its relative paths resolve from there. `config/` is two levels up.
+- **Firestore commands** (`./hbd firestore-*`) use the emulator by default. Only target production with `FIRESTORE_TARGET=production` when explicitly asked.
+- **Formatting.** Prettier formats everything, including Markdown, JSON and YAML. Run `npx prettier --write <files>` after editing them.
+- **Docs** use short, plain sentences. Mark claims that were not tested with "verify".
+
+## Pull requests and releases
+
+- Pull request titles follow [Conventional Commits](https://www.conventionalcommits.org/), for example `fix(web): show session times in the event time zone`. They are squash merged, and the title becomes the release note.
+- Mark breaking changes with `!` and explain what organizers must do in a `BREAKING CHANGE:` paragraph. [docs/releases.md](docs/releases.md) defines what counts as breaking.
+- release-please opens the release pull request and updates [CHANGELOG.md](CHANGELOG.md). Do not edit the changelog by hand.
+
+## Do not commit
+
+- `serviceAccount.json`, `*-adminsdk-*.json`, `.firebaserc`, or any other credentials.
+- Emulator debug logs (`*-debug.log`).
+- `NEXT.md` and the planning specs in `docs/` that it lists. They are local working documents. Do not link to them from committed files.

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+Release notes are generated by [release-please](https://github.com/googleapis/release-please) from pull request titles. See [docs/releases.md](docs/releases.md).
+
+## [3.1.0](https://github.com/gdg-x/hoverboard/releases/tag/v3.1.0) (2026-09-08)
+
+Final v3 release. Earlier releases are listed on [GitHub](https://github.com/gdg-x/hoverboard/releases).

docs/README.md

@@ -10,3 +10,7 @@
 - [Notifications](tutorials/05-notifications.md)
 - [MailChimp auto subscription](tutorials/07-mailchimp-autosubscribe.md)
 - [Firestore utils](tutorials/firebase-utils.md)
+
+## Maintainers
+
+- [Releases](releases.md)

docs/releases.md

@@ -0,0 +1,79 @@
+# Releases
+
+How Hoverboard is versioned and released, and what counts as a breaking change.
+
+## Versioning
+
+Hoverboard uses [semantic versioning](https://semver.org/). The whole repo has one version, kept in the root [package.json](../package.json) and tagged as `vX.Y.Z`. The packages in `packages/` are private and not published, so their own `version` fields are not release versions.
+
+A version describes the impact of an update on a site that runs Hoverboard.
+
+### Major: breaking changes
+
+Anything that makes an organizer change something to keep their site working after updating:
+
+- **Config.** Removing or renaming a key, changing its meaning or type, or adding a required key with no default. This covers `site.json`, the content files and `schemaVersion`.
+- **Content files.** Changing the location or format of `resources.json`, markdown pages, blog posts or images.
+- **Firestore data.** Renaming or removing a collection or field, changing a field's type, or adding a required field.
+- **Security rules.** Firestore or Storage rules that reject data or requests that were allowed before.
+- **Functions.** Removing or renaming a function, changing its trigger, or requiring a new secret, API or Firebase service.
+- **CLI.** Removing or renaming an `hbd` command or flag, or changing a default in a way that changes the result.
+- **Requirements.** Raising the minimum Node.js version in `engines`, requiring a different Firebase plan, or dropping a supported browser.
+- **URLs.** Removing or changing a route without a redirect, which breaks shared links and search results.
+
+### Minor: features
+
+New features, new optional config keys with defaults, new built-in themes, new locales, new `hbd` commands and flags, and deprecations.
+
+### Patch: fixes
+
+Bug fixes, security fixes, translation fixes, and dependency updates with no change in behavior.
+
+## Breaking changes
+
+Every breaking change must:
+
+- Use `!` in the pull request title, for example `feat(config)!: rename event.dates`.
+- Explain what organizers need to do in a `BREAKING CHANGE:` paragraph at the end of the pull request description. It becomes part of the release notes.
+- From v4 on, ship an `hbd upgrade` migration for config and Firestore data changes, with tests against the previous shape.
+
+When possible, deprecate first: keep the old behavior working in a minor release with a warning from the build or `hbd doctor`, then remove it in the next major.
+
+## Pull requests
+
+Pull requests are squash merged, and the title becomes the commit message. Titles follow [Conventional Commits](https://www.conventionalcommits.org/), which the [PR Title](../.github/workflows/pr-title.yaml) check enforces.
+
+| Type       | Use for                                       | In release notes | Version bump |
+| ---------- | --------------------------------------------- | ---------------- | ------------ |
+| `feat`     | A new feature for organizers or attendees     | Features         | Minor        |
+| `fix`      | A bug fix                                     | Bug Fixes        | Patch        |
+| `perf`     | A performance improvement                     | Performance      | Patch        |
+| `revert`   | Reverting an earlier change                   | Reverts          | Patch        |
+| `docs`     | Documentation and tutorials                   | Documentation    | None         |
+| `refactor` | Code changes with no change in behavior       | Hidden           | None         |
+| `test`     | Tests only                                    | Hidden           | None         |
+| `build`    | Build tooling                                 | Hidden           | None         |
+| `ci`       | Workflows                                     | Hidden           | None         |
+| `chore`    | Everything else, including dependency updates | Hidden           | None         |
+| `style`    | Formatting only                               | Hidden           | None         |
+
+Any type with `!` is a major bump. Scopes are optional. Use the package or area, for example `web`, `functions`, `cli`, `storage`, `config` or `deps`.
+
+Write titles for organizers reading the release notes: `fix(web): show session times in the event time zone`, not `fix: tz bug`.
+
+## Making a release
+
+[release-please](https://github.com/googleapis/release-please) runs on every push to `main` ([workflow](../.github/workflows/release-please.yaml), [config](../release-please-config.json)). It keeps one release pull request open that bumps the version and adds the new notes to [CHANGELOG.md](../CHANGELOG.md). Merging that pull request tags the release and publishes a GitHub release.
+
+- Merge the release pull request when the release is ready. There is no fixed schedule. Fixes should be released soon after they land.
+- Until v4 ships, `release-as` in the config pins the release pull request to `4.0.0`, so it collects the v4 notes as work lands. Remove `release-as` in the pull request that releases v4.
+- Pull requests created with the default `GITHUB_TOKEN` do not trigger other workflows. To run CI on the release pull request, add a `RELEASE_PLEASE_TOKEN` secret with a fine-grained token that can write contents and pull requests.
+
+Repository settings this process depends on:
+
+- Allow squash merging only, with the default commit message set to the pull request title and description.
+- Allow GitHub Actions to create and approve pull requests (Settings, Actions, General).
+
+## Supported versions
+
+Only the latest major version gets fixes. v3 ended at v3.1.0, and there will be no more 3.x releases. Pre-v4 sites relaunch on v4 and move their content over by hand.

release-please-config.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "bootstrap-sha": "80395b0ccc6e08cc1f0cdff50186ee119aad0b24",
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "package-name": "hoverboard",
+      "include-component-in-tag": false,
+      "release-as": "4.0.0",
+      "changelog-sections": [
+        { "type": "feat", "section": "Features" },
+        { "type": "fix", "section": "Bug Fixes" },
+        { "type": "perf", "section": "Performance" },
+        { "type": "revert", "section": "Reverts" },
+        { "type": "docs", "section": "Documentation" },
+        { "type": "refactor", "section": "Refactors", "hidden": true },
+        { "type": "test", "section": "Tests", "hidden": true },
+        { "type": "build", "section": "Build", "hidden": true },
+        { "type": "ci", "section": "CI", "hidden": true },
+        { "type": "chore", "section": "Chores", "hidden": true },
+        { "type": "style", "section": "Style", "hidden": true }
+      ]
+    }
+  }
+}