Skip to content

Latest commit

 

History

History
150 lines (102 loc) · 5.73 KB

CONTRIBUTING.md

File metadata and controls

150 lines (102 loc) · 5.73 KB

Contributing

We appreciate your interest in contributing to observerly, and your contributions are integral to enhancing this project. Whether you are addressing a bug, implementing new features, or suggesting improvements, your involvement is highly valued and essential.

What Orderly Runs On

orderly is middleware for Cloudflare Queues. It runs on workerd, not Node, and this shapes almost everything below.

  • No Node built-ins. node:fs, node:path and friends are unavailable at runtime. The TypeScript configuration deliberately omits the DOM library for the same reason: browser-only APIs are not there either.
  • Tests execute inside workerd, not Node, through @cloudflare/vitest-pool-workers. A test that passes under Node proves nothing about the runtime orderly ships on.
  • Node is used only to run the toolchain.

Code Style

Formatting and linting are not matters of taste here — they are enforced, and a pre-commit hook applies them to staged files automatically.

File Headers

Every TypeScript file opens and closes with a banner, and separates top-level declarations with the same banner:

/*****************************************************************************************************************/

// @author         Michael Roberts <michael@observerly.com>
// @package        @observerly/orderly
// @license        Copyright © 2026 observerly

/*****************************************************************************************************************/

export const example = (): void => {};

/*****************************************************************************************************************/

The banner is exactly 115 characters. @package is the bare package name in src/index.ts, and the module path elsewhere, such as @observerly/orderly/middleware. Copy an existing file rather than retyping it.

Getting Started

1. Fork The Repository

Fork @observerly/orderly.

2. Clone The Repository

git clone https://github.com/<REPLACE_WITH_YOUR_USERNAME>/orderly.git
cd orderly

3. Setup

The quickest route is the development container. Open the repository in an editor that supports Dev Containers and it arrives with the pinned Node and pnpm already in place, with dependencies installed. Nothing else in this section applies.

To work on the host instead, you need Node and pnpm:

nvm install
npm install -g pnpm
pnpm install

nvm install reads .nvmrc, so it installs and selects the pinned Node. Any recent pnpm will do: managePackageManagerVersions is set, so pnpm reads the packageManager field and switches itself to the pinned version rather than running whatever you happen to have.

pnpm install refuses to run on a Node version below the engines floor, and installs the pre-commit hook for you. No further setup step is needed.

4. Develop

Command What it does
pnpm build Bundles to dist/ with rolldown
pnpm test Runs the suite once, inside workerd
pnpm test:watch Same, in watch mode
pnpm typecheck Typechecks the library and the tests
pnpm lint Fast syntactic lint
pnpm lint:types Type-aware lint, including no-floating-promises
pnpm lint:package Validates the published package shape
pnpm format Formats in place

Tests live in tests/ and use the .spec.ts suffix.

Branches

main is the default branch and the most recent canary version of the codebase. All development work happens on a separate branch, using a trunk-based workflow.

git checkout -b <COMMIT_TYPE>/<SCOPE>/branch-name

For example, chore/configuration/oxlint or fix/middleware/retry-delay.

Committing Your Changes

Write clear, concise commits following Conventional Commits.

If your change is one a consumer of the package would notice, it also needs a changeset:

pnpm changeset

Commit the generated file alongside your change. Nothing enforces this, so a pull request that needs a changeset and lacks one will merge cleanly and quietly miss the next release. See RELEASING.md for the full process.

Create A Pull Request

Open the pull request against main. CI runs formatting, both lint passes, typechecking, the test suite, the build and the package checks. All of them must pass.

Review And Feedback

Reviews are about the change, not the person making it. Expect questions; ask them freely in return.

Bug Reports

Open an issue. A report is most useful when it includes the queue configuration involved, the batch or message that triggered it, and what you expected to happen instead.

Feature Requests

Also an issue. Describe the queue behaviour you are trying to achieve rather than the API you imagine; there may be a simpler route to it.

Code Of Conduct

This project is governed by the Code of Conduct.