Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
168 lines (120 loc) · 4.8 KB

CONTRIBUTING.md

File metadata and controls

168 lines (120 loc) · 4.8 KB

Contributing to WebMob

First off, thank you for considering contributing to WebMob! 🎉 It's people like you that make WebMob such a great learning tool for everyone.

🌟 How Can I Contribute?

Current Phase: Documentation

Since we're currently in the documentation phase, here are the ways you can help:

📝 Documentation Improvements

  • Fix typos or clarify instructions
  • Add missing information
  • Improve existing guides
  • Translate documentation to other languages
  • Add diagrams or illustrations

🐛 Reporting Issues

  • Report unclear documentation
  • Suggest improvements to the getting started guide
  • Report broken links
  • Suggest new documentation topics

🎨 Design Feedback

  • Provide feedback on the design system
  • Suggest accessibility improvements
  • Share ideas for UI/UX enhancements

📸 Sharing Your Build

  • Share photos of your WebMob robot
  • Document your building process
  • Share tips and tricks
  • Report what worked or didn't work for you

📋 How to Submit Contributions

For Documentation Changes

  1. Fork the repository

    git clone https://github.com/ivanr3d/webmob.git
cd webmob

  2. Create a branch

    git checkout -b docs/improve-getting-started

  3. Make your changes

    • Edit the relevant markdown files
    • Keep the same style and tone
    • Follow our writing guidelines (see below)

  4. Commit your changes

    git add .
git commit -m "docs: improve getting started guide clarity"

  5. Push and create a Pull Request

    git push origin docs/improve-getting-started

For Issues and Suggestions

  1. Check if the issue already exists
  2. Use our issue templates when available
  3. Provide as much context as possible
  4. Be clear and concise

✍️ Writing Guidelines

When contributing to documentation:

Tone and Voice

  • Friendly and encouraging - Match the robot's personality ("Let's learn together!")
  • Clear and simple - Avoid jargon when possible
  • Patient and supportive - Remember beginners are reading this
  • Inclusive - Use "we" and "you" appropriately

Formatting

  • Use clear headings and subheadings
  • Break up long paragraphs
  • Use bullet points for lists
  • Include code blocks with syntax highlighting
  • Add images or diagrams when helpful

Examples

✅ Good: "Let's connect your Arduino! First, plug the USB cable into your computer..."

❌ Bad: "Connect the Arduino Nano via USB interface to establish serial communication..."

✅ Good: "If you see this error, don't worry! Here's how to fix it..."

❌ Bad: "Error state encountered. Troubleshoot accordingly."

🎯 What We're Looking For

High Priority

  • Clarity improvements in getting started guide
  • Additional troubleshooting tips
  • Assembly instruction enhancements
  • Hardware sourcing tips for different regions
  • Accessibility improvements

Welcome Contributions

  • New examples and use cases
  • Community project showcases
  • Educational activity ideas
  • Design system feedback
  • Translation to other languages

Not Yet Accepting

  • Source code contributions (coming in Phase 2)
  • Major structural changes without discussion
  • Changes that conflict with the design system

🔍 Review Process

  1. Initial Review - Maintainer reviews within 3-5 days
  2. Feedback - We may request changes or ask questions
  3. Approval - Once approved, changes are merged
  4. Recognition - Contributors are added to our acknowledgments

💭 Questions?

  • Open a Discussion for general questions
  • Open an Issue for bugs or specific problems
  • Tag maintainers with @ivanr3d for urgent matters

📜 Code of Conduct

This project follows our Code of Conduct. By participating, you agree to uphold this code. Please report unacceptable behavior to [hi@ivanr3d.com].

🎓 First Time Contributing?

Don't worry! Here are some resources to help you get started:

🙏 Recognition

All contributors will be recognized in our README and documentation. We appreciate every contribution, no matter how small!

Commit Message Guidelines

We follow conventional commits for clear history:

  • docs: - Documentation changes
  • feat: - New features (when code is released)
  • fix: - Bug fixes
  • style: - Formatting, missing semicolons, etc.
  • refactor: - Code restructuring
  • test: - Adding tests
  • chore: - Maintenance tasks

Example: docs: add troubleshooting section for Bluetooth connection

Thank you for helping make WebMob better for everyone! 🤖✨