Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
193 lines (145 loc) · 4.96 KB

CONTRIBUTING.md

File metadata and controls

193 lines (145 loc) · 4.96 KB

Contributing to rescript-signals

Thank you for your interest in contributing to rescript-signals! This document provides guidelines and instructions for contributing.

Development Setup

  1. Fork and clone the repository
  2. Install dependencies: 
    npm install
  3. Build the project: 
    npm run build
  4. Run tests: 
    npm test

Commit Convention

This project follows Conventional Commits and enforces the 50/72 rule:

  • Subject line: Maximum 50 characters
  • Body lines: Maximum 72 characters per line
  • Footer lines: Maximum 72 characters per line

Please read our Commit Convention Guide for detailed information.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Commit Types

  • feat: New feature (minor version bump)
  • fix: Bug fix (patch version bump)
  • perf: Performance improvement (patch version bump)
  • refactor: Code refactoring (patch version bump)
  • revert: Revert previous commit (patch version bump)
  • docs: Documentation changes (no version bump)
  • style: Code style changes (no version bump)
  • test: Test changes (no version bump)
  • build: Build system changes (no version bump)
  • ci: CI changes (no version bump)
  • chore: Other changes (no version bump)

Breaking Changes

For major version bumps, add BREAKING CHANGE: in the footer or ! after type:

feat!: remove deprecated API

BREAKING CHANGE: The old API has been completely removed.
Users should migrate to the new API.

Reporting Issues

When reporting bugs or issues:

  1. Provide a clear description of the problem
  2. Include a test case reproducing the issue if possible: 
    test("demonstrates the bug", () => {
  let signal = Signal.make(0)
  let computed = Computed.make(() => Signal.get(signal) * 2)
  Signal.set(signal, 5)
  // Expected: 10, Actual: 0
  assertEqual(Signal.peek(computed), 10, ~message="Computed should update")
})
  3. Describe the expected vs actual behavior
  4. Include relevant environment details if applicable

A reproducible test case helps us understand and fix the issue faster!

Pull Request Process

  1. Create a feature branch from main
  2. Make your changes
  3. Ensure all tests pass: npm test
  4. Ensure code builds: npm run build
  5. Commit using conventional commits
  6. Push to your fork
  7. Create a pull request

PR Requirements

  • All tests must pass
  • All commits must follow conventional commit format
  • Code must build successfully
  • Include tests for new features or bug fixes
  • Update documentation if needed
  • Include test cases showing edge cases or scenarios that needed fixing (highly encouraged)

Testing

We use a simple custom test framework. Tests are located in the tests/ directory.

Running Tests

npm test

Writing Tests

See existing tests in tests/ for examples:

open TestFramework
open Signals

let tests = suite(
  "My Feature Tests",
  [
    test("should do something", () => {
      let signal = Signal.make(42)
      assertEqual(Signal.peek(signal), 42, ~message="Should equal 42")
    }),
  ],
)

Writing Edge Case Tests

When fixing bugs or adding features, include tests that demonstrate:

  • The specific scenario that was broken:

    test("computed updates when last subscriber removed during rerun", () => {
  let base = Signal.make(0)
  let computed = Computed.make(() => Signal.get(base) * 2)
  let cleanup = ref(None)

  let _effect = Effect.make(() => {
    if Signal.get(base) > 5 {
      // Stop reading computed after base > 5
      ()
    } else {
      ignore(Signal.get(computed))
    }
  })

  Signal.set(base, 10) // Computed should be disposed here
  assertTrue(true, ~message="Should not crash on disposal")
})

  • Boundary conditions: Empty inputs, zero values, maximum values

  • Error conditions: Invalid states, exceptions, resource cleanup

  • Race conditions: Concurrent updates, nested effects, reentrant calls

  • Performance considerations: Large data sets, deep nesting, many subscribers

Good test cases make the codebase more robust and prevent regressions!

Release Process

Releases are automated using semantic-release:

  1. Commits to main trigger the release workflow
  2. Semantic-release analyzes commit messages
  3. Version is bumped based on commit types
  4. CHANGELOG.md is updated
  5. Package is published to npm
  6. GitHub release is created

Version Bumping

  • feat: Minor version bump (0.x.0)
  • fix, perf, refactor, revert: Patch version bump (0.0.x)
  • BREAKING CHANGE: Major version bump (x.0.0)
  • docs, style, test, build, ci, chore: No version bump

Code Style

  • Follow existing code patterns
  • Use ReScript best practices
  • Keep functions small and focused
  • Add comments for complex logic

Questions?

Feel free to open an issue for any questions or concerns.