CONTRIBUTING.adoc

Contributing to rescript-tea

Table of Contents

• Getting Started
  • Prerequisites
  • Development Setup
  • Using Nix
• Tri-Perimeter Contribution Framework (TPCF)
  • Perimeter 1 (Core)
  • Perimeter 2 (Expert)
  • Perimeter 3 (Community)
• How to Contribute
  • Reporting Bugs
  • Suggesting Features
  • Submitting Pull Requests
  • Code Style
  • SPDX Headers
  • Commit Messages
• Testing
  • Writing Tests
• Documentation
• Code of Conduct
• License
• Questions?

Thank you for your interest in contributing to rescript-tea!

Getting Started

Prerequisites

• Node.js 18+

• npm or pnpm

• ReScript compiler (installed via npm)

• Nix (optional, for reproducible development environment)

Development Setup

# Clone the repository
git clone https://github.com/Hyperpolymath/rescript-tea.git
cd rescript-tea

# Install dependencies
npm install

# Build the project
npm run build

# Run in watch mode
npm run dev

Using Nix

# Enter development shell
nix develop

# Or use direnv
direnv allow

Tri-Perimeter Contribution Framework (TPCF)

This project follows the RSR Tri-Perimeter Contribution Framework:

Perimeter 1 (Core)

Maintainers only. Changes to:

• Build system configuration

• Core runtime (Tea_App.res)

• Release management

• Security-critical code

Perimeter 2 (Expert)

Trusted contributors. Changes to:

• Protocol extensions

• New subscription types

• Performance optimizations

• API design changes

Perimeter 3 (Community)

Open participation:

• Documentation improvements

• Bug fixes with tests

• New examples

• Test coverage

• Issue triage

How to Contribute

Reporting Bugs

1. Check existing issues to avoid duplicates

2. Create a new issue with:

   • Clear, descriptive title

   • Steps to reproduce

   • Expected vs actual behavior

   • ReScript/Node.js versions

   • Minimal reproduction code

Suggesting Features

1. Open a discussion or issue

2. Describe the use case

3. Explain why existing features don’t suffice

4. Propose an API design (if applicable)

Submitting Pull Requests

1. Fork the repository

2. Create a feature branch: git checkout -b feature/my-feature

3. Make your changes

4. Add/update tests

5. Ensure all tests pass: npm test

6. Add SPDX headers to new files

7. Update documentation if needed

8. Submit a pull request

Code Style

• Follow existing code patterns

• Use meaningful variable names

• Keep functions small and focused

• Add type annotations for public APIs

• Document complex logic with comments

SPDX Headers

All source files must include SPDX headers:

// SPDX-License-Identifier: PMPL-1.0-or-later
// SPDX-FileCopyrightText: 2024 Your Name

Commit Messages

Follow conventional commits:

type(scope): description

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

Examples:

feat(cmd): add Cmd.debounce for rate-limited commands
fix(sub): prevent memory leak in subscription cleanup
docs: update README with new API examples

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

Writing Tests

Use Tea_Test utilities:

// Test update function
let model = Tea_Test.simulate(
  ~init,
  ~update,
  ~msgs=[Increment, Increment, Decrement],
)
assert(model.count == 1)

// Test commands
let cmds = Tea_Test.collectCmds(~init, ~update, ~msgs=[FetchData])
assert(Belt.Array.length(cmds) > 0)

Documentation

• Update README.adoc for user-facing changes

• Add JSDoc comments to public functions

• Include examples for new features

• Update CHANGELOG.md

Code of Conduct

Please read and follow our Code of Conduct.

License

By contributing, you agree that your contributions will be licensed under the project’s dual MIT and Palimpsest v0.8 license.

Questions?

• Open a GitHub Discussion

• Check existing documentation

• Review closed issues/PRs

Thank you for contributing!