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. 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 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 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:

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 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:

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 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:

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

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 for more details on our development process.

Code Style and Guidelines

• Rust: Follow Rust 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:

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), 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 — System design and component boundaries
• ROADMAP.md — Project phases and long-term direction
• 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 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 for the responsible disclosure process.

Getting Help

• Stuck? Open a GitHub Discussion or ask in an issue.
• Questions about contribution? Check docs/WORKFLOW.md or ask.
• Feedback on your PR? Ask for help! Code review is collaborative.
• Want to discuss design? 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!