= Contributing to {Project Name}
:project-name: {Project Name}
:repo-url: {Repository URL – *REMINDER: Provide this for each project*}
:language: {Primary language}

== 🤝 Welcome Contributors!

Thank you for your interest in contributing to {project-name}! This document explains our **Tri-Perimeter Contribution Framework (TPCF)**, which balances architectural integrity with community involvement.

== 🎯 Core Principles

Before contributing, understand our values:

1. **Emotionally safe**: Mistakes are learning opportunities, not failures
2. **Reversible**: Every change can be undone (see link:REVERSIBILITY.md[REVERSIBILITY.md])
3. **Collaborative**: Architecture enforces cooperation over competition
4. **Rigorous**: Testing and verification are acts of care
5. **Inclusive**: Everyone can contribute at appropriate level

== 🛠️ Tri-Perimeter Contribution Framework (TPCF)

We use a graduated trust model with three perimeters. Find where you fit:

=== 🔒 Perimeter 1: Core Systems (Maintainers Only)

**Languages**: Rust, Nickel, Bash, C++, {add project-specific languages}

**Responsibilities**:

- Core runtime and critical path code
- Build orchestration (Justfile, Ninja emitters)
- Protocol emitters (`.well-known/*.json`)
- SPDX audit and licence layering
- CI/CD pipelines and containerisation
- Security-critical components

**Access**: Maintainers only

**Contribution Path**: **Closed to public.** Maintainers commit directly with full SPDX and compliance coverage.

**Why restricted?**: Architectural integrity and security require centralised oversight for foundational components.

=== 🧠 Perimeter 2: Expert Extensions (Trusted Contributors)

**Languages**: {Language}, Rust, Nickel, Bash, controlled Python

**Responsibilities**:

- Protocol extensions (e.g. consent tokens, provenance chains)
- Plugins and extensions
- Advanced features and integrations
- Compliance validators
- Performance optimisations
- Contributor onboarding flows

**Access**: Trusted contributors (must apply)

**Contribution Path**:

1. **Apply** via issue template: link:.gitlab/ISSUE_TEMPLATE/expert-contributor.yml[Expert Contributor Application]
2. **Demonstrate expertise**: Show relevant experience or previous contributions
3. **Submit MRs** under `extensions/` or `{appropriate-directory}/`
4. **Include**:
   - Unit tests (required)
   - Documentation (required)
   - Example usage (required)
   - SPDX headers (required)
   - Licence declaration (required)
5. **Review**: Core maintainers review before merge

**Requirements**:

- Familiarity with {language} and project architecture
- Understanding of RSR compliance criteria
- Commitment to testing and documentation

=== 🌱 Perimeter 3: Community Sandbox (Open to All)

**Languages**: Shell, Markdown, AsciiDoc, JSON, YAML

**Responsibilities**:

- Documentation improvements (`docs/`)
- Spec tests (`spec/`, `test/`)
- Compliance manifest proposals (`.well-known/`)
- Contributor guides
- Onboarding scripts
- Examples and tutorials
- Bug reports and feature requests

**Access**: **Open to all**

**Contribution Path**:

1. **Fork** the repository
2. **Clone** your fork locally
3. **Create branch**: `git checkout -b feature/your-contribution`
4. **Make changes** under:
   - `docs/` for documentation
   - `spec/` for behaviour tests
   - `.well-known/` for protocol suggestions
   - `examples/` for examples
5. **Run validation**: `just validate` locally
6. **Commit**: Follow commit conventions (see below)
7. **Push**: `git push -u origin feature/your-contribution`
8. **Submit MR**: Link to link:{repo-url}/-/merge_requests/new[Create Merge Request]
9. **CI validation**: Automated checks for SPDX headers, schema compliance, formatting

**This is the best place to start!** No prior approval needed.

== 🚀 Getting Started

=== Prerequisites

*REMINDER: List actual prerequisites.*

- {Primary language} compiler/interpreter
- `just` command runner
- Git (obviously)
- Familiarity with {project-name} architecture

=== Local Setup

[source,bash]
----
# 1. Fork the repository (via GitLab web UI)

# 2. Clone your fork
git clone {your-fork-url}
cd {project-name}

# 3. Add upstream remote
git remote add upstream {repo-url}

# 4. Install dependencies
just setup

# 5. Build the project
just build

# 6. Run tests
just test

# 7. Verify everything works
just validate
----

== 📋 Contribution Workflow

=== 1. Find an Issue

- **Good first issues**: link:{repo-url}/-/issues?label_name%5B%5D=good+first+issue[Start here]
- **Documentation**: link:{repo-url}/-/issues?label_name%5B%5D=documentation[Docs needed]
- **Help wanted**: link:{repo-url}/-/issues?label_name%5B%5D=help+wanted[Contributions welcome]

Or propose your own via link:{repo-url}/-/issues/new[New Issue].

=== 2. Create a Branch

[source,bash]
----
# Update your fork
git fetch upstream
git checkout main
git merge upstream/main

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

# Or for fixes:
# git checkout -b fix/issue-number-description
----

=== 3. Make Changes

Follow our coding conventions (see below).

=== 4. Test Locally

[source,bash]
----
# Run full test suite
just test

# Run specific tests
just test-unit
just test-integration

# Check code style
just lint

# Validate compliance
just validate
----

=== 5. Commit

Follow **Conventional Commits**:

[source,bash]
----
# Format: <type>(<scope>): <subject>
git commit -m "feat(parser): add support for nested structures"
git commit -m "fix(cli): handle empty input gracefully"
git commit -m "docs(README): clarify installation steps"
git commit -m "test(integration): add tests for error handling"
----

**Types**:

- `feat:` New features
- `fix:` Bug fixes
- `docs:` Documentation changes
- `refactor:` Code refactoring
- `test:` Test additions/changes
- `security:` Security improvements
- `perf:` Performance optimisations
- `build:` Build system changes
- `ci:` CI/CD changes

### 6. Push

[source,bash]
----
git push -u origin feature/descriptive-name
----

=== 7. Create Merge Request

1. Go to link:{repo-url}/-/merge_requests/new[New Merge Request]
2. Select your branch
3. Fill out the template (description, tests, checklist)
4. Assign labels (if applicable)
5. Submit

=== 8. Address Review Feedback

- Respond to comments
- Make requested changes
- Push updates to the same branch (MR updates automatically)
- Mark conversations as resolved when addressed

== 📐 Coding Conventions

=== Code Style

- **Indentation**: 2 spaces (Rust: 4 spaces)
- **Line length**: 100 characters max (120 for comments)
- **Naming**:
  - Functions: `snake_case` ({language}-specific)
  - Types: `PascalCase`
  - Constants: `SCREAMING_SNAKE_CASE`

=== SPDX Headers

**All source files** must have SPDX headers:

[source,{language}]
----
// SPDX-License-Identifier: MIT AND Palimpsest-0.8
// SPDX-FileCopyrightText: {Year} {Your Name} <{your-email}>
----

For Ada:
[source,ada]
----
-- SPDX-License-Identifier: MIT AND Palimpsest-0.8
-- SPDX-FileCopyrightText: {Year} {Your Name} <{your-email}>
----

=== Documentation

- **Public APIs**: Documented in code (docstrings/comments)
- **Modules**: README or module-level documentation
- **AsciiDoc preferred** for structured docs
- **Markdown acceptable** for simple docs

=== Testing

- **Unit tests**: For all new functions/modules
- **Integration tests**: For feature interactions
- **Property-based tests**: For complex logic
- **Examples**: Runnable examples in `examples/`

== 🔁 Lifecycle & Automation

=== CI/CD

All contributions are automatically tested:

- **Linting**: Code style checks
- **Testing**: Full test suite
- **Security**: Dependency audit, secret scanning
- **SPDX**: Header validation
- **Licence**: Compatibility checks
- **Documentation**: Link validation (Lychee)

CI must pass before merge.

=== Robot Vacuum Cleaner (RVC)

Pre-commit hooks automatically run:

- Format code
- Fix whitespace
- Update SPDX headers (if missing)
- Run linters

**Bypass only when necessary**:
[source,bash]
----
git commit --no-verify  # Use sparingly!
----

== 🤝 Code of Conduct

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

**In summary**:

- **Be respectful**: Treat all contributors with dignity
- **Be constructive**: Criticism should be helpful, not harmful
- **Be inclusive**: Welcome people of all backgrounds
- **Respect boundaries**: Honour attribution and licences
- **No harassment**: Zero tolerance for abusive behaviour

== 🎓 Learning Resources

=== Project-Specific

- **Architecture**: link:docs/architecture/[Architecture docs]
- **API Reference**: link:reference/[API reference]
- **Examples**: link:examples/[Example code]

=== Language-Specific

*REMINDER: Add language-specific learning resources.*

- **{Language} Guide**: {link}
- **{Language} Best Practices**: {link}

=== RSR/CCCP Philosophy

- **CLAUDE.md**: link:CLAUDE.md[Complete RSR specification]
- **Reversibility**: link:REVERSIBILITY.md[Why we can undo everything]
- **CCCP Manifesto**: link:CCCP-MANIFESTO.md[Philosophical foundation]

== 📊 Contribution Metrics

We track contributions transparently:

- **Contributors**: All contributors listed in link:CONTRIBUTORS.md[CONTRIBUTORS.md]
- **Attribution**: Git history preserves authorship
- **Recognition**: Security researchers in link:SECURITY.md[Security Hall of Fame]

== ❓ Questions?

- **General questions**: link:{repo-url}/-/discussions[Discussions]
- **Bug reports**: link:{repo-url}/-/issues[Issues]
- **Security issues**: link:SECURITY.md[Security policy]
- **Licence questions**: link:LICENSE-MIT[MIT] or link:LICENSE-PALIMPSEST[Palimpsest]

== 🙏 Thank You!

Every contribution, no matter how small, makes {project-name} better. We appreciate your time and effort!

---

*"Community over ego. Collaboration over competition."*

— The Rhodium Standard
