lmrc-postgres 0.3.12

# Contributing to PostgreSQL Manager

Thank you for your interest in contributing to PostgreSQL Manager! This document provides guidelines and information for contributors.

## Code of Conduct

Be respectful and constructive in all interactions.

## How to Contribute

### Reporting Bugs

When reporting bugs, please include:

- A clear, descriptive title
- Steps to reproduce the issue
- Expected behavior
- Actual behavior
- Your environment (OS, Rust version, PostgreSQL version)
- Any relevant logs or error messages

### Suggesting Features

Feature requests are welcome! Please:

- Check if the feature has already been requested
- Provide a clear description of the feature
- Explain the use case and benefits
- Consider implementation details if possible

### Pull Requests

1. **Fork the repository** and create a new branch from `main`
2. **Make your changes** following our coding standards
3. **Write tests** for new functionality
4. **Update documentation** as needed
5. **Run tests** to ensure everything passes
6. **Submit a pull request** with a clear description

#### Pull Request Guidelines

- Keep changes focused and atomic
- Write clear, descriptive commit messages
- Follow existing code style and conventions
- Add tests for new features or bug fixes
- Update README.md and documentation as needed
- Ensure all tests pass

## Development Setup

### Prerequisites

- Rust 1.70 or later
- Access to a test server for integration tests (optional)

### Getting Started

1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/postgres-manager.git
   cd postgres-manager
   ```

2. Build the project:
   ```bash
   cargo build
   ```

3. Run tests:
   ```bash
   cargo test
   ```

### Running Tests

#### Unit Tests

```bash
cargo test
```

#### Integration Tests

Integration tests require SSH access to a test server:

```bash
export TEST_SSH_HOST=192.168.1.100
export TEST_SSH_USER=root
export TEST_SSH_PASSWORD=secret
cargo test --test integration_tests -- --ignored
```

#### Running Examples

```bash
cargo run --example basic_install
cargo run --example custom_config
cargo run --example diff_detection
```

## Code Style

### Rust Guidelines

- Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- Use `rustfmt` for code formatting:
  ```bash
  cargo fmt
  ```
- Use `clippy` for linting:
  ```bash
  cargo clippy
  ```

### Documentation

- Add doc comments (`///`) for all public items
- Include examples in doc comments where appropriate
- Use `cargo doc` to build and view documentation:
  ```bash
  cargo doc --open
  ```

### Error Handling

- Use the custom `Error` type from `crate::error`
- Provide clear, actionable error messages
- Include context with `.map_err()` when appropriate

### Testing

- Write unit tests in the same file as the code (`#[cfg(test)] mod tests`)
- Write integration tests in the `tests/` directory
- Aim for high test coverage
- Test both success and error cases
- Test edge cases and boundary conditions

## Project Structure

```
postgres-manager/
├── src/
│   ├── lib.rs          # Library root and public API
│   ├── config.rs       # PostgresConfig and builder
│   ├── error.rs        # Error types
│   ├── manager.rs      # PostgresManager and builder
│   ├── diff.rs         # Configuration diff detection
│   └── operations.rs   # Idempotent operations
├── tests/
│   └── integration_tests.rs
├── examples/
│   ├── basic_install.rs
│   ├── custom_config.rs
│   ├── diff_detection.rs
│   └── uninstall.rs
├── Cargo.toml
├── README.md
└── CONTRIBUTING.md
```

## Adding New Features

When adding new features:

1. **Design**: Consider the API design and user experience
2. **Implement**: Write the code following our guidelines
3. **Test**: Add comprehensive tests
4. **Document**: Update documentation and add examples
5. **Review**: Submit a PR for review

### Feature Checklist

- [ ] Feature is well-designed and fits the library's purpose
- [ ] Code follows style guidelines
- [ ] Unit tests added
- [ ] Integration tests added (if applicable)
- [ ] Documentation updated
- [ ] Example added (if appropriate)
- [ ] CHANGELOG.md updated (if applicable)

## Idempotency

All operations should be idempotent - safe to run multiple times without errors:

- Check if operation is needed before executing
- Use SQL `IF NOT EXISTS` or `|| true` for database operations
- Handle "already exists" errors gracefully
- Document idempotency guarantees

## Platform Support

Currently supported:
- Debian/Ubuntu Linux
- PostgreSQL 12-16

When adding platform support:
- Test on the target platform
- Update documentation
- Add platform-specific tests

## Release Process

(For maintainers)

1. Update version in `Cargo.toml`
2. Update `CHANGELOG.md`
3. Run all tests
4. Create a git tag
5. Publish to crates.io

## Getting Help

- Open an issue for questions
- Check existing issues and PRs
- Review the documentation

## License

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

## Recognition

Contributors will be recognized in the project README and release notes.

Thank you for contributing to PostgreSQL Manager!