Contributing Guidelines

Contributions to the core Bloom applications and services are welcomed. To help us meet the project’s goals around quality and maintainability, we ask that all contributors read, understand, and agree to these guidelines before submitting work.

Issue tracking

Development tasks are managed through GitHub Issues and, in the vast majority of cases, work should be tied to an issue.

Bugs

Use GitHub Issues to report any defects in the core software or reference implementations. Implementation-specific issues should be tracked in the repositories for those individual sites.

Feature ideas

Submit feature requests as GitHub Issues even if you don’t plan to implement them yourself. They help the team understand demand and prioritize work.

Check for existing issues

Before creating a new issue, search the issue tracker to see if one already exists. Duplicate issues slow down triage.

Fill out all fields

When creating an issue, complete every provided field and include as much detail as possible. Add screenshots wherever they help illustrate the problem.

Check in with the team before starting work

Don’t begin implementing a fix or feature without checking in first — it may already be in active development. Tag the team to get started: @ludtkemorgan, @emilyjablonski, @yazeedloonat.

Conventional commits

Bloom uses the Conventional Commits specification. Every commit message must follow this format or the linter will reject it.

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Common types include:

Type	When to use
`feat`	A new feature
`fix`	A bug fix
`chore`	Build process or tooling changes
`docs`	Documentation only changes
`refactor`	Code change that neither fixes a bug nor adds a feature
`test`	Adding or updating tests
`style`	Formatting changes that don’t affect meaning

You have two options for committing:

Commitizen (recommended)
Manual commit

Commitizen is a CLI that asks a series of questions and builds a valid commit message for you.

Install commitizen globally

npm install -g commitizen

Commit with git cz

Instead of git commit, run:

git cz

The interactive prompt will guide you through selecting a type, writing a description, and adding an optional body.

You can run git commit with your own message as long as it follows the conventional commit format.

git commit -m "feat(listings): add map marker endpoint"

The commit-msg hook runs commitlint to verify the format. If your message doesn’t conform to the conventional commit standard the commit will be rejected.

Pre-commit hooks

Bloom ships a pre-commit hook in the .githooks/ directory that runs Gitleaks to scan staged changes for accidentally committed secrets.

Install Gitleaks

On macOS:

brew install gitleaks

For other platforms, see the Gitleaks installation docs.

Enable the hook

From the root of your local clone:

git config core.hooksPath .githooks/

The pre-commit script (gitleaks -v git --pre-commit --staged) will now run automatically before every commit.

Gitleaks is also enforced on all pull requests to main via a GitHub Actions workflow. If the job fails on your PR, notify the team so the flagged secret can be triaged and rotated if necessary.

Code style

Bloom enforces code style with ESLint and Prettier. All pull requests must pass linting to be accepted.

Prettier configuration

The Prettier config is defined in package.json:

package.json

"prettier": {
  "singleQuote": false,
  "printWidth": 100,
  "semi": false
}

Key rules at a glance:

Double quotes for strings
Line length capped at 100 characters
No semicolons

ESLint configuration

The root .eslintrc.js uses the @typescript-eslint/recommended ruleset, plugin:jsx-a11y/recommended for accessibility, and plugin:prettier/recommended to surface Prettier violations as ESLint errors. Lint-staged runs ESLint on every staged .js, .ts, and .tsx file before a commit is allowed. If linting rules become out of date, file an issue. A resulting PR should include two commits minimum: one to update the rules or tooling, and another to update the codebase to match.

VSCode extensions

If you use VSCode, these extensions are recommended:

Prettier

Install the Prettier extension, then enable Format on Save in User Settings (⌘⇧P → search “Format on Save”). Files will auto-format on every save.

Postgres explorer

The Postgres explorer extension lets you inspect your local database directly from the editor. See the api README for connection setup instructions.

Code Spell Checker

The Code Spell Checker extension flags spelling errors inline.

CSS variable autocomplete

The CSS variable autocomplete extension pulls all CSS variable definitions from ui-seeds for autocompletion. See the public site README for additional setup.

axe Accessibility Linter

The axe Accessibility Linter extension checks for common accessibility issues as you write JSX.

Naming conventions

The following conventions apply to backend (api/) code.

Controllers

File extension: .controller.ts
File name uses the singular model name — e.g., listing.controller.ts
Exported class: PascalCase — e.g., ListingController
Lives under src/controllers/

Services

File extension: .service.ts
File name uses the singular model name — e.g., listing.service.ts
Exported class: PascalCase — e.g., ListingService
Lives under src/services/

DTOs

File extension: .dto.ts
File name: lowercase kebab-case — e.g., listings-filter-params.dto.ts
Exported class: PascalCase, no Dto suffix — e.g., ListingFilterParams
Lives under src/dtos/

Modules

File extension: .module.ts
File name uses the singular model name — e.g., listing.module.ts
Exported class: PascalCase — e.g., ListingModule
Lives under src/modules/

Enums

File name: lowercase kebab-case ending in -enum.ts — e.g., filter-key-enum.ts
Exported enum: PascalCase — e.g., ListingFilterKeys
Lives under src/enums/

Prisma/database enums are defined in schema.prisma and are separate from the NestJS application enums described above.

Pull requests

Pull requests are opened against the main branch.

Fill out the full PR template

The template includes: a link to the related issue, a description of the changes, instructions for the reviewer on how to test, and a testing checklist. Complete every section.

Label your PR

Add the needs review(s) label when the PR is ready for eyes.
Add the wip label if the PR is not yet ready for review.

Review etiquette

As a reviewer, don’t leave only inline comments — always leave a clear next-step action:

Requested Changes — further discussion or code changes are needed before merging.
Approved — the PR looks good; comment any small remaining changes that don’t require an additional review cycle.

This keeps the PR list state clear and avoids unnecessary extra review cycles.

On all pull requests, GitHub Actions automatically runs the full test suite: API unit tests, API integration tests, public and partners unit/integration tests, and Cypress E2E tests for both sites. No PR that introduces errors in existing tests will be accepted.

Get Started

Core Features

Sites

Backend API

Configuration

Deployment & Operations

Contributing

Issue tracking

Bugs

Feature ideas

Conventional commits

Pre-commit hooks

Code style

Prettier configuration

ESLint configuration

VSCode extensions

Naming conventions

Controllers

Services

DTOs

Modules

Enums

Pull requests

Build docs developers (and LLMs) love

Get Started

Core Features

Sites

Backend API

Configuration

Deployment & Operations

Contributing

​Issue tracking

Bugs

Feature ideas

​Conventional commits

​Pre-commit hooks

​Code style

​Prettier configuration

​ESLint configuration

​VSCode extensions

​Naming conventions

​Controllers

​Services

​DTOs

​Modules

​Enums

​Pull requests

Build docs developers (and LLMs) love

Issue tracking

Conventional commits

Pre-commit hooks

Code style

Prettier configuration

ESLint configuration

VSCode extensions

Naming conventions

Controllers

Services

DTOs

Modules

Enums

Pull requests