From 746fc5a26b23b301abd3a92043781f0e16d502a8 Mon Sep 17 00:00:00 2001
From: jessikitty <jess.rogerson.29@outlook.com>
Date: Mon, 15 Dec 2025 16:15:04 +1100
Subject: [PATCH] Add contributing guidelines for community collaboration

---
 CONTRIBUTING.md | 428 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 428 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..8bf2721
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,428 @@
+# Contributing to ESP32 Bluetooth Relay Controller
+
+Thank you for your interest in contributing! This document provides guidelines and information for contributing to this project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How Can I Contribute?](#how-can-i-contribute)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Features](#suggesting-features)
+- [Development Setup](#development-setup)
+- [Pull Request Process](#pull-request-process)
+- [Coding Standards](#coding-standards)
+- [Testing Guidelines](#testing-guidelines)
+
+## Code of Conduct
+
+### Our Pledge
+
+We are committed to providing a welcoming and inclusive environment for everyone. We expect all contributors to:
+
+- Be respectful and considerate
+- Welcome diverse perspectives and experiences
+- Accept constructive criticism gracefully
+- Focus on what's best for the community
+- Show empathy towards other community members
+
+### Unacceptable Behavior
+
+- Harassment, discrimination, or derogatory comments
+- Trolling, insulting comments, or personal attacks
+- Publishing private information without permission
+- Any conduct that could be considered inappropriate in a professional setting
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating a bug report:
+1. **Check existing issues** to avoid duplicates
+2. **Test with the latest version** to ensure the bug still exists
+3. **Gather information** about your setup and the bug
+
+#### Bug Report Template
+
+```markdown
+**Description:**
+A clear description of the bug
+
+**Steps to Reproduce:**
+1. Step 1
+2. Step 2
+3. Step 3
+
+**Expected Behavior:**
+What you expected to happen
+
+**Actual Behavior:**
+What actually happened
+
+**Environment:**
+- ESP32 Board: [e.g., ESP32-DevKitC V4]
+- Relay Module: [e.g., 8-Channel 5V Active LOW]
+- Arduino IDE Version: [e.g., 2.3.2]
+- Operating System: [e.g., Windows 11]
+- Bluetooth Device: [e.g., Android 14]
+
+**Additional Context:**
+- Serial monitor output
+- Photos of wiring
+- Any other relevant information
+```
+
+### Suggesting Features
+
+Feature requests are welcome! Before submitting:
+
+1. **Check if it's already requested** in existing issues
+2. **Explain the use case** - why is this feature needed?
+3. **Provide examples** of how it would work
+4. **Consider alternatives** you've thought about
+
+#### Feature Request Template
+
+```markdown
+**Feature Description:**
+A clear description of the feature
+
+**Use Case:**
+Why is this feature needed? What problem does it solve?
+
+**Proposed Solution:**
+How you think this feature should work
+
+**Alternatives Considered:**
+Other solutions you've thought about
+
+**Additional Context:**
+Mockups, diagrams, or examples
+```
+
+## Development Setup
+
+### Prerequisites
+
+- Arduino IDE 2.0+ or PlatformIO
+- ESP32 board support installed
+- Git for version control
+- An ESP32 board and relay module for testing
+
+### Setting Up Development Environment
+
+1. **Fork the repository**
+   ```bash
+   # Click "Fork" on the repository page
+   ```
+
+2. **Clone your fork**
+   ```bash
+   git clone https://gitea.hideawaygaming.com.au/[your-username]/esp32-bluetooth-relay.git
+   cd esp32-bluetooth-relay
+   ```
+
+3. **Create a branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b bugfix/your-bugfix-name
+   ```
+
+4. **Set up hardware**
+   - Connect ESP32 and relay module as per documentation
+   - Test with existing firmware before making changes
+
+### Testing Your Changes
+
+1. **Compile the code**
+   ```bash
+   # Arduino IDE: Sketch > Verify/Compile
+   # PlatformIO: pio run
+   ```
+
+2. **Upload to ESP32**
+   ```bash
+   # Arduino IDE: Sketch > Upload
+   # PlatformIO: pio run --target upload
+   ```
+
+3. **Test functionality**
+   - Test all modified features
+   - Verify existing features still work
+   - Test edge cases
+
+4. **Check serial output**
+   - Monitor for errors or warnings
+   - Verify debug messages are helpful
+
+## Pull Request Process
+
+### Before Submitting
+
+- [ ] Code compiles without errors
+- [ ] All features tested on actual hardware
+- [ ] Documentation updated (README, comments, etc.)
+- [ ] CHANGELOG.md updated with your changes
+- [ ] Code follows project coding standards
+- [ ] Commit messages are clear and descriptive
+
+### Submitting a Pull Request
+
+1. **Push to your fork**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+2. **Create Pull Request**
+   - Go to the original repository
+   - Click "New Pull Request"
+   - Select your fork and branch
+   - Fill out the PR template
+
+3. **PR Description Template**
+   ```markdown
+   ## Description
+   Brief description of changes
+   
+   ## Type of Change
+   - [ ] Bug fix
+   - [ ] New feature
+   - [ ] Documentation update
+   - [ ] Performance improvement
+   - [ ] Code refactoring
+   
+   ## Testing
+   How has this been tested?
+   
+   ## Checklist
+   - [ ] Code compiles without errors
+   - [ ] Tested on actual hardware
+   - [ ] Documentation updated
+   - [ ] CHANGELOG.md updated
+   - [ ] Follows coding standards
+   
+   ## Screenshots/Videos
+   If applicable, add screenshots or videos
+   ```
+
+### Review Process
+
+1. Maintainers will review your PR
+2. Address any requested changes
+3. Once approved, your PR will be merged
+4. Your contribution will be credited in CHANGELOG
+
+## Coding Standards
+
+### C++ Style Guidelines
+
+```cpp
+// Use clear, descriptive variable names
+int relayCount = 8;  // Good
+int rc = 8;          // Avoid
+
+// Constants in UPPER_CASE
+const int MAX_RELAYS = 8;
+
+// Functions in camelCase
+void sendCommand(String command) {
+    // Implementation
+}
+
+// Classes in PascalCase
+class RelayController {
+    // Implementation
+};
+
+// Add comments for complex logic
+// Calculate average response time over last 10 readings
+float averageResponseTime = calculateAverage(readings, 10);
+```
+
+### Code Organization
+
+```cpp
+/*
+ * File Header: Brief description of file purpose
+ * Author information (optional)
+ * License reference
+ */
+
+// 1. Include statements
+#include "BluetoothSerial.h"
+
+// 2. Define constants
+#define MAX_BUFFER_SIZE 256
+
+// 3. Global variables (minimize these)
+BluetoothSerial SerialBT;
+
+// 4. Function declarations
+void setupRelays();
+void processCommand(String cmd);
+
+// 5. Setup function
+void setup() {
+    setupRelays();
+}
+
+// 6. Loop function
+void loop() {
+    // Main logic
+}
+
+// 7. Helper functions
+void setupRelays() {
+    // Implementation
+}
+```
+
+### Documentation Standards
+
+```cpp
+/**
+ * @brief Controls a single relay
+ * 
+ * @param relayIndex Index of the relay (0-7)
+ * @param state Desired state (true=ON, false=OFF)
+ * @return bool Success status
+ */
+bool setRelay(int relayIndex, bool state) {
+    // Validate input
+    if (relayIndex < 0 || relayIndex >= 8) {
+        return false;
+    }
+    
+    // Set relay state
+    // (relays are active LOW)
+    digitalWrite(relayPins[relayIndex], state ? LOW : HIGH);
+    
+    return true;
+}
+```
+
+### Git Commit Messages
+
+```
+type(scope): brief description
+
+Longer explanation if needed
+
+Fixes #issue_number
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, no logic change)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+**Examples:**
+```
+feat(relay): add relay interlock functionality
+
+Prevents multiple relays from being active simultaneously
+when interlock mode is enabled.
+
+Fixes #42
+
+---
+
+docs(readme): update wiring diagram for ESP32-C3
+
+Added pin mapping for newer ESP32-C3 boards
+
+---
+
+fix(bluetooth): resolve connection timeout issue
+
+Increased timeout from 5s to 10s to handle slower devices
+
+Fixes #28
+```
+
+## Testing Guidelines
+
+### Hardware Testing
+
+Required tests before PR:
+- [ ] Compile test (no errors/warnings)
+- [ ] Upload test (successful upload)
+- [ ] Basic functionality (all commands work)
+- [ ] All 8 relays tested individually
+- [ ] Bluetooth connection stability
+- [ ] Power cycle test (state persistence)
+- [ ] Long-running test (24+ hours)
+
+### Test Checklist
+
+```markdown
+## Test Report
+
+**Hardware:**
+- ESP32 Board: [model]
+- Relay Module: [model]
+- Power Supply: [specs]
+
+**Test Results:**
+- [ ] All relays switch correctly
+- [ ] Bluetooth pairs successfully
+- [ ] Commands processed correctly
+- [ ] States persist after reboot
+- [ ] No memory leaks observed
+- [ ] Serial output is correct
+- [ ] Runs stable for 24+ hours
+
+**Issues Found:**
+- [List any issues]
+
+**Additional Notes:**
+- [Any observations]
+```
+
+## Documentation Contributions
+
+Documentation improvements are always welcome!
+
+### Documentation Types
+
+- **Code comments**: Explain complex logic
+- **README updates**: Keep instructions current
+- **Troubleshooting**: Add solutions to common issues
+- **Examples**: Add more use cases
+- **Diagrams**: Visual aids for wiring/setup
+- **Translations**: Documentation in other languages
+
+### Writing Style
+
+- Use clear, simple language
+- Include examples where helpful
+- Add screenshots/diagrams when appropriate
+- Test all instructions on fresh setup
+- Proofread for grammar and clarity
+
+## Recognition
+
+Contributors will be:
+- Listed in CHANGELOG.md for their contributions
+- Credited in release notes
+- Mentioned in the repository's contributors section
+
+## Questions?
+
+- Open an issue with the "question" label
+- Check existing issues and discussions
+- Review documentation thoroughly first
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same MIT License that covers this project.
+
+---
+
+**Thank you for contributing to ESP32 Bluetooth Relay Controller!**
+
+Your contributions help make this project better for everyone in the maker and IoT community.