Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
217 lines (167 loc) · 6.91 KB

CONTRIBUTING.md

File metadata and controls

217 lines (167 loc) · 6.91 KB
Raw

Contributing to ARM Cortex-M Tutorials

Thank you for your interest in contributing! This project aims to create high-quality, original educational content for ARM Cortex-M embedded programming.

🎯 Project Goals

  • Educational focus on ARM Cortex-M concepts
  • Accessible through Wokwi simulations
  • Progressive difficulty levels
  • Original, plagiarism-free content
  • Clear documentation and explanations

📋 Contribution Guidelines

Project Structure Requirements

Each project must include:

  • README.md with clear explanation and proper references
  • src/main.cpp with well-commented, original code
  • CMakeLists.txt for building
  • wokwi.toml and diagram.json for simulation
  • Circuit diagram image

Code Standards

  • Comments: Explain ARM-specific concepts
  • Naming: Use descriptive variable names
  • Style: Follow consistent C++ formatting
  • Originality: All code written from scratch
  • Documentation: Include learning objectives

ARM Focus Areas

Projects should demonstrate:

  • GPIO and peripheral control
  • Interrupt handling
  • Timer and PWM usage
  • Communication protocols
  • Performance considerations
  • Real-time concepts

🛡️ Originality & Anti-Plagiarism Requirements

Original Content Strategy

Code Examples

  • Write from scratch - No copying from existing tutorials
  • Unique implementations - Different approaches to common problems
  • Personal coding style - Consistent variable naming and structure
  • Original comments - Explain concepts in your own words

Documentation

  • Personal explanations - Write concepts as you understand them
  • Unique analogies - Use your own comparisons and examples
  • Original structure - Different organization than existing tutorials
  • Personal insights - Add your learning experience and tips

Circuit Designs

  • Custom pin assignments - Use different GPIO pins than common examples
  • Unique component combinations - Creative circuit arrangements
  • Original diagrams - Draw your own circuit illustrations
  • Personal component choices - Justify your hardware selections

Required References for Every Project

  • ARM official documentation (architecture manuals, technical references)
  • Raspberry Pi Foundation materials (datasheets, SDK docs)
  • Development tools used (Wokwi, ARM GCC, CMake)
  • Protocol standards referenced (I2C, SPI, UART specifications)
  • Hardware specifications cited (electrical characteristics, pinouts)

Citation Format

## 📚 References & Credits

### Official Documentation
- [Document Title](URL) - Organization Name
- [ARM Cortex-M0+ Technical Reference Manual](https://developer.arm.com/documentation/ddi0484/latest/) - ARM Ltd.

### Hardware Specifications  
- [RP2040 Datasheet](https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf) - Raspberry Pi Foundation

### Development Tools
- [Wokwi Online Simulator](https://wokwi.com/) - Wokwi Ltd.

What to Avoid

  • Copying code from existing tutorials
  • Paraphrasing without adding value
  • Using identical project structures
  • Copying circuit diagrams
  • Reusing exact explanations

🚀 How to Contribute

Adding a New Project

  1. Choose project number: Next in sequence (02, 03, 04...)
  2. Use original approach: Create unique implementation
  3. Follow naming convention: ##-descriptive-name/
  4. Create complete project: Code + documentation + simulation + references
  5. Test thoroughly: Ensure everything works

Improving Existing Projects

  • Fix bugs or improve code quality
  • Enhance documentation with original explanations
  • Add better explanations of ARM concepts
  • Improve Wokwi simulations
  • Add proper references if missing

Documentation Contributions

  • Setup guides with original explanations
  • ARM concept explanations in your own words
  • Tutorial improvements with unique insights
  • Learning path enhancements

📝 Pull Request Process

  1. Fork the repository
  2. Create branch: feature/##-project-name or fix/issue-description
  3. Follow originality guidelines: Ensure all content is original
  4. Test everything: Code compilation + Wokwi simulation
  5. Add proper references: Include all required citations
  6. Update documentation: README and relevant guides
  7. Submit PR: Clear description of changes and originality confirmation

🔍 Review Criteria

  • Educational value: Does it teach ARM concepts effectively?
  • Originality: Is all content created from scratch?
  • Code quality: Clean, commented, and working code
  • Documentation: Clear explanations and learning objectives
  • References: Proper attribution to official sources
  • Simulation: Working Wokwi integration
  • Progression: Fits well in the learning path

✅ Pre-Submission Checklist

Originality Requirements

  • All code written from scratch
  • Documentation uses original explanations
  • No copied text from other tutorials
  • Unique project structure and approach
  • Original Wokwi circuit designs
  • Personal insights and learning tips added

Attribution Requirements

  • ARM official documentation cited
  • Raspberry Pi Foundation materials referenced
  • Development tools properly attributed
  • Protocol standards cited where applicable
  • Hardware specifications referenced

Quality Standards

  • Code compiles without warnings
  • Wokwi simulation works perfectly
  • Documentation is complete and clear
  • ARM concepts are well explained
  • Learning objectives are defined
  • Code is well-commented
  • Project builds on previous concepts

💡 Project Ideas

Beginner Projects (02-10)

  • Button input with debouncing
  • PWM servo control
  • ADC sensor readings
  • UART communication
  • I2C temperature sensor
  • SPI display control
  • Timer-based applications
  • Basic interrupt handling

Intermediate Projects (11-20)

  • Multi-sensor systems
  • Real-time data processing
  • Communication protocol implementations
  • Performance optimization examples
  • Power management techniques

Advanced Projects (21+)

  • Dual-core applications
  • DMA usage examples
  • ARM assembly integration
  • Security implementations
  • Professional use cases

🤝 Community Guidelines

  • Be respectful and constructive
  • Focus on educational value and originality
  • Help others learn ARM concepts
  • Share knowledge and unique experiences
  • Maintain high standards for content quality

📞 Questions?

  • Open an issue for project ideas or questions
  • Discuss in pull request comments
  • Focus on ARM Cortex-M learning goals
  • Ensure all contributions are original and properly attributed

🚫 Unacceptable Contributions

  • Copied code from other tutorials or websites
  • Plagiarized documentation or explanations
  • Missing or improper attribution
  • Non-functional code or simulations
  • Content that doesn't focus on ARM Cortex-M concepts

Create original, educational content that helps others master ARM Cortex-M programming! 🚀