Add contributing guidelines for community collaboration
This commit is contained in:
428
CONTRIBUTING.md
Normal file
428
CONTRIBUTING.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user