Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
345 lines (204 loc) · 6.46 KB

CONTRIBUTING.md

File metadata and controls

345 lines (204 loc) · 6.46 KB
Raw

Contributing to 1000Langs

Thank you for your interest in contributing to 1000Langs! This document provides guidelines and information for contributors.

Tri-Perimeter Contribution Framework (TPCF)

This project uses a graduated trust model for contributions:

Perimeter 1: Core

  • Who: Project maintainers only

  • Access: Direct commit to main branch

  • Scope: Architecture decisions, security-critical code, release management

  • Review: Self-review with documentation

Perimeter 2: Expert

  • Who: Trusted contributors with demonstrated expertise

  • Access: Protected branches, requires 1 maintainer review

  • Scope: Feature development, complex bug fixes, performance optimizations

  • Review: Code review by Perimeter 1 member

Perimeter 3: Community

  • Who: All contributors

  • Access: Fork and pull request

  • Scope: Bug fixes, documentation, tests, minor features

  • Review: Code review by Perimeter 2+ member

Getting Started

Prerequisites

  • Node.js 20+

  • Just command runner

  • Nix (recommended) or npm

  • Git

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/1000Langs.git
cd 1000Langs

# Add upstream remote
git remote add upstream https://github.com/Hyperpolymath/1000Langs.git

# Enter development environment
nix develop  # or: npm install

# Run tests to verify setup
just test

Development Workflow

1. Create a Branch

# Update main
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

2. Make Changes

  • Write code following the style guide

  • Add tests for new functionality

  • Update documentation as needed

  • Ensure SPDX headers are present

3. Test Your Changes

# Run all checks
just check

# Or individually:
just lint        # Check code style
just typecheck   # Type checking
just test        # Run tests
just prove       # Verify proofs

4. Commit Your Changes

We follow conventional commits:

type(scope): description

[optional body]

[optional footer]

Types:

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation changes

  • style: Code style changes (formatting, etc.)

  • refactor: Code refactoring

  • test: Adding or updating tests

  • chore: Maintenance tasks

  • perf: Performance improvements

  • proof: Proof additions or updates

Example:

feat(crawler): add support for ebible.org source

Implements the eBible crawler with support for USFM and USX formats.
Includes rate limiting and retry logic.

Closes #42

5. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Code Style

ReScript

  • Use descriptive module and function names

  • Prefer pattern matching over if/else chains

  • Use labeled arguments for functions with multiple parameters

  • Add SPDX headers to all source files

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell and Contributors

/**
 * Module documentation goes here.
 */
module MyModule = {
  // ...
}

Documentation

  • Use AsciiDoc for documentation (not Markdown, except SECURITY.md)

  • Include code examples where helpful

  • Keep documentation close to the code

Testing Guidelines

Unit Tests

  • Test one thing per test

  • Use descriptive test names

  • Mock external dependencies

describe("Iso639.Validation", () => {
  test("isValidIso639_3 returns true for valid codes", () => {
    expect(Iso639.Validation.isValidIso639_3("eng"))->toBe(true)
  })

  test("isValidIso639_3 returns false for invalid codes", () => {
    expect(Iso639.Validation.isValidIso639_3("english"))->toBe(false)
  })
})

Integration Tests

  • Test interactions between modules

  • Use realistic test data

  • Clean up after tests

Proof Tests

  • Verify mathematical properties

  • Document proof obligations

  • Link to formal specifications

Pull Request Guidelines

Before Submitting

  • All tests pass (just test)

  • Code is formatted (just format)

  • No linting errors (just lint)

  • Types check (just typecheck)

  • Documentation updated if needed

  • SPDX headers present on new files

  • Conventional commit messages used

PR Description Template

## Summary

Brief description of changes.

## Changes

- Change 1
- Change 2

## Testing

How was this tested?

## Checklist

- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] CHANGELOG.md updated

Review Process

  1. Automated checks must pass

  2. At least one approval from appropriate perimeter

  3. All comments addressed

  4. Squash merge preferred

Reporting Issues

Bug Reports

Include:

  • ReScript/Node.js version

  • Operating system

  • Steps to reproduce

  • Expected vs actual behavior

  • Error messages/logs

Feature Requests

Include:

  • Use case description

  • Proposed solution

  • Alternatives considered

  • Willingness to implement

Security Issues

Do not report security vulnerabilities through public issues.

See SECURITY for responsible disclosure guidelines.

License

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

Questions?

  • Open a discussion on GitHub

  • Check existing issues and discussions

  • Review the documentation

Thank you for contributing!

Signed commits

Every commit that reaches the default branch must be signed; a ruleset refuses unsigned pushes. Estate policy: SIGNING-POLICY.

  • People and interactive agents sign with an SSH key registered on GitHub as a signing key (gpg.format=ssh, user.signingkey=<key>.pub, commit.gpgsign=true). The committer email must be verified on that account.
  • Apps, bots and workflows never git push local commits. They write through the API (createCommitOnBranch or the estate signed-push action) so that GitHub signs each commit.
  • Merge PRs with squash. The ruleset checks every commit on the PR branch, not just the result, so one unsigned commit blocks the merge. Re-create such a branch with signed commits (git cherry-pick -S) and open a new PR. Rebase-merge replays commits unsigned and is disabled.