From 46f4dc0b8a9af359b9bf8ffa7606adbf8304382e Mon Sep 17 00:00:00 2001 From: Shin'ya Ueoka Date: Wed, 29 Apr 2026 13:58:41 +0900 Subject: [PATCH 1/2] docs: add CONTRIBUTING.md and link from README Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 26 +------------------- 2 files changed, 65 insertions(+), 25 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0e6e4b4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to setup-chrome + +Thank you for your interest in contributing! + +## Development Setup + +**Prerequisites:** Node.js ≥ 24, [pnpm](https://pnpm.io/) + +```bash +# Install dependencies +pnpm install +``` + +## Development Workflow + +```bash +# Lint (CI mode, no auto-fix) +pnpm lint + +# Lint with auto-fix +pnpm lint:fix + +# Run unit tests +pnpm test + +# Run tests with verbose output +pnpm test -- --reporter=verbose + +# Run a single test file +npx vitest run __test__/.test.ts + +# Build (compiles TypeScript → dist/index.js via @vercel/ncc) +pnpm build + +# Package (copies action.yml + README.md into dist/) +pnpm package +``` + +## Submitting Changes + +1. Fork the repository and create a branch from `master`. +2. Make your changes with tests where applicable. +3. Run `pnpm lint` and `pnpm test` to verify everything passes. +4. Open a pull request against `master`. + +**Important:** All commit messages must follow [Conventional Commits][] — this is required for the automated release process to correctly determine version bumps and generate changelog entries. + +Examples: +- `fix: handle missing chromedriver binary on Windows` +- `feat: add support for chrome-version input alias` +- `chore: update dependencies` + +## Release Process + +Releases are automated with [Release Please](https://github.com/googleapis/release-please): + +1. Merge changes to `master` following Conventional Commits. +2. Release Please opens or updates a release PR with version bumps and changelog updates. +3. Squash and merge the release PR. +4. CI builds `dist/`, pushes it to the `latest` branch, and creates signed `vX` and `vX.Y.Z` tags. + +> **Note:** Never commit generated `dist/` files to the source branch — they are built and published automatically by CI. + +[Conventional Commits]: https://www.conventionalcommits.org/en/v1.0.0/ diff --git a/README.md b/README.md index 6ed3851..cac5a79 100644 --- a/README.md +++ b/README.md @@ -113,31 +113,7 @@ steps: ## Contributing -### Local development - -```bash -# Instal dependencies -pnpm install - -# Run tests -pnpm lint -pnpm test - -# Build and create package in dist/ -pnpm build -pnpm package -``` - -## Release - -Releases are automated with Release Please. All changes must follow [Conventional Commits][], since Release Please derives versions and changelog entries from commit messages. - -1. Merge some changes to the main branch. -2. Release Please opens or updates a release PR with version bumps and changelog updates. -3. Squash and merge the release PR to the main branch with a commit message that follows [Conventional Commits][]. -4. Create a GitHub release and publish the action to the marketplace. - -[Conventional Commits]: https://www.conventionalcommits.org/en/v1.0.0/ +See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and release process. ## License From c2a509a98f09b70c3a51a36bba59b396af4a1f32 Mon Sep 17 00:00:00 2001 From: Shin'ya Ueoka Date: Wed, 29 Apr 2026 14:01:16 +0900 Subject: [PATCH 2/2] docs: add AGENTS.md for agentic coding guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fa42ae6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,78 @@ +# Agentic Coding Guide + +This file provides guidance for AI coding agents working in this repository. + +## Repository Purpose + +`setup-chrome` is a GitHub Action that installs Google Chrome, Chromium, and optionally ChromeDriver on GitHub Actions runners. It supports stable/beta/dev/canary channels, specific version numbers, commit positions (snapshot builds), and the latest snapshot. + +## Commands + +```bash +pnpm install --frozen-lockfile # install dependencies +pnpm lint # lint with Biome (CI mode, no auto-fix) +pnpm lint:fix # lint with auto-fix +pnpm test # run all unit tests with Vitest +pnpm test -- --reporter=verbose # verbose test output +npx vitest run __test__/.test.ts # run a single test file +pnpm build # compile TypeScript → dist/index.js +pnpm package # copy action.yml + README.md into dist/ +``` + +## Project Layout + +``` +src/ + index.ts # action entry point: reads inputs, selects installer, sets outputs + installer.ts # Installer interface (checkInstalled, download, install for browser+driver) + version.ts # version string parser → typed spec (latest | channel | snapshot | four-parts) + platform.ts # OS/arch detection → Platform struct + latest_installer.ts # installs the latest snapshot build + snapshot_installer.ts # installs a specific snapshot by commit position + version_installer.ts # installs a known-good version via Chrome for Testing API + channel_linux.ts # channel installer for Linux (stable/beta/dev/canary) + channel_macos.ts # channel installer for macOS + channel_windows.ts # channel installer for Windows + chrome_for_testing.ts # client for the Chrome for Testing JSON API + snapshot_bucket.ts # client for the Chromium snapshot GCS bucket + cache.ts # tool-cache helpers for caching installed binaries + dependencies.ts # install system dependencies on Linux (apt) +__test__/ + *.test.ts # Vitest unit tests, one file per source module + data/ # JSON fixtures for API responses (excluded from linting) +action.yml # action metadata: inputs, outputs, runs.using: node24 +biome.json # linter/formatter config (space indent; useLiteralKeys and noUselessElse off) +``` + +## Architecture + +Version resolution follows a strategy pattern. `version.ts` parses the input string into one of four types, and `index.ts` selects the appropriate `Installer` implementation: + +| Version spec | Installer class | Source | +|---------------------|-------------------------------|---------------------------| +| `latest` | `LatestInstaller` | Chromium snapshot bucket | +| `stable/beta/dev/canary` | `*ChannelInstaller` | Platform package manager | +| `1295939` (commit) | `SnapshotInstaller` | Chromium snapshot bucket | +| `120.0.6099.x` | `KnownGoodVersionInstaller` | Chrome for Testing API | + +All installer classes implement the `Installer` interface from `installer.ts`. Each provides methods for both browser and ChromeDriver installation. + +The action uses `actions-swing` as a shared utility library — check there before adding new utility functions. + +## Testing + +Tests live in `__test__/` and use [Vitest](https://vitest.dev/). Test files mirror source file names (e.g., `version.test.ts` tests `version.ts`). + +- JSON fixtures for mocked API responses are in `__test__/data/` — do not lint this directory. +- Tests mock network calls; no real HTTP requests are made. +- When adding a new installer or version format, add a corresponding test file. + +## Conventions + +- **TypeScript strict mode** — all types must be explicit; avoid `any`. +- **Linter:** Biome — run `pnpm lint` before committing. `useLiteralKeys` and `noUselessElse` rules are disabled. +- **Formatter:** Biome with space indentation. +- **Node.js ≥ 24** is required (specified in `package.json` engines and `action.yml`). +- **Conventional Commits** are required for all commits (`feat:`, `fix:`, `chore:`, etc.). +- **Never commit `dist/`** — it is built by CI and deployed to the `latest` branch on release. +- The `action.yml` `main` field points to `index.js` inside `dist/`, not the TypeScript source.