// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2025 The Rhodium Standard Contributors
= Contributing Guide
:toc: left
:toclevels: 4
:icons: font
:sectanchors:
:experimental:

Thank you for your interest in contributing to the Rhodium Standard Repositories! This guide will help you understand how to contribute effectively.

== Quick Start

[source,bash]
----
# 1. Fork the repository on GitLab
# 2. Clone your fork
git clone https://gitlab.com/YOUR-USERNAME/rhodium-standard-repositories.git
cd rhodium-standard-repositories

# 3. Enter development environment
nix develop

# 4. Create a branch
git checkout -b feature/your-feature-name

# 5. Make your changes

# 6. Validate compliance
just validate

# 7. Commit with SPDX headers
git add .
git commit -m "feat: your descriptive commit message"

# 8. Push and create merge request
git push origin feature/your-feature-name
# Then open MR on GitLab
----

== Before You Begin

Please read:

* link:README.adoc[README.adoc] - Project overview
* link:CODE_OF_CONDUCT.adoc[CODE_OF_CONDUCT.adoc] - Community standards
* link:GOVERNANCE.adoc[GOVERNANCE.adoc] - Decision-making process
* link:SECURITY.md[SECURITY.md] - Security policies

== Tri-Perimeter Contribution Framework (TPCF)

The Rhodium Standard uses a graduated trust model. Your contribution scope depends on your role, but *everyone can contribute* at some level!

=== 🌱 Perimeter 3: Community Sandbox (You Are Here!)

*Access*: **Open to all** - This is where you start!

*What You Can Contribute*:
* Documentation improvements (fix typos, clarify explanations, add examples)
* Translations (future: help make RSR accessible in other languages)
* Bug reports and feature requests
* Example repositories (new examples showing RSR in action)
* Tutorials and guides (how-to articles, videos, workshops)
* Testing and QA (try things and report what breaks)
* Spec tests and compliance proposals (suggest improvements to RSR standards)

*Languages You Can Use*: Any! Shell, Markdown, AsciiDoc, JSON, Nickel, Rust, Elixir, Haskell, ReScript, Ada, whatever fits your contribution.

*Process*:
1. Fork → make changes → validate locally → create merge request
2. CI runs automatically to check formatting, SPDX headers, links
3. Maintainer reviews (usually within 1 week)
4. Address feedback, get approval, merged!

*No prior permission needed* - just follow the guidelines below and go for it!

=== 🧠 Perimeter 2: Expert Extensions

*Access*: Trusted contributors (3+ months of contributions, demonstrated expertise)

*What Trusted Contributors Can Do*:
* Approve merge requests in their domain (after review by another trusted contributor or maintainer)
* Work on example repositories beyond minimal
* Create repository templates
* Extend protocol validators
* Build testing infrastructure
* Contribute to DocGementer tooling

*How to Become a Trusted Contributor*:
See link:MAINTAINERS.adoc[MAINTAINERS.md] for the progression path. Typically:
* 20+ merged contributions OR deep expertise in specific area
* 3+ months of consistent activity
* Positive community interactions
* Self-nominate or get nominated via issue

=== 🔒 Perimeter 1: Core Systems

*Access*: Core maintainers only

*Scope*:
* Audit system (`rsr-audit.sh`)
* Build systems and CI/CD core
* Main documentation (README, GOVERNANCE, SECURITY)
* Haskell registry (when implemented)

*Note*: This perimeter is closed to ensure architectural integrity, but you can propose changes via issues and the core team may implement them.

== Types of Contributions

=== 📝 Documentation

Documentation improvements are *always* welcome!

==== What to Document

* Fix typos and grammatical errors
* Clarify confusing explanations
* Add missing information
* Improve examples
* Add diagrams and visualizations
* Write tutorials for specific use cases
* Translate to other languages (future)

==== Documentation Standards

* **Format**: AsciiDoc for governance docs (`.adoc`), Markdown for guides (`.md`)
* **Links**: All links must be valid (validated by `lychee`)
* **Images**: All images must have alt text for accessibility
* **SPDX**: Add SPDX headers to all documentation files
* **Clarity**: Write for non-native English speakers (simple, clear language)

==== Example Documentation Contribution

[source,asciidoc]
----
// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2025 Your Name <your.email@example.com>
= How to Use RSR with Python Projects
:toc: left

== Overview

Even though RSR prefers Rust/Elixir/Haskell, you can apply RSR
principles to Python projects...
----

=== 🐛 Bug Reports

Found a bug? Thank you for helping us improve!

==== Before Filing a Bug

1. **Search existing issues** - Maybe it's already reported?
2. **Reproduce on latest version** - Is it still happening?
3. **Simplify** - Can you create a minimal reproduction?

