First off, thanks for taking the time to contribute! 🎉

The following is a set of guidelines for contributing to Forge SQL ORM.

For product scope, platform limits, and documentation obligations, see REQUIREMENTS.md.

This monorepo publishes three npm packages:

CI runs the full quality gate for all three packages on every pull request to master. See REQUIREMENTS.md §2.4 for how features are split between core and extra.

In addition to PR CI, .github/workflows/weekly-gpr.yml publishes a weekly snapshot of master to GitHub Packages (dist-tag: latest) after the same quality checks (Knip, lint, build, tests). Ephemeral ci.* GPR versions are bulk-deleted at the end of that job.

Consumer install instructions (.npmrc, npm aliases): README — Installing from GitHub Packages (weekly latest). You do not need to run the weekly workflow locally when contributing — merge to master and wait for the schedule, or trigger Weekly GitHub Packages (latest) manually from Actions if needed.

This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code.

This project uses Husky to enforce high code quality standards via git hooks.

# Clone the repository
git clone https://github.com/forge-sql-orm/forge-sql-orm.git

# Install dependencies (this automatically sets up Husky)
npm install

Important: Simply running npm run test is NOT sufficient. Our pre-commit hook is strict and performs a full health check.

Before committing, ensure your code passes the following suite:

# 1. Format code (Essential!)
npm run format

# 2. Type-checking & Build
npm run build

# 3. Dependency validation (Knip)
npm run knip

# 4. Linter
npm run lint

# 5. Tests with Coverage
npm run test

If you changed forge-sql-orm-extra or forge-sql-orm-cli, run the same checks in that package directory before opening a PR:

# forge-sql-orm-extra
cd forge-sql-orm-extra
npm ci
npm run knip
npm run build
npm run test:coverage

# forge-sql-orm-cli
cd forge-sql-orm-cli
npm ci
npm run knip
npm run build
npm run test:coverage

This project enforces strict code coverage thresholds via Vitest in each package (root, forge-sql-orm-extra/, forge-sql-orm-cli/). If your PR lowers the coverage below these limits, the build will fail:

• Statements: > 80%
• Branches: > 80%
• Functions: > 80%
• Lines: > 80%

Please ensure that any new logic includes corresponding unit tests.

Reporting Bugs & Suggestions

• Use a clear title and describe the problem or suggestion in detail.
• Provide reproduction steps (code snippets or repo links are highly appreciated).
• Explain expected vs. actual behavior.

Pull Requests

1. Fork the repo and create your branch from master.
2. Make sure you have run the Pre-commit Requirements listed above.
3. Ensure strict coverage thresholds are met.
4. Issue that pull request!

Forge SQL ORM is a solo-maintained open-source project. To keep review discipline strong without a team of human reviewers, every PR goes through an automated review pipeline whose comments are treated as binding review items.

Review tools that run on every PR to master:

Comment resolution is mandatory:

• Every comment posted by any tool above is a blocking review item, regardless of severity.
• A human maintainer must explicitly resolve each comment — by applying a fix, replying with reasoning that the comment is wrong/inapplicable and marking it resolved, or filing a follow-up issue if it is out of scope.
• Auto-merge is enabled only after the pipeline passes and every outstanding comment has been resolved by a human.
• PRs with unresolved bot comments will not be merged.

This replaces, by design, the need for a second human reviewer on a solo-maintained project. See REQUIREMENTS.md §8.2 for the corresponding requirements-level definition.

The CI pipeline (.github/workflows/node.js.yml, job examples) builds and deploys every example app to Atlassian Forge. The target environment depends on the trigger:

• Push to master → the production Forge environment.
• Pull request (or manual development dispatch) → a per-contributor Forge environment, named after your sanitized GitHub username (github.actor with everything except letters/digits stripped, e.g. Jane-Doe → JaneDoe). Each example is then installed on FORGE_HOSTNAME for that environment.

The install step is idempotent: it runs forge install list --json, checks whether the app already exists on FORGE_HOSTNAME in that environment, and either --upgrades it or performs a fresh install.

All deployments run under the maintainer's Forge credentials (FORGE_EMAIL / FORGE_API_TOKEN repository secrets) against the maintainer's apps and FORGE_HOSTNAME site — you do not need any Forge account, site access, or Developer Console membership to contribute. The per-contributor environment naming only namespaces the dev deploys so concurrent PRs don't collide.

Diagnostic logging goes through the platform-native console.* API — Atlassian Forge captures console output from resolvers and triggers, and we deliberately avoid third-party logging frameworks to keep dependencies lean (see REQUIREMENTS.md NFR-11).

Because of this, no-console is configured as an ESLint error. You cannot just drop in a console.log:

• Each intentional log must be opted in per line with // eslint-disable-next-line no-console.
• Think before adding one — keep it intentional and minimal, and gate noisy output behind a flag where appropriate (e.g. logRawSqlQuery):

if (newOptions.logRawSqlQuery) {
  // eslint-disable-next-line no-console
  console.debug("Initializing ForgeSQLORM...");
}

The explicit opt-in is intentional: it keeps every log line visible in review rather than letting console output accumulate accidentally.

• Use the present tense ("Add feature" not "Added feature").
• Reference issues and pull requests liberally.