# 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:** - **Security issues:** - **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!