# Contributing to Kubernetes Manager

Thank you for your interest in contributing to kubernetes-manager! This document provides guidelines and instructions for contributing.

## Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please be respectful and constructive in all interactions.

## How to Contribute

### Reporting Bugs

If you find a bug, please create an issue with:
- A clear, descriptive title
- Steps to reproduce the issue
- Expected behavior
- Actual behavior
- Your environment (OS, Rust version, Kubernetes version)
- Any relevant code snippets or error messages

### Suggesting Features

Feature requests are welcome! Please create an issue with:
- A clear description of the feature
- Use cases and motivation
- Examples of how the feature would be used
- Any implementation ideas you have

### Pull Requests

1. **Fork the repository** and create your branch from `main`
2. **Make your changes**:
   - Write clear, documented code
   - Follow the existing code style
   - Add tests for new functionality
   - Update documentation as needed
3. **Test your changes**:
   ```bash
   cargo test
   cargo clippy -- -W clippy::all
   cargo fmt --check
   ```
4. **Commit your changes**:
   - Write clear commit messages
   - Reference any related issues
5. **Push to your fork** and submit a pull request

## Development Setup

### Prerequisites

- Rust 1.70 or later
- A Kubernetes cluster for integration testing (optional)

### Building

```bash
cargo build
```

### Running Tests

```bash
# Run unit tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_name
```

### Code Style

- Run `cargo fmt` before committing
- Run `cargo clippy` and address any warnings
- Follow Rust naming conventions
- Document public APIs with doc comments
- Add examples in doc comments where appropriate

## Project Structure

```
kubernetes-manager/
├── src/
│   ├── client.rs          # Main client
│   ├── config.rs          # Configuration
│   ├── error.rs           # Error types
│   ├── deployment/        # Deployment management
│   ├── service/           # Service management
│   ├── secret.rs          # Secret management
│   ├── namespace.rs       # Namespace management
│   ├── configmap/         # ConfigMap management
│   ├── ingress/           # Ingress management
│   ├── gateway/           # Gateway API management
│   ├── networkpolicy/     # NetworkPolicy management
│   ├── job/               # Job management
│   ├── cronjob/           # CronJob management
│   ├── pvc/               # PVC management
│   ├── hpa/               # HPA management
│   └── lib.rs             # Library root
├── examples/              # Usage examples
└── tests/                 # Integration tests
```

## Adding New Features

When adding new Kubernetes resource support:

1. **Create a new module** in `src/` (e.g., `src/newresource/`)
2. **Implement the spec** (`spec.rs`):
   - Builder pattern for ergonomic API
   - Validation methods
   - Unit tests
3. **Implement the manager** (`manager.rs`):
   - CRUD operations (create, read, update, delete)
   - List operations
   - Proper error handling
4. **Update the client** (`client.rs`):
   - Add manager getter method
5. **Export types** in `lib.rs`
6. **Add documentation**:
   - Module-level docs
   - API docs with examples
   - Update README if needed
7. **Add tests**:
   - Unit tests for specs
   - Unit tests for manager logic
   - Integration tests if applicable

## Documentation

- Use `///` for public API documentation
- Include code examples in doc comments
- Run `cargo doc --open` to view generated docs
- Keep README.md up to date

## Testing Guidelines

### Unit Tests

- Test all public APIs
- Test validation logic
- Test builder patterns
- Test error conditions

Example:
```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_spec_builder() {
        let spec = MySpec::new("test")
            .with_field("value");
        assert_eq!(spec.name(), "test");
    }

    #[test]
    fn test_validation() {
        let spec = MySpec::new("");
        assert!(spec.validate().is_err());
    }
}
```

### Integration Tests

Integration tests require a Kubernetes cluster. Mark them with `#[ignore]`:

```rust
#[tokio::test]
#[ignore] // Requires Kubernetes cluster
async fn test_create_deployment() {
    // Test implementation
}
```

## Release Process

1. Update version in `Cargo.toml`
2. Update `CHANGELOG.md`
3. Create a git tag
4. Publish to crates.io (maintainers only)

## Questions?

Feel free to open an issue for questions or discussions. We're here to help!

## License

By contributing, you agree that your contributions will be licensed under the same license as the project (MIT OR Apache-2.0).
