// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2024-2025 Ehsaneddin Asgari and Contributors
= Contributing to 1000Langs
:toc:
:toclevels: 3
:icons: font

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

[source,bash]
----
# 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

[source,bash]
----
# 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

[source,bash]
----
# 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:

[source]
----
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:

[source]
----
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

[source,bash]
----
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

[source,rescript]
----
// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2024-2025 Ehsaneddin Asgari 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

[source,rescript]
----
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

[source,markdown]
----
## 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 link:SECURITY.md[SECURITY.md] 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!