==== What to Include

Use our bug report template (automatically loaded when you create an issue):

* **Description**: Clear explanation of the problem
* **Steps to Reproduce**: Numbered steps we can follow
* **Expected Behavior**: What should happen
* **Actual Behavior**: What actually happens
* **Environment**: OS, Nix version, tool versions
* **Logs**: Relevant error messages or output
* **Minimal Reproduction**: Smallest possible example

==== Example Bug Report

[source,markdown]
----
**Bug**: rsr-audit.sh crashes when repository has no .gitignore

**Steps**:
1. Clone fresh repo without .gitignore
2. Run `./rsr-audit.sh .`
3. Observe crash

**Expected**: Audit should fail that check but continue

**Actual**: Script exits with error code 4

**Environment**: NixOS 23.11, Bash 5.2

**Error Log**:
```
line 245: test: .gitignore: unary operator expected
```
----

=== ✨ Feature Requests

Have an idea? We want to hear it!

==== Before Requesting a Feature

* **Check existing issues** - Maybe someone already suggested it?
* **Consider if it fits RSR philosophy** - Read CCCP-MANIFESTO.md
* **Think about alternatives** - Are there other ways to solve this?

==== What to Include

* **Problem Statement**: What problem does this solve?
* **Proposed Solution**: How would it work?
* **Alternatives Considered**: What else did you think about?
* **RSR Alignment**: How does this fit RSR principles?
* **Willing to Implement?**: Can you contribute the code?

=== 💻 Code Contributions

Ready to write code? Awesome!

==== Development Environment

[source,bash]
----
# Using Nix (recommended)
nix develop

# This gives you:
# - Rust toolchain
# - Just task runner
# - All required tools

# Verify setup
just --version
rustc --version
nix --version
----

==== Before Writing Code

1. **Open an issue first** - Discuss the approach before implementing
2. **Wait for approval** - Especially for large changes
3. **Read relevant code** - Understand existing patterns
4. **Check test coverage** - We expect tests for new features

==== Code Standards

===== Language Preferences

Per RSR standards, prefer in this order:

1. **Rust** - For systems programming, CLI tools, performance-critical code
2. **Elixir** - For services, APIs, fault-tolerant systems
3. **ReScript** - For web frontends (not applicable here, but for examples)
4. **Haskell** - For validators, pure functional logic
5. **Ada/SPARK** - For safety-critical, formally verified code
6. **Nickel** - For configuration and infrastructure-as-code
7. **Bash** - For simple automation (with discipline!)

❌ **Avoid**:
* JavaScript (except Deno if absolutely necessary)
* TypeScript (unsound type system)
* Python (except in SaltStack, temporary)

===== Code Style

**Rust**:
* Run `cargo fmt` before committing
* Run `cargo clippy` and fix warnings
* Follow https://rust-lang.github.io/api-guidelines/[Rust API Guidelines]

**Bash**:
* Use `shellcheck` and fix all warnings
* Quote all variables: `"$var"` not `$var`
* Use `set -uo pipefail` (not `-e` as it breaks our audit script!)

**All Languages**:
* Maximum line length: 100 characters (with exceptions for URLs)
* No trailing whitespace
* LF line endings (`.gitattributes` enforces this)
* SPDX headers on every file

===== SPDX Headers

**Required on every source file**:

[source,rust]
----
// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2025 Your Name <your.email@example.com>

// Rest of file...
----

For Markdown/AsciiDoc:
[source,markdown]
----
<!--
SPDX-License-Identifier: MPL-2.0
SPDX-FileCopyrightText: 2025 Your Name
-->
----

===== Testing Requirements

* **Unit tests**: All new functions must have tests
* **Integration tests**: Complex features need end-to-end tests
* **Coverage**: Aim for ≥80% coverage (run `just coverage`)
* **Passing CI**: All tests must pass before merge

===== Security Requirements

* **No secrets**: Never commit credentials, API keys, private keys
* **Input validation**: Validate all external input
* **Error handling**: Handle errors gracefully, no panics in libraries
* **Dependencies**: Justify any new dependencies in MR description
* **Audit**: Run `cargo audit` if adding Rust dependencies

==== Commit Message Format

We follow **Conventional Commits**:

[source]
----
<type>(<scope>): <subject>

<body>

<footer>
----

**Types**:
* `feat`: New feature
* `fix`: Bug fix
* `docs`: Documentation changes
* `test`: Test additions or fixes
* `refactor`: Code refactoring
* `perf`: Performance improvements
* `build`: Build system changes
* `ci`: CI/CD changes
* `chore`: Maintenance tasks

