From b607731116782ce9a10d8fd904077c987f242d0b 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..ef8aa6f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to setup-firefox + +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: resolve incorrect Firefox binary path on macOS` +- `feat: support latest-esr version 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 ef9552b..9371c46 100644 --- a/README.md +++ b/README.md @@ -40,31 +40,7 @@ jobs: ## 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 87a800e2f92f41832ef3f5f763248e1fc734c00c 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 | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fdfea80 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# Agentic Coding Guide + +This file provides guidance for AI coding agents working in this repository. + +## Repository Purpose + +`setup-firefox` is a GitHub Action that installs Firefox on GitHub Actions runners. It supports stable, beta, devedition, nightly, and ESR releases, as well as specific version numbers. + +## 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, invokes installer, sets outputs + platform.ts # OS/arch detection → Platform struct + versions.ts # version alias resolution (latest, latest-beta, latest-esr, etc.) + DownloadURL.ts # constructs the download URL for a given version and platform + DownloadURLFactory.ts # factory that picks the right DownloadURL strategy for a version spec + installers.ts # installer registry: maps platform to the right installer class + LinuxInstaller.ts # Firefox installer for Linux + MacOSInstaller.ts # Firefox installer for macOS + WindowsInstaller.ts # Firefox installer for Windows + firefoxUtils.ts # shared utilities (e.g. finding the installed binary) + errors.ts # custom error types +__test__/ + DownloadURL.test.ts # tests for URL construction + DownloadURLFactory.test.ts # tests for URL factory dispatch + installers.test.ts # tests for installer selection +action.yml # action metadata: inputs, outputs, runs.using: node24 +biome.json # linter/formatter config +``` + +## Architecture + +Version resolution and download URL construction are separated: + +1. `versions.ts` resolves alias strings (e.g. `latest-beta`) to actual release version numbers by querying the Mozilla release API. +2. `DownloadURLFactory.ts` picks the right `DownloadURL` strategy for the resolved version and platform. +3. Platform-specific installer classes (`LinuxInstaller`, `MacOSInstaller`, `WindowsInstaller`) handle download, extraction, and PATH setup. + +## Testing + +Tests live in `__test__/` and use [Vitest](https://vitest.dev/). + +- Tests mock network/HTTP calls; no real requests are made at test time. +- When adding support for a new version alias or platform, add or update the 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. +- **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.