Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The data-path project is a modern, zero-dependency library designed for type-safe object property path manipulation. These guidelines establish the standards for code quality, communication, and automated release cycles to ensure contributions align with the project's architecture and maintainability goals.
The library emphasizes a "Zero Config" development experience, leveraging modern tooling like Biome for linting and formatting, and Vitest for a robust test suite that includes runtime and type-level assertions.
Sources: README.md:1-5, CONTRIBUTING.md:1-6
Contribution Workflow
The project operates under a specific protocol for proposing changes, distinguished by the scale and nature of the modification.
The "Golden Rule" of Communication
Contributors are encouraged to categorize their work into two distinct paths:
- Direct Pull Requests: Appropriate for bugs, typos, or broken functionality. No prior discussion is required.
- Issue-First Discussion: Required for new features or significant architectural changes. This ensures the proposal fits the project's vision and avoids duplicated efforts.
The following flowchart illustrates the decision-making process for new contributions:
The diagram outlines the path from identifying a change to the final merge, emphasizing the discussion phase for new features.
Sources: CONTRIBUTING.md:8-14
Local Development Environment
Setting up the development environment is designed to be minimal. The project utilizes tsup for building and husky for pre-commit validation.
Setup and Tooling
The environment requires Node.js (v20 or higher) and uses the following core commands defined in the project configuration:
| Command | Action |
|---|---|
npm ci | Installs dependencies using the lockfile. |
npm run build | Compiles the source into CJS and ESM formats using tsup. |
npm run dev | Runs the build in watch mode for instant updates. |
npm run lint | Performs a code quality check using Biome. |
npm run test | Executes the Vitest test suite, including typechecks. |
Sources: CONTRIBUTING.md:16-29, package.json:11-20, package.json:49-51
Code Style and Standards
The project enforces strict code style and linting without requiring manual configuration by the developer.
Biome Configuration
Biome is the primary tool for formatting and linting. It is configured to handle JavaScript and TypeScript with specific rules:
- Indentation: Uses tabs.
- Quotes: Enforces double quotes for JavaScript strings.
- Linter: Recommended rules are enabled, with a specific override to allow arrow functions (
useArrowFunction: "off"). - Import Organization: Automatically organizes imports.
Husky hooks are utilized to run biome check --write automatically before every commit, ensuring no unformatted or lint-violating code reaches the repository.
Sources: biome.json:1-40, CONTRIBUTING.md:31-41
Commit and Release Automation
data-path uses an automated release pipeline. The versioning and changelog generation are driven entirely by the structure of commit messages.
Conventional Commits
All commits must follow the Conventional Commits specification. The commitlint.config.js extends the conventional configuration to enforce this at the local level via git hooks.
| Prefix | Resulting Action |
|---|---|
feat: | Triggers a Minor release (e.g., 1.0.0 -> 1.1.0). |
fix: | Triggers a Patch release (e.g., 1.0.0 -> 1.0.1). |
docs: | No release triggered; updates documentation only. |
chore: | No release triggered; internal maintenance. |
CI/CD Pipeline
The release process is handled via GitHub Actions and semantic-release. The sequence from commit to NPM publication is as follows:
This sequence shows how automated tools validate code locally before GitHub Actions handles the final build, testing, and distribution.
Sources: CONTRIBUTING.md:43-57, commitlint.config.js:1, package.json:44-48
Testing Requirements
The project maintains high standards for both runtime logic and TypeScript type safety. The test configuration is managed in vitest.config.ts.
- Runtime Tests: Located in
src/tests/**/*.spec.ts, these verify the functional logic of path creation, manipulation, and data access. - Type Tests: Located in
src/tests/**/*.test-d.ts, these useexpectTypeOfandassertTypeto ensure the library's complex generics remain sound. - Coverage: Contributors are expected to include both
.spec.tsand.test-d.tsfiles for any new feature to prevent regressions.
Sources: vitest.config.ts:1-12, package.json:17-18
Summary
Contributing to data-path involves adhering to a streamlined, automated workflow that prioritizes discussion for new features and leverages Biome and Conventional Commits for quality control. By following these guidelines, contributors ensure the library remains a robust, zero-dependency tool for the TypeScript ecosystem.