Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
226 lines (144 loc) · 3.67 KB

CONTRIBUTING.md

File metadata and controls

226 lines (144 loc) · 3.67 KB

Contributing to dfsync

Thank you for your interest in contributing to dfsync.

dfsync is an open-source TypeScript library focused on reliable HTTP communication between services. We welcome contributions that improve stability, developer experience, documentation, and examples.

Ways to Contribute

You can contribute by:

  • fixing bugs
  • improving documentation
  • adding examples
  • improving test coverage
  • suggesting new features
  • improving developer experience

Small and focused pull requests are preferred.

Before You Start

Before opening a pull request:

  1. Check existing issues and pull requests
  2. For larger changes, consider opening an issue first
  3. For small fixes (docs, typos, tests), feel free to open a PR directly

Project Structure

This repository uses a pnpm monorepo.

packages/
  client/        main dfsync HTTP client package

examples/
  node-basic/    basic usage example

smoke/
  */             smoke tests verifying published packages

The main library lives in:

packages/client

Local Development

Requirements:

  • Node >= 20
  • pnpm >= 10

Clone the repository:

git clone https://github.com/dfsyncjs/dfsync.git
cd dfsync

Setup:

corepack enable
pnpm install

Install dependencies:

pnpm install

Build the project:

pnpm build

Run tests:

pnpm test

Run lint:

pnpm lint

Type checking:

pnpm typecheck

Coding Guidelines

Please follow these principles:

  • Use TypeScript
  • Keep the public API minimal and predictable
  • Prefer small focused changes
  • Avoid breaking public APIs without discussion
  • Keep code readable and maintainable

Tests

If your change affects behavior:

  • add or update tests
  • ensure all tests pass

Tests are run using Vitest.

Run locally:

pnpm test

Documentation

If your change affects the public API, please update:

  • README
  • documentation
  • examples (if necessary)

Examples should remain simple and runnable.

Changesets and Releases

This project uses changesets for release management.

If your change affects the published package:

pnpm changeset

Examples when a changeset is required:

  • new features
  • bug fixes
  • API changes

Documentation-only changes usually do not require a changeset.

How to verify the package before release

Before publishing @dfsync/client, run the standard test suite and the pack smoke checks.

1. Run the regular checks

pnpm test

2. Verify the published package shape

These checks build the package, create a tarball with pnpm pack, install that tarball into isolated smoke projects, and verify that the package works as expected.

pnpm smoke:pack

This command runs:

  • pnpm smoke:pack:esm — verifies ESM import from the packed tarball
  • pnpm smoke:pack:cjs — verifies CommonJS require() from the packed tarball
  • pnpm smoke:pack:types — verifies TypeScript types from the packed tarball

Why this matters

Examples in the monorepo validate local workspace usage, but the pack smoke tests validate the actual publish artifact that users install from npm. This helps catch issues with:

  • dist output
  • exports
  • CommonJS / ESM entry points
  • published type definitions

Pull Requests

When submitting a PR:

  • create a branch from main
  • keep PRs small and focused
  • provide a clear description of the change
  • explain why the change is needed

Before submitting, ensure the following commands succeed:

pnpm lint
pnpm typecheck
pnpm test

Thank You

Your contributions help make dfsync better for everyone.