= Contributing to Rhodium Pipeline Template
:toc: macro
:toc-title: Contents
:toclevels: 2
:sectnums:
:icons: font

Thank you for your interest in contributing to Rhodium Pipeline Template!

toc::[]

== Code of Conduct

This project adheres to the https://www.contributor-covenant.org/version/2/1/code_of_conduct/[Contributor Covenant Code of Conduct]. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

See link:../CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md] for the full text.

== How to Contribute

=== Reporting Bugs

Before submitting a bug report:

1. *Check existing issues* — The bug may already be reported
2. *Verify reproduction* — Ensure the bug is reproducible
3. *Collect information* — Gather version numbers, error messages, and steps

*Bug Report Template:*

[source,markdown]
----
## Description
[Clear description of the bug]

## Steps to Reproduce
1. Step one
2. Step two
3. ...

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Environment
- Template version: [e.g., 1.0.0]
- Rust version: [e.g., 1.80.0]
- OS: [e.g., Ubuntu 24.04]

## Additional Context
[Any other relevant information]
----

=== Suggesting Enhancements

Enhancement suggestions are welcome! Please:

1. *Check the roadmap* — See link:../V1_ROADMAP.md[V1_ROADMAP.md] for planned features
2. *Search existing issues* — Avoid duplicates
3. *Provide context* — Explain the use case and benefit

=== Pull Requests

==== Before You Start

1. *Open an issue first* — Discuss significant changes before implementing
2. *Check the language policy* — See `.claude/CLAUDE.md` for allowed technologies
3. *Review the architecture* — Understand the existing patterns

==== Development Setup

[source,bash]
----
# Clone the repository
git clone https://github.com/hyperpolymath/rhodium-pipeline.git
cd rhodium-pipeline

# Install dependencies
cargo install cargo-generate just nickel-lang-cli

# Run checks
just check-deps  # Verify toolchain
just lint        # Code quality
just test        # Run tests
----

==== Making Changes

1. *Create a feature branch:*
+
[source,bash]
----
git checkout -b feature/your-feature-name
----

2. *Make your changes* following the style guidelines below

3. *Test your changes:*
+
[source,bash]
----
# Generate a test project
cargo generate --path ./template --name test-project

# Verify it compiles
cd test-project && cargo check
----

4. *Commit with clear messages:*
+
[source,bash]
----
git commit -m "feat: add XYZ support

- Detailed explanation of changes
- Any breaking changes noted"
----

5. *Push and create PR:*
+
[source,bash]
----
git push origin feature/your-feature-name
----

== Style Guidelines

=== Commit Messages

Follow https://www.conventionalcommits.org/[Conventional Commits]:

[source]
----
type(scope): description

[optional body]

[optional footer]
----

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

Examples:

* `feat(proofs): add monotonicity theory`
* `fix(template): correct checksum computation`
* `docs(quickstart): clarify deterministic mode`

=== Rust Code

* Follow https://rust-lang.github.io/api-guidelines/[Rust API Guidelines]
* Run `cargo fmt` before committing
* Run `cargo clippy` and address warnings
* Write documentation comments for public items

=== Isabelle Theories

* Follow Isabelle/HOL conventions
* Include theory header comments
* Document lemmas and theorems
* Use structured proofs (Isar) over apply scripts

=== Documentation

* Use AsciiDoc for documentation (`.adoc`)
* Keep line length under 80 characters where practical
* Include code examples where helpful
* Update the table of contents if adding sections

== Language Policy

This project follows the Hyperpolymath language policy:

=== Allowed

* *Rust* — Primary implementation
* *ReScript* — Web/UI components (not TypeScript)
* *Deno* — JavaScript runtime (not Node.js)
* *Isabelle/HOL* — Formal proofs
* *Nickel* — Configuration
* *Guile Scheme* — Scripting
* *Bash/POSIX Shell* — Automation

=== Not Allowed

* TypeScript (use ReScript)
* Node.js/npm (use Deno)
* Go (use Rust)
* Python (except SaltStack)
* Java/Kotlin/Swift (use Rust/Tauri)

See link:../.claude/CLAUDE.md[CLAUDE.md] for the full policy.

== Testing

=== Template Tests

[source,bash]
----
# Validate cargo-generate template
cargo generate --path ./template --name test-output \
  --define project_name=test_output \
  --define ProjectName=TestOutput \
  --define PROJECT_NAME=TEST_OUTPUT \
  --define description="Test project"

# Verify generated project compiles
cd test-output && cargo check
----

=== Proof Verification

[source,bash]
----
# Check Isabelle theories typecheck
# (Requires Isabelle installation)
isabelle build -d template/*/proofs/ -n
----

== Review Process

1. *Automated checks* — CI must pass (linting, formatting, tests)
2. *Maintainer review* — At least one maintainer approval required
3. *Documentation* — Significant changes need documentation updates
4. *CHANGELOG* — User-facing changes should update CHANGELOG

== Recognition

Contributors are recognized in:

* The project's contributor list
* Release notes for significant contributions
* CITATION.cff for academic acknowledgment

== Getting Help

* *Questions:* Open a discussion or issue
* *Real-time:* [Community channels if available]
* *Documentation:* See link:HANDOVER.adoc[HANDOVER.adoc] for methodology details

== License

By contributing, you agree that your contributions will be licensed under the project's dual license: MIT OR PMPL-1.0-or-later.

See link:LICENSING.adoc[LICENSING.adoc] for details.

---

Thank you for contributing to Rhodium Pipeline Template! 🎉