**Examples**:

[source,git]
----
feat(audit): add check for FUNDING.yml presence

The RSR standard now requires FUNDING.yml for funding transparency.
This adds a check to rsr-audit.sh to validate its presence.

Related: #42
----

[source,git]
----
docs(readme): fix broken link to GOVERNANCE.adoc

The link was using .md extension instead of .adoc.
----

==== Creating a Merge Request

1. **Push your branch**: `git push origin feature/your-branch`
2. **Open MR on GitLab**: Click "Create merge request"
3. **Fill out template**: Use the provided template
4. **Link issues**: Reference related issues with `#123`
5. **Mark as draft** if not ready: Add `Draft:` prefix to title
6. **Request review**: Tag relevant maintainers if known

==== MR Review Process

1. **Automated checks**: CI runs tests, linting, SPDX validation
2. **Code review**: Maintainer reviews code for quality and correctness
3. **Feedback**: You may receive requests for changes
4. **Address feedback**: Make changes, push to same branch
5. **Approval**: Once approved, maintainer merges
6. **Celebration**: Your contribution is live! 🎉

==== Review Expectations

* **Response time**: Maintainers aim for 1 week response
* **Be patient**: We're volunteers with limited time
* **Be respectful**: Reviews are about code, not about you
* **Ask questions**: If feedback is unclear, ask for clarification
* **Iterate**: Multiple rounds of review are normal

=== 🧪 Testing

Help us maintain quality by testing!

==== Manual Testing

* Try new features and report issues
* Test on different platforms (Linux, macOS, BSD)
* Test edge cases and unusual scenarios
* Verify documentation accuracy

==== Automated Testing

* Write unit tests for new code
* Add integration tests for features
* Improve test coverage for existing code
* Fix flaky tests

==== Running Tests

[source,bash]
----
# Run all tests
just test

# Run specific test file
cargo test --test audit_tests

# Run with coverage
just coverage

# Run linting
just lint
----

=== 🎨 Design Contributions

Visual design and UX improvements welcome!

* Improve documentation formatting
* Create diagrams and visualizations
* Design badges and branding (future)
* Improve CLI output readability
* Suggest UX improvements for tools

=== 🌍 Community Contributions

Help grow the community!

* Answer questions in issues
* Help newcomers get started
* Write blog posts or tutorials
* Give talks about RSR
* Share RSR on social media
* Organize meetups or workshops

== Contribution Workflow

=== Step-by-Step

1. **Find or create an issue**
   * Check existing issues first
   * Open new issue if needed
   * Wait for approval on large changes

2. **Fork and clone**
   [source,bash]
   ----
   # Fork on GitLab first, then:
   git clone https://gitlab.com/YOUR-USERNAME/rhodium-standard-repositories.git
   cd rhodium-standard-repositories
   ----

3. **Create a branch**
   [source,bash]
   ----
   git checkout -b feat/my-awesome-feature
   # Or: fix/bug-description, docs/what-changed, etc.
   ----

4. **Make changes**
   * Add SPDX headers to new files
   * Follow code style guidelines
   * Write tests for new functionality

5. **Validate locally**
   [source,bash]
   ----
   just validate    # Runs all checks
   just test        # Runs tests
   just lint        # Runs linters
   just fmt         # Formats code
   ----

6. **Commit**
   [source,bash]
   ----
   git add .
   git commit -m "feat: add awesome new feature"
   ----

7. **Push**
   [source,bash]
   ----
   git push origin feat/my-awesome-feature
   ----

8. **Create Merge Request**
   * Go to GitLab
   * Click "Create merge request"
   * Fill out template
   * Submit!

9. **Respond to feedback**
   * Address review comments
   * Push additional commits to same branch
   * Request re-review when ready

10. **Celebrate! 🎉**
    * Once merged, your contribution is part of RSR
    * You're now in git history and CONTRIBUTORS
    * Thank you!

== Common Tasks

=== Adding a New Example Repository

1. Create directory: `examples/your-example/`
2. Build RSR-compliant repo structure
3. Add `README.adoc`, `LICENSE.txt`, `SECURITY.md`, etc.
4. Achieve at least Bronze compliance (75%)
5. Document in root `README.adoc`
6. Create MR

=== Improving Documentation

1. Identify doc needing improvement
2. Make changes (keep SPDX headers!)
3. Run `just check-links` to validate links
4. Preview locally (use AsciiDoc renderer for `.adoc` files)
5. Create MR with clear description

=== Fixing a Bug

1. Reproduce the bug
2. Add a test that fails due to the bug
3. Fix the bug
4. Verify test now passes
5. Check for similar bugs elsewhere
6. Create MR

