Contributing to FaasJS

This file is the entry point for contributors and agents developing the FaasJS framework in this monorepo.

Read In Order

  1. contributing/target-users.md for product boundaries, target users, supported stacks, and core framework trade-offs
  2. contributing/source-of-truth.md for edit locations, generated-file rules, and codebase conventions
  3. contributing/validation.md for environment requirements and validation commands
  4. contributing/documentation-sync.md when changes may affect docs, generated docs, navigation, or changelog entries; it uses @faasjs/docgen via npm run doc as the docs update and sync tool

By Task

Documentation Flow

  • Edit source-of-truth content first: JSDoc in packages/*/src, English guides in skills/*/references/guidelines/**, and specs in skills/*/references/specs/**.
  • Keep skill source links within the same skill. Use plain guide/spec names for cross-skill references; @faasjs/docgen injects public docs-site links when generating docs/**.
  • Run npm run doc to invoke @faasjs/docgen, which refreshes API Markdown, skill references, generated English published docs, and generated guide indexes.
  • The docs site build generates docs/guidelines/** and docs/specs/** from skills/*/references/**; do not edit generated docs directly. docs/guidelines/** is not committed, while docs/specs/** is refreshed through npm run doc when specs change.
  • Do not hand-edit generated docs under packages/*/{classes,functions,interfaces,type-aliases,variables}, docs/guidelines/**, docs/specs/**, docs/guidelines/README.md, or docs/specs/README.md.

Standard Flow

  1. Check existing discussions and issues before creating a new one.
  2. Create or confirm the issue with the proper template (Bug or Feature).
  3. Create a branch from main.
  4. Open a PR that links the issue (Closes #123).
  5. Wait for CI and review, then merge with squash.

Core Expectations

  • Keep each issue and PR focused on one problem or feature.
  • Use lowercase branch names with hyphens: feat/<name>, fix/<name>, docs/<name>, chore/<name>.
  • Mention affected packages under packages/*.
  • Call out breaking changes explicitly.
  • Use Conventional Commits.

Review And Merge

  • main only accepts PR merges.
  • At least 1 approval is required.
  • Required checks must pass.
  • Resolve all review conversations before merge.
  • Merge strategy: Squash and merge.

Release

Releases are handled by maintainers. Do not run release scripts in contributor PRs unless explicitly requested.

Other Ways To Help