Skip to content
This repository was archived by the owner on Mar 9, 2026. It is now read-only.

CONTRIBUTING.md

Latest commit

 

History

History
179 lines (115 loc) · 4.6 KB

CONTRIBUTING.md

File metadata and controls

179 lines (115 loc) · 4.6 KB

Contributing to safe-formdata

Thank you for your interest in contributing to safe-formdata!

Before You Start

  1. README.md: Understand the design principles and what safe-formdata is (and isn't)
  2. AGENTS.md: Review the non-negotiable implementation rules
  3. Design decisions (Why not?): Understand why certain features are intentionally excluded

Critical: If your contribution makes the parser smarter, more convenient, or more opinionated, it likely violates the boundary and will be rejected.

Development Setup

Prerequisites

  • Node.js ^20.19.0 || >= 22.12.0
  • Package manager: Bun

This project uses Bun for development. Other package managers are not supported.

Installation

git clone https://github.com/roottool/safe-formdata.git
cd safe-formdata
bun install

Development Workflow

bun run dev          # Watch mode for building
bun run test:watch   # Watch mode for testing

Project Philosophy

Core Principles (from README.md)

  • 🧱 Keys are opaque: Never interpret key naming conventions
  • 🚫 No silent fixes: Report issues, never correct them
  • ⚖️ Parsing is not validation: Schema logic belongs outside the boundary
  • 🔒️ Security over convenience: Surface unsafe input explicitly

What We Will NOT Accept

Features that violate these principles:

  • Structural inference (arrays, objects, nested data)
  • Duplicate key resolution (first-wins, last-wins, merging)
  • Value validation or type coercion
  • Configuration options or flags
  • Framework-specific behavior
  • Performance optimizations that compromise correctness

See AGENTS.md: Non-goals for the complete list.

Making Changes

1. Check AGENTS.md First

Before implementing:

  1. Confirm alignment with README.md design principles
  2. Apply AGENTS.md technical constraints
  3. If unsure, open an issue for discussion

2. Code Quality Requirements

Run these commands before submitting:

bun run check:source # Linting and formatting must pass
bun run check:type:source   # TypeScript type checking must pass
bun run test         # All tests must pass
bun run build        # Build must succeed

For local validation before pushing (mimics publish workflow):

bun run prepare:publish     # Runs all checks: type checking, tests, build, package validation

3. Testing

  • Write tests for all new functionality
  • Maintain full coverage for boundary and security-critical paths
  • Test security constraints (forbidden keys, prototype pollution)
bun run test:coverage   # View coverage report

4. Security Considerations

Mandatory security rules (AGENTS.md)

  • Use Object.create(null) for parsed data (no prototype)
  • Reject forbidden keys: __proto__, constructor, prototype
  • Never throw for input-derived errors (return ParseResult with issues)

Pull Request Guidelines

PR Checklist

Before submitting a PR:

  • Read README.md design principles
  • Read AGENTS.md implementation rules
  • Confirmed change does not violate the boundary
  • Added tests for new functionality
  • Linting and formatting passes (bun run check:source)
  • Type checking passes (bun run check:type:source)
  • All tests pass (bun run test)
  • Build succeeds (bun run build)

PR Description

Include the following:

  1. Problem: What issue does this solve?
  2. Solution: How does this maintain the boundary?
  3. AGENTS.md compliance: Which rules does this follow?
  4. Tests: What test cases were added?

Review Process

PRs are evaluated against:

  1. Alignment with design principles (README.md)
  2. Compliance with technical rules (AGENTS.md)
  3. Review rule of thumb: Does it make the parser smarter/more convenient? → Likely rejected

Issue Guidelines

Before Opening an Issue

  1. Feature requests: Check README.md: Design decisions (Why not?) first
  2. Bug reports: Ensure it's a boundary violation, not expected behavior

Feature Requests

Most feature requests will be declined because they violate the boundary.

Acceptable: Bugs in boundary enforcement, security issues, documentation improvements Not acceptable: Convenience features, structural inference, schema validation

Security Issues

For security vulnerabilities, please open an issue or contact the maintainer directly.

Questions?

  • Open an issue for discussion
  • Reference AGENTS.md for implementation questions
  • Reference README.md for design philosophy questions

License

By contributing, you agree that your contributions will be licensed under the MIT License.