=== Adding a Feature

1. Open issue first - discuss approach
2. Wait for approval (especially for large features)
3. Implement with tests
4. Update documentation
5. Run full validation: `just validate`
6. Create MR with detailed description

== Tools and Commands

=== Just Tasks

[source,bash]
----
just --list              # Show all available tasks
just validate            # Run all validation checks
just test                # Run tests
just lint                # Run linters
just fmt                 # Format code
just audit-license       # Check SPDX headers
just check-links         # Validate documentation links
just build-examples      # Build all example repos
----

=== CI/CD

Our GitLab CI runs on every merge request:

* **Validation**: Checks RSR compliance
* **Tests**: Runs test suite
* **Linting**: Enforces code style
* **Links**: Validates all documentation links
* **SPDX**: Verifies headers on all files
* **Security**: Scans for vulnerabilities

All checks must pass before merge.

== Getting Help

=== I'm Stuck!

Don't worry - we're here to help!

* **Questions**: Open an issue with label `~question`
* **Matrix**: #rhodium-standard:matrix.org (planned)
* **Email**: rhodium-standard@proton.me

=== I'm New to Git/GitLab

No problem! Check out:

* https://docs.gitlab.com/ee/gitlab-basics/[GitLab Basics Tutorial]
* https://git-scm.com/book/en/v2[Pro Git Book]
* Ask in an issue - we love helping newcomers!

=== I'm New to Rust/Elixir/Haskell

That's okay! Contributing to documentation, testing, or examples doesn't require deep expertise. For code contributions:

* https://www.rust-lang.org/learn[Rust Learning Resources]
* https://elixir-lang.org/getting-started/introduction.html[Elixir Getting Started]
* https://www.haskell.org/documentation/[Haskell Documentation]

Or focus on areas you're comfortable with - all contributions are valuable!

== Recognition

=== How We Thank Contributors

* **Git history**: Permanent record of your contributions
* **CONTRIBUTORS**: Auto-generated list from git
* **.well-known/humans.txt**: Attribution and thanks
* **Release notes**: Significant contributions mentioned
* **MAINTAINERS.md**: Progression path to trusted contributor and maintainer
* **Social media**: We highlight great contributions (with your permission)

=== Contributor Levels

* **First-time contributor**: Welcome! Every expert was once a beginner.
* **Regular contributor** (5+ MRs): Recognized in release notes
* **Trusted contributor** (20+ MRs, 3+ months): Listed in MAINTAINERS.md, can approve MRs in your domain
* **Core maintainer** (6+ months trusted): Listed as maintainer, voting rights

See link:MAINTAINERS.adoc[MAINTAINERS.md] for details.

== Legal

=== License

By contributing, you agree that your contributions will be licensed under:

* **MIT License** - Permissive open source
* **Palimpsest License v0.8** - Ethical AI and attribution framework

See link:LICENSE.txt[LICENSE.txt] for full terms.

=== Developer Certificate of Origin (DCO)

By making a contribution, you certify that:

1. The contribution was created in whole or in part by you
2. You have the right to submit it under the project's license
3. You understand and agree the contribution is public
4. If your employer has rights to IP you create, you've received permission

We follow the https://developercertificate.org/[Developer Certificate of Origin].

=== Attribution

* Your name/email from git commits will be public
* You'll be listed in git history and CONTRIBUTORS
* You can use a pseudonym if you prefer
* You can use a privacy-preserving email (like GitLab's private email)

== Code of Conduct

All contributors must follow our link:CODE_OF_CONDUCT.adoc[Code of Conduct].

Key points:

* Be respectful and inclusive
* Welcome newcomers warmly
* Give constructive feedback
* Assume good intent
* No harassment, gatekeeping, or shaming

Violations can be reported to code-of-conduct@rhodium-standard.org

== Additional Resources

* link:README.adoc[README] - Project overview
* link:GOVERNANCE.adoc[GOVERNANCE] - How decisions are made
* link:SECURITY.md[SECURITY] - Security policies
* link:MAINTAINERS.adoc[MAINTAINERS] - Team structure
* link:CLAUDE.md[CLAUDE.md] - AI assistant guidance
* link:COMPLIANCE_CHECKLIST.md[Compliance Checklist] - RSR standards

---

**Document Version**: 1.0.0 +
**Last Updated**: 2025-11-28 +
**Maintained by**: Core Team

_"The best contribution is the one you actually make, not the perfect one you never start."_

— The Rhodium Standard

**Thank you for contributing! Together we build systems that don't decay under pressure, communities that support experimentation without shame, and infrastructure that respects human autonomy.** 🎖️
