esp32-bluetooth-relay/CONTRIBUTING.md

# 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.