Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
297 lines (203 loc) · 5.92 KB

CONTRIBUTING.md

File metadata and controls

297 lines (203 loc) · 5.92 KB

Contributing to FormKit Gov

Thank you for your interest in contributing to FormKit Gov! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Prerequisites

  • Node.js >= 20.0.0
  • pnpm >= 9.0.0
  • Git

Development Setup

  1. Fork the repository on GitHub.

  2. Clone your fork locally:

    git clone https://github.com/YOUR_USERNAME/formkit-gov.git
cd formkit-gov

  3. Add the upstream repository:

    git remote add upstream https://github.com/LinnJS/formkit-gov.git

  4. Install dependencies:

    pnpm install

  5. Build all packages:

    pnpm build

  6. Run tests to ensure everything is working:

    pnpm test

Project Structure

formkit-gov/
├── packages/
│   ├── core/           # @formkit-gov/core - Zod schemas & utilities
│   ├── react/          # @formkit-gov/react - React components
│   ├── store/          # @formkit-gov/store - State management
│   ├── wizard/         # @formkit-gov/wizard - Multi-step forms
│   ├── openapi/        # @formkit-gov/openapi - OpenAPI integration
│   ├── validators/     # @formkit-gov/validators - Extended validators
│   └── test-utils/     # @formkit-gov/test-utils - Testing utilities
├── docs/               # Internal documentation
└── ...config files

Making Changes

Branch Naming

Create a branch for your changes:

git checkout -b <type>/<scope>/<description>

Examples:

  • feat/react/add-date-picker
  • fix/core/ssn-validation
  • docs/wizard/update-examples

Development Workflow

  1. Make your changes in the appropriate package(s).

  2. Run the development server:

    # Run all packages in watch mode
pnpm dev

# Run a specific package
pnpm --filter @formkit-gov/react dev

  3. Test your changes:

    # Run all tests
pnpm test

# Run tests for a specific package
pnpm --filter @formkit-gov/react test

# Run tests in watch mode
pnpm test:watch

  4. Ensure linting passes:

    pnpm lint
pnpm typecheck

  5. Format your code:

    pnpm format

Commit Guidelines

We follow Conventional Commits. Each commit message should have a type, optional scope, and description.

Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, semicolons, etc.)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding or updating tests
  • build: Build system changes
  • ci: CI/CD changes
  • chore: Other changes (dependencies, configs)
  • revert: Reverting a previous commit

Scopes

  • core, react, store, wizard, openapi, validators, test-utils
  • docs, storybook, playground
  • deps, release, repo

Examples

feat(react): add TextInputField component

fix(core): correct SSN regex pattern for edge cases

docs(wizard): add save-in-progress guide

chore(deps): update zod to v3.23

Pull Request Process

  1. Create a changeset if your PR includes user-facing changes:

    pnpm changeset

    Follow the prompts to describe your changes.

  2. Update documentation if needed.

  3. Ensure all checks pass:

    • Linting
    • Type checking
    • Tests
    • Build

  4. Submit your PR with a clear title and description.

  5. Address review feedback promptly.

PR Title Format

Follow the same format as commit messages:

<type>(<scope>): <description>

PR Description Template

Your PR description should include:

  • Summary of changes
  • Related issue(s)
  • Testing performed
  • Screenshots (for UI changes)
  • Breaking changes (if any)

Testing

Running Tests

# All tests
pnpm test

# With coverage
pnpm test:coverage

# Watch mode
pnpm test:watch

# Specific package
pnpm --filter @formkit-gov/react test

Writing Tests

  • Place test files next to the source files with .test.ts or .test.tsx extension.
  • Use descriptive test names.
  • Test both happy paths and edge cases.
  • Include accessibility tests for components.

Example:

import { describe, it, expect } from 'vitest';
import { createSSNSchema } from './ssn';

describe('createSSNSchema', () => {
  const schema = createSSNSchema();

  it('validates correctly formatted SSN', () => {
    expect(schema.safeParse('123-45-6789').success).toBe(true);
  });

  it('rejects SSN without dashes', () => {
    const result = schema.safeParse('123456789');
    expect(result.success).toBe(false);
  });

  it('provides user-friendly error message', () => {
    const result = schema.safeParse('invalid');
    expect(result.error?.issues[0].message).toContain('Social Security');
  });
});

Documentation

Package Documentation

Each package should have:

  • README.md with usage examples
  • JSDoc comments for public APIs
  • Storybook stories for components

Docs Site

Internal documentation is in the docs/ directory. For package usage documentation, see each package's README.

Questions?

If you have questions, feel free to:

Thank you for contributing!