FedDIY/CONTRIBUTING.md

# Contributing to FeDIY

Welcome! We're thrilled you're interested in contributing to FeDIY. Whether you're a Rust expert, a DIY enthusiast, a designer, a writer, or just someone curious about federated projects, there's a place for you here.

## Code of Conduct

Before you get started, please read our [Code of Conduct](CODE_OF_CONDUCT.md). We are committed to providing a welcoming, harassment-free environment for everyone. If you witness or experience behavior that violates the code of conduct, please report it.

## Diversity, Equity, and Inclusion

FeDIY is built on the belief that diverse perspectives make us stronger. We actively welcome contributions from people of all backgrounds, identities, and experience levels. See [DEI.md](DEI.md) for details on how we're building an inclusive community.

## Ways You Can Contribute

Not a code expert? No problem! We value all types of contributions:

### Code and Technical Work

- **Bug fixes:** Found a bug? Fix it! Start with issues labeled `bug`.
- **Features:** Want to implement something new? Check issues labeled `feature` or `help-wanted`.
- **Tests:** Improve test coverage or write new tests.
- **Performance improvements:** Optimize code or fix inefficiencies.
- **Rust learning:** If you're learning Rust, this is a great place to practice. We're happy to help with code review and guidance.

### Documentation and Writing

- **README improvements:** Is something confusing? Improve the docs!
- **API documentation:** Write clear, well-commented documentation for public APIs.
- **Tutorial and guides:** Help newcomers get started with FeDIY.
- **Blog posts or articles:** Share your experience with FeDIY (ask us before publishing to avoid duplication).

### Design and Accessibility

- **UI/UX improvements:** Suggest interface improvements or general enhancements.
- **Accessibility testing and review:** Test features with screen readers, keyboard navigation, and other assistive technologies. Report issues with WCAG 2.1 AA compliance. See [DEI.md](DEI.md) for our accessibility commitments.
- **Alt text and captions:** Help write or improve alt text for images, transcripts for videos, and captions for audio content.
- **Accessible documentation:** Improve docs for clarity, readability, and accessibility (plain language, good structure, proper heading hierarchy).
- **Accessibility tooling:** Develop or suggest tools to help creators make their content accessible (e.g., alt text helpers, caption templates).
- **Design for sensory differences:** Suggest improvements for people who are blind, low-vision, Deaf, hard-of-hearing, or have motor differences.
- **Architecture diagrams:** Help visualize how FeDIY works in multiple formats (visual diagrams, text descriptions, accessible charts).

### Community and Outreach

- **Issue triage:** Help organize and categorize issues.
- **Code review:** Review pull requests and provide constructive feedback.
- **Community discussions:** Participate in GitHub Discussions or forums.
- **Mentoring:** Help newer contributors get up to speed.

## Getting Started

### 1. Set Up Your Development Environment

Clone the repository and set up the development environment:

```bash
git clone https://github.com/moturpin/FeDIY.git
cd FeDIY
nix flake update        # Update Nix dependencies
nix develop             # Enter the development shell
cargo build             # Build the project
cargo test              # Run tests
```

**Note:** We use Nix flakes for reproducible development. If you don't have Nix installed, see our [README](README.md) for alternative setup instructions.

### 2. Choose Something to Work On

- **New to the project?** Look for issues labeled `good-first-issue` or `help-wanted`.
- **Want to learn?** Pick an issue that interests you and comment to let us know.
- **Have an idea?** Open a GitHub Discussion to get feedback before starting work.
- **Not sure?** Ask! Comment on an issue or start a discussion.

### 3. Create a Branch and Make Your Changes

We use GitHub Flow for branching:

```bash
git checkout -b feature/your-feature-name
# or: git checkout -b fix/issue-number-short-description
```

**Branch naming conventions:**

- `feature/feature-name` for new features
- `fix/issue-number-description` for bug fixes
- `docs/description` for documentation changes
- `refactor/description` for code cleanup

### 4. Write Commit Messages

Use clear, descriptive commit messages:

```
Summarize change in ~50 characters or less

Add more detailed explanation here if needed, wrapping around 72 characters.

If this closes an issue, mention it:
Closes #123
```

Follow the [conventional commits](https://www.conventionalcommits.org/) style when possible:

- `fix:` for bug fixes
- `feat:` for new features
- `docs:` for documentation changes
- `test:` for test changes
- `refactor:` for code cleanup

### 5. Testing and Quality

Before pushing, ensure your code is ready:

```bash
cargo fmt              # Format code
cargo clippy           # Run linter
cargo test             # Run tests
cargo build --release # Build in release mode
```

All of these should pass before submitting a PR.

### 6. Push and Open a Pull Request

```bash
git push origin feature/your-feature-name
```

Then open a pull request on GitHub. Include:

- **Description:** What does this change do? Why?
- **Testing:** How did you test this? What should reviewers test?
- **Screenshots or examples** (if applicable)
- **Links to related issues** (e.g., "Closes #123")

We'll review your PR and provide feedback. Don't worry if we ask for changes—that's part of the process!

## Development Process

We follow Test-Driven Development (TDD) / Behavior-Driven Development (BDD):

### Red-Green-Refactor Cycle

1. **Red:** Write a test that fails (describes the desired behavior)
2. **Green:** Write minimal code to make the test pass
3. **Refactor:** Improve the code without changing behavior

See [WORKFLOW.md](docs/WORKFLOW.md) for more details on our development process.

## Code Style and Guidelines

- **Rust:** Follow [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/). We use `rustfmt` for formatting.
- **Comments:** Write comments that explain *why*, not just *what*. The code itself shows what it does.
- **Type safety:** Leverage Rust's type system to prevent bugs. Prefer explicit types over type inference when it improves clarity.
- **Error handling:** Use Result/Option types appropriately. Avoid panicking except in truly unrecoverable situations.
- **Naming:** Use clear, descriptive names. Prefer `is_active` over `active` for booleans.

Run these before submitting:

```bash
cargo fmt --all
cargo clippy --all-targets -- -D warnings
```

## Human-Authored Core Code Policy

We are committed to human-authored, human-reviewed code for FeDIY's core:

- **Executable core code** (src/, tests/) must be written and understood by humans.
- **AI Assistants:** Agents may help with documentation, planning, housekeeping, and Nix environment management.
- **Implementation help:** When asking for coding guidance, you'll receive links to primary sources (especially the [Rust Book](https://doc.rust-lang.org/book/)), paraphrased explanations, and implementation checklists—not generated code.

This policy ensures code quality, maintainability, and learning. It doesn't prevent you from *using* AI tools; it just means you're responsible for understanding and authoring the final code.

## Architecture and Design

Before making large changes, review:

- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — System design and component boundaries
- [ROADMAP.md](docs/ROADMAP.md) — Project phases and long-term direction
- [OPEN_QUESTIONS.md](docs/OPEN_QUESTIONS.md) — Unresolved design decisions

For significant changes, consider opening an issue or discussion first. This helps prevent duplicate work and ensures alignment with the project's direction.

## Pull Request Review Process

We value constructive, respectful code review:

- **Review timeframe:** We aim to provide initial feedback within 48 hours of a PR submission.
- **Expectations:** We may ask questions, suggest improvements, or request changes. This is normal!
- **Approval:** PRs need at least one approval from a maintainer before merging.
- **Passing checks:** All automated checks (formatting, linting, tests) must pass.

### For Reviewers

- Be respectful and constructive. Focus on the code, not the person.
- Explain *why* you're suggesting a change, not just that it should change.
- Acknowledge good work. Celebrate learning and growth.
- Ask questions rather than making demands.

## Licensing

All contributions are licensed under **CC BY-SA 4.0** (Creative Commons Attribution-ShareAlike 4.0). By contributing, you agree to this licensing.

- See [LICENSE](LICENSE) for details.
- This applies to all contributions (code, documentation, designs, etc.).

## Reporting Issues

Found a bug or have a feature request?

1. **Check existing issues** to avoid duplicates.
2. **Be clear and specific.**
   - Include steps to reproduce for bugs.
   - Explain your use case for features.
   - Add error messages, logs, or screenshots if helpful.
3. **Include environment info:**
   - OS and version
   - Rust version (if relevant)
   - How you built/ran FeDIY

## Security Issues

**Don't open public issues for security vulnerabilities!** See [SECURITY.md](SECURITY.md) for the responsible disclosure process.

## Getting Help

- **Stuck?** Open a GitHub Discussion or ask in an issue.
- **Questions about contribution?** Check [docs/WORKFLOW.md](docs/WORKFLOW.md) or ask.
- **Feedback on your PR?** Ask for help! Code review is collaborative.
- **Want to discuss design?** [OPEN_QUESTIONS.md](docs/OPEN_QUESTIONS.md) is a good place to start.

## Recognizing Contributors

We believe in recognizing contributions. Contributors are listed in:

- **GitHub:** Automatically in the repository's contributor graph
- **Release notes:** Major contributors mentioned in release announcements
- **Project documentation:** Long-term contributors highlighted

## Questions?

- **General questions:** Start a GitHub Discussion
- **Code of Conduct questions:** <conduct@moturpin.com>
- **Security issues:** <security@moturpin.com>
- **Other:** Open an issue and tag with `question`

---

Thank you for contributing! Together, we're building a federated DIY community that welcomes everyone. Happy coding!