From 1c035672f22f7d9f1d33f0c095c4907985bd6e8e 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 | 68 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +++ 2 files changed, 72 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e233b47 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# Contributing to release-firefox-addon + +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 +``` + +## AMO API Credentials for Local Testing + +To test against the AMO (addons.mozilla.org) API, you need JWT credentials (`auth-api-issuer` and `auth-api-secret`). You can obtain them from the [AMO Developer Hub](https://addons.mozilla.org/en-US/developers/addon/api/key/). + +## 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 unlisted channel upload errors` +- `feat: support release-note locales` +- `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 1fa50b3..554a692 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,10 @@ All supported outputs are the following: | `version-id` | 'ID of the uploaded version in numeric format. | | `version-edit-url` | 'URL of the edit page of the uploaded version. | +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and release process. + ## License [MIT](LICENSE) From 08b5be393289d24b08403fe9e1a470abce65d4d7 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 | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5f1d16d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,58 @@ +# Agentic Coding Guide + +This file provides guidance for AI coding agents working in this repository. + +## Repository Purpose + +`release-firefox-addon` is a GitHub Action that publishes a Firefox add-on to AMO (addons.mozilla.org) using the AMO API with JWT-based authentication. + +## 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 build # compile TypeScript → dist/index.js +pnpm package # copy action.yml + README.md into dist/ +``` + +> ℹ️ There is no automated test suite in this repository. Verify behaviour manually or with integration tests against the AMO API. + +## Project Layout + +``` +src/ + index.ts # action entry point: reads inputs, calls AMO API, sets outputs + amo.ts # AMO API client (upload version, poll status, retrieve version info) +action.yml # action metadata: inputs, outputs, runs.using: node24 +biome.json # linter/formatter config +``` + +## Architecture + +The action flow is: + +1. Read `addon-id`, `addon-path`, optional `source-path`, and JWT credentials from inputs. +2. Use `amo.ts` to upload the add-on zip (and optional source zip) to the AMO API. +3. Poll until the upload is processed, then set version outputs (`version`, `version-id`, `version-edit-url`). + +`amo.ts` constructs signed JWT tokens from `auth-api-issuer` and `auth-api-secret` using the `jsonwebtoken` library. The `uuid` library is used for unique upload identifiers. + +### Source code submission + +If the add-on contains minified or transpiled files, AMO requires a source zip. Pass the `source-path` input and include an `approval-note` explaining how to build the project so reviewers can verify the code. + +### Channel + +The `channel` input controls whether the version is published publicly (`listed`) or unlisted (`unlisted`). Default is `listed`. + +## 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. +- **Never commit AMO API credentials** — always use GitHub Actions secrets. +- The `action.yml` `main` field points to `index.js` inside `dist/`, not the TypeScript source.