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
• Getting Started
• Development Setup
• How to Contribute
• Pull Request Process
• Coding Standards
• 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.

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
• Node.js 20+ - For Web UI development
• pnpm - Package manager for Web UI
• Docker (optional) - For container builds

Development Setup

1. Clone the repository:

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

2. Setup Rust environment:

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

cd webui
pnpm install

4. Build the project:

# Build server only
cargo build

# Build with Web UI
cargo build --features webui

5. Run tests:

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

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:

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
• Use rustfmt for formatting
• Address all clippy warnings
• Write documentation for public APIs
• Include unit tests for new functionality

// 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

// 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 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! 🎉