# Contributing to indieweb-rust

Thank you for your interest in contributing to indieweb-rust! This document provides guidelines for contributing to the project.

## AI Disclosure

**Important**: If you are using **any kind of AI assistance** to contribute to indieweb-rust, it must be disclosed in the pull request.

### Requirements

When using AI tools while contributing to this project, you must:

- **Disclose in PR description**: Mention if AI tools were used and to what extent
- **Indicate scope**: Clarify how much AI assistance was involved (e.g., "AI helped with boilerplate" vs "AI wrote core logic")
- **Commit attribution**: Add `AI-Assisted-by:` trailer to commits (see [DCO.md](DCO.md#ai-generated-contributions))

### Example PR Description

> This PR adds OAuth2 support. Claude 3.5 Sonnet assisted with the PKCE 
> implementation (approximately 60% of the code).

### Why This Matters

Disclosing AI usage is a matter of respect for reviewers and maintainers. It allows them to:
- Apply appropriate scrutiny to AI-generated code
- Understand the context and limitations of the contribution
- Provide better feedback based on how the code was written

We support and encourage AI-assisted development, but transparency is essential for maintaining trust in the project.

## Developer Certificate of Origin (DCO)

This project uses the [Developer Certificate of Origin](DCO.md) to ensure contributors certify they have the right to submit their contributions.

### What This Means

Every commit must include a `Signed-off-by:` line certifying you have the right to submit the code under the project's AGPL-3.0 license.

For AI-assisted contributions, an additional `AI-Assisted-by:` line is required for transparency.

### Committing Code

#### Regular Commits

For code you wrote yourself (no AI assistance):

```bash
git commit -m "feat: add new feature" \
  -m "Signed-off-by: Your Name <your.email@example.com>"
```

#### AI-Assisted Commits

For code developed with AI tools (Claude, ChatGPT, GitHub Copilot, etc.):

```bash
git commit -m "feat: add OAuth2" \
  -m "Signed-off-by: Your Name <your.email@example.com>" \
  -m "AI-Assisted-by: Claude 3.5 Sonnet"
```

Or for multi-line commit messages:

```bash
git commit -m "feat: add OAuth2

Implemented PKCE extension for public clients with
secure token storage and automatic token refresh." \
  -m "Signed-off-by: Your Name <your.email@example.com>" \
  -m "AI-Assisted-by: Claude 3.5 Sonnet"
```

### Why This Matters

The DCO provides legal clarity about contributions:
- Confirms you have the right to contribute the code
- Creates a clear record of contribution provenance
- Required for projects with corporate contributors
- AI attribution ensures transparency about development methods

See [DCO.md](DCO.md) for the full certificate text and AI attribution requirements.

## Development Setup

### Prerequisites

- **Rust stable toolchain**: 1.93 or later
- **Components**: clippy, rust-analyzer (configured in `rust-toolchain.toml`)

Install Rust via [rustup](https://rustup.rs/):

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

### Building the Project

Build all workspace members:

```bash
cargo build
```

Build with all features (including experimental features):

```bash
cargo build --all-features
```

Build specific package:

```bash
cargo build --package indieweb
```

### Running Tests

Run all tests in the workspace:

```bash
cargo test
```

Run tests with all features:

```bash
cargo test --all-features
```

Run tests for a specific package:

```bash
cargo test --package indieweb
```

Run a specific test:

```bash
cargo test test_name
```

Run tests with verbose output:

```bash
cargo test -- --nocapture
```

### Benchmarking

Run all benchmarks:

```bash
cargo bench
```

Run a specific benchmark:

```bash
cargo bench -- micropub_properties
```

**Note**: Benchmarking requires the `--release` profile implicitly.

### Code Quality

Check code formatting without making changes:

```bash
cargo fmt -- --check
```

Auto-format code:

```bash
cargo fmt
```

Run clippy linter:

```bash
cargo clippy --all-features
```

Auto-fix linting issues where possible:

```bash
cargo clippy --all-features -- --fix
```

## Git Hooks Setup

### Automated DCO Enforcement

Set up a commit-msg hook to enforce DCO sign-offs:

```bash
cat > .git/hooks/commit-msg << 'EOF'
#!/bin/bash
if ! grep -q "Signed-off-by:" "$1"; then
    echo "ERROR: Commit message must include 'Signed-off-by:' trailer"
    echo "See DCO.md for details"
    exit 1
fi
EOF
chmod +x .git/hooks/commit-msg
```

This hook will prevent commits that don't include the `Signed-off-by:` trailer.

### Optional: AI Attribution Reminder

Add a prepare-commit-msg hook to remind about AI attribution:

```bash
cat > .git/hooks/prepare-commit-msg << 'EOF'
#!/bin/bash
if [ -z "$(grep 'AI-Assisted-by:' "$1" 2>/dev/null)" ]; then
    echo "" >> "$1"
    echo "# Reminder: If AI tools assisted, add 'AI-Assisted-by:' trailer" >> "$1"
fi
EOF
chmod +x .git/hooks/prepare-commit-msg
```

This adds a non-blocking reminder comment to your commit message template.

## Pull Request Process

1. **Fork the repository** from [git.sr.ht/~jacky/indieweb-rust](https://git.sr.ht/~jacky/indieweb-rust)
2. **Create a feature branch** from the main branch
3. **Make your changes** with proper sign-offs
4. **Ensure tests pass**: `cargo test --all-features`
5. **Run linter**: `cargo clippy --all-features`
6. **Format code**: `cargo fmt`
7. **Submit PR** with:
   - Clear description of changes
   - AI disclosure (if applicable)
   - Links to related issues or specs

## Code Review

All submissions require review. We prioritize:

- **Code quality**: Idiomatic Rust, proper error handling
- **Test coverage**: Tests for new functionality
- **Documentation**: Comments and doc strings for public APIs
- **DCO compliance**: Proper sign-offs on all commits
- **Spec alignment**: Adherence to IndieWeb specifications

### Getting Help

If you need help contributing:
- Open an issue with the `question` label
- Join the IndieWeb community at [indieweb.org/chat](https://indieweb.org/chat)
- Contact maintainers at yo@jacky.wtf

## Resources

- [IndieWeb Specifications](https://indieweb.org/Specs)
- [Rust Book](https://doc.rust-lang.org/book/)
- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- [Conventional Commits](https://www.conventionalcommits.org/)

Thank you for contributing to indieweb-rust!
