Skip to content

Latest commit

 

History

History
178 lines (130 loc) · 6.13 KB

CONTRIBUTING.md

File metadata and controls

178 lines (130 loc) · 6.13 KB

Contributor Guide (@addon-core/browser)

Thank you for your interest in contributing! This package is a promise‑oriented TypeScript wrapper around the Chrome Extensions API (MV2/MV3) with additional convenience helpers. Our goal is to cover all available APIs and simplify day‑to‑day extension development.

By participating, you agree to the Code of Conduct.

Contents:

  • Getting started
  • GitFlow: branching and PRs
  • Commits: Conventional Commits and versioning
  • Scope: cover Chrome APIs and add helpers
  • Code quality: lint, format, types
  • Tests
  • Documentation
  • Releases and publishing (GitHub Actions + release-it)
  • License

Getting started

  1. Fork and clone
  1. Install dependencies
npm ci
  1. Useful scripts
  • npm run dev — build in watch mode (tsup)
  • npm run build — production build (tsup)
  • npm run lint / npm run lint:fix — check/fix with Biome
  • npm run format — format with Biome
  • npm run typecheck — type-check with tsc
  • npm test / npm run test:ci — tests (Jest)

Minimum Node.js version: current LTS (at release time).

GitFlow: branching and PRs

We use GitFlow:

  • main — stable releases.
  • develop — integration branch. Most PRs should target develop.
  • Task branches:
    • feature/<short-feature-name> — new features.
    • bugfix/<short-bug-name> — fixes based off develop.
    • release/<x.y.z> — release preparation from develop.
    • hotfix/<x.y.z> — urgent fixes from main (merge back to develop after release).

PR rules:

  • Small, atomic changes with a clear description and a linked issue (e.g., “Closes #123”).
  • Required checks: lint, types, tests, build must be green.
  • At least one review is required.

Commits: Conventional Commits and versioning

Follow Conventional Commits: type(scope): subject. Examples:

  • feat(tabs): add getActiveTab helper
  • fix(downloads): handle USER_CANCELED interruption
  • refactor(runtime): unify error handling
  • docs(readme): add usage examples

Types and their impact on version (as configured in release-it):

  • MAJOR: any commit with BREAKING CHANGE: in the footer or with a bang — feat!: ....
  • MINOR: feat, and also revert (project policy bumps minor on reverts).
  • PATCH: fix, perf, refactor, ci.
  • Do not trigger a release by themselves: docs, test, chore, build, style (they may be hidden in the changelog).

Commit messages are validated by commitlint (see .commitlintrc.json). Changelog and version selection are automated via release-it + Conventional Changelog (see .release-it.cjs).

Format BREAKING CHANGE like this:

feat(action)!: rename setBadgeBgColor to setBadgeBackgroundColor

BREAKING CHANGE: function renamed to align with Chrome naming.

Scope: cover Chrome APIs and add helpers

The goal is to cover as much of the WebExtensions/Chrome API surface as possible and provide practical helpers. For major changes, please open an issue first to discuss.

How to add a new API wrapper:

  1. Implementation
  • Create src/<api>.ts.
  • Wrap callback‑style APIs into Promise and call throwRuntimeError() inside callbacks.
  • Events must return an unsubscribe function () => void (see handleListener/safeListener).
  • Use precise types from @types/chrome (avoid Parameters<> in the final documentation — show real argument types).
  • Keep function names concise and consistent (see existing modules).
  • Where appropriate, add cross‑MV2/MV3 helpers and cross‑browser unification (examples: action, sidebar).
  1. Export
  • Re-export from src/index.ts.
  1. Documentation
  • Create docs/<api>.md following the template: “Documentation → Methods/Events (links to sections) → sections with real TypeScript signatures”.
  • Update the list in README.md (link to the new file and add a brief description where it helps).
  1. Tests
  • Cover core scenarios: success, error (runtime.lastError), events (subscribe/unsubscribe behavior).

See the list of not-yet-covered APIs in the "Not yet covered" section of README.md.

Code quality: lint, format, types

  • Formatting/linting: Biome — npm run format, npm run lint.
  • Type checking: npm run typecheck.
  • Husky + lint-staged run pre-commit checks (Biome and jest --findRelatedTests).

PRs with lint/type/build errors won’t be accepted.

Tests

Framework: Jest (npm test). Recommendations:

  • Mock chrome.* APIs (simple stubs/mocks are fine).
  • Test error paths (runtime.lastError).
  • For events, verify that the returned function actually removes the listener.
  • Structure: co-locate tests with the module or use a __tests__ folder.

In CI use npm run test:ci.

Documentation

  • For each new API, add a file under docs/ and keep signatures accurate.
  • Keep README concise and link to detailed per‑API docs in docs/.
  • Maintain a consistent style and anchors for methods/events.

Releases and publishing (GitHub Actions + release-it)

Releases are performed by maintainers.

Flow (aligned with GitFlow):

  1. Merge features into develop via PRs.
  2. Create a release/x.y.z branch from develop. Preview autogenerated CHANGELOG: 
    npm run release:preview
  3. Prepare the release: 
    npm run release
    This runs release-it: determines the version via Conventional Commits, creates tag vX.Y.Z, generates CHANGELOG.md, and pushes tags.
  4. Pushing a v* tag triggers GitHub Actions, which:
    • runs lint/types/tests/build;
    • creates a GitHub Release;
    • publishes the package to npm (npm publish).

Required repository/org secrets:

  • NPM_TOKEN — for publishing to npm;
  • GITHUB_TOKEN (provided automatically by Actions) — for releases and changelog.

Release configuration: .release-it.cjs (preset conventionalcommits, changelog generation, version bump rules). Scripts: npm run release, npm run release:preview.

License

By contributing, you agree to license your contributions under the project’s MIT license. See LICENSE.md.