galvanize/CONTRIBUTING.md

# Contributing to Galvanize

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

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [How to Contribute](#how-to-contribute)
- [Pull Request Process](#pull-request-process)
- [Coding Standards](#coding-standards)
- [Commit Messages](#commit-messages)

## Code of Conduct

This project and everyone participating in it is governed by our commitment to providing a welcoming and inclusive environment. By participating, you are expected to uphold this commitment. Please report unacceptable behavior to [contact@aitiome.org](mailto:contact@aitiome.org).

### Our Standards

- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members

## Getting Started

### Prerequisites

- **Rust 1.75+** - Install via [rustup](https://rustup.rs/)
- **Node.js 20+** - For Web UI development
- **pnpm** - Package manager for Web UI
- **Docker** (optional) - For container builds

### Development Setup

1. **Clone the repository:**

```bash
git clone https://github.com/aitiome/galvanize.git
cd galvanize
```

2. **Setup Rust environment:**

```bash
# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install additional components
rustup component add rustfmt clippy
```

3. **Setup Web UI environment:**

```bash
cd webui
pnpm install
```

4. **Build the project:**

```bash
# Build server only
cargo build

# Build with Web UI
cargo build --features webui
```

5. **Run tests:**

```bash
# Rust tests
cargo test

# Web UI tests
cd webui && pnpm test
```

## How to Contribute

### Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates.

When creating a bug report, please include:

- **Clear title** describing the issue
- **Steps to reproduce** the behavior
- **Expected behavior** - what you expected to happen
- **Actual behavior** - what actually happened
- **Environment details:**
  - OS and version
  - Rust version (`rustc --version`)
  - Galvanize version
- **Screenshots** (if applicable)
- **Logs** (if applicable)

### Suggesting Features

Feature requests are welcome! Please provide:

- **Clear title** describing the feature
- **Detailed description** of the proposed functionality
- **Use case** - why is this feature needed?
- **Possible implementation** (optional)

### Your First Code Contribution

Looking for something to work on? Check out issues labeled:

- `good first issue` - Good for newcomers
- `help wanted` - Extra attention needed
- `documentation` - Documentation improvements

## Pull Request Process

1. **Fork the repository** and create your branch from `main`:

```bash
git checkout -b feature/my-new-feature
# or
git checkout -b fix/bug-description
```

2. **Make your changes** following our coding standards.

3. **Write tests** for your changes.

4. **Ensure all tests pass:**

```bash
cargo test
cargo clippy -- -D warnings
cargo fmt -- --check
```

5. **Update documentation** if needed.

6. **Commit your changes** using conventional commit messages.

7. **Push to your fork** and submit a Pull Request.

8. **Describe your changes** in the PR description:
   - What does this PR do?
   - How has it been tested?
   - Are there any breaking changes?

### PR Review Process

- PRs require at least one approving review
- CI checks must pass
- PRs should be up to date with `main` before merging

## Coding Standards

### Rust

- Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- Use `rustfmt` for formatting
- Address all `clippy` warnings
- Write documentation for public APIs
- Include unit tests for new functionality

```rust
// Good: Documented public function with error handling
/// Sends a Wake-on-LAN magic packet to the specified MAC address.
///
/// # Arguments
///
/// * `mac` - The MAC address of the target device
/// * `broadcast` - Optional broadcast address (defaults to 255.255.255.255)
///
/// # Errors
///
/// Returns an error if the magic packet cannot be sent.
pub fn wake_device(mac: &MacAddress, broadcast: Option<IpAddr>) -> Result<(), WolError> {
    // Implementation
}
```

### TypeScript/React (Web UI)

- Use TypeScript strict mode
- Follow ESLint and Prettier configuration
- Use functional components with hooks
- Keep components small and focused

```typescript
// Good: Typed component with proper props interface
interface DeviceCardProps {
  device: Device;
  onWake: (id: string) => Promise<void>;
}

export function DeviceCard({ device, onWake }: DeviceCardProps) {
  // Implementation
}
```

## Commit Messages

We use [Conventional Commits](https://www.conventionalcommits.org/) format:

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Types

- `feat` - New feature
- `fix` - Bug fix
- `docs` - Documentation only
- `style` - Code style (formatting, etc.)
- `refactor` - Code refactoring
- `perf` - Performance improvement
- `test` - Adding tests
- `chore` - Maintenance tasks
- `ci` - CI/CD changes

### Examples

```
feat(api): add device groups endpoint

Add support for organizing devices into groups.
Groups can be used to wake multiple devices at once.

Closes #123
```

```
fix(wol): handle network interface binding on Linux

Previously, the WoL packet was not being sent on the correct
network interface when multiple interfaces were available.

Fixes #456
```

## Questions?

Feel free to open an issue for any questions or reach out to the maintainers.

Thank you for contributing! 🎉