# Contributing

Guidelines for contributing to the Provisioning platform including setup, workflow, and best practices.

## Getting Started

### Prerequisites

Install required development tools:

```bash
# Rust toolchain (latest stable)
curl --proto '=https' --tlsv1.2 -sSf  [https://sh.rustup.rs](https://sh.rustup.rs) | sh

# Nushell shell
brew install nushell

# Nickel configuration language
brew install nickel

# Just task runner
brew install just

# Additional development tools
cargo install cargo-watch cargo-tarpaulin cargo-audit
```

### Development Workflow

Follow these guidelines for all code changes and ensure adherence to the project's technical standards.

1. Read applicable language guidelines
2. Create feature branch from main
3. Make changes following project standards
4. Write or update tests
5. Run full test suite and linting
6. Create pull request with clear description

## Code Style Guidelines

### Rust Code

Rust code guidelines:

- Use idiomatic Rust patterns
- No `unwrap()` in production code
- Comprehensive error handling with custom error types
- Format with `cargo fmt`
- Pass `cargo clippy -- -D warnings` with zero warnings
- Add inline documentation for public APIs

### Nushell Scripts

Nushell code guidelines:

- Use structured data pipelines
- Avoid external command dependencies where possible
- Handle errors gracefully with try-catch
- Document functions with comments
- Use type annotations for clarity

### Nickel Schemas

Nickel configuration guidelines:

- Define clear type constraints
- Use lazy evaluation appropriately
- Provide default values where sensible
- Document schema fields
- Validate schemas with `nickel typecheck`

## Testing Requirements

All contributions must include appropriate tests:

### Required Tests

- **Unit tests** for all new functions
- **Integration tests** for component interactions
- **Security tests** for security-related changes
- **Documentation tests** for code examples

### Running Tests

```bash
# Run all tests
just test

# Run specific test suite
cargo test -p provisioning-orchestrator

# Run with coverage
cargo tarpaulin --out Html
```

### Test Coverage Requirements

- Unit tests: Minimum 80% code coverage
- Critical paths: 100% coverage
- Security components: 100% coverage

## Documentation

### Required Documentation

All code changes must include:

- **Inline code documentation** for public APIs
- **Updated README** if adding new components
- **Examples** showing usage
- **Migration guide** for breaking changes

### Documentation Standards

Documentation standards:

- Use Markdown for all documentation
- Code blocks must specify language
- Keep lines ≤150 characters
- No bare URLs (use markdown links)
- Test all code examples

## Commit Message Format

Use conventional commit format:

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

<body>

<footer>
```

Types:
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation changes
- `test:` Adding or updating tests
- `refactor:` Code refactoring
- `perf:` Performance improvements
- `chore:` Maintenance tasks

Example:

```text
feat(orchestrator): add workflow retry mechanism

- Implement exponential backoff strategy
- Add max retry configuration option
- Update workflow state tracking

Closes #123
```

## Pull Request Process

### Before Creating PR

1. Update your branch with latest main
2. Run full test suite: `just test`
3. Run linters: `just lint`
4. Format code: `just fmt`
5. Build successfully: `just build-all`

### PR Description Template

```markdown
## Description
Brief description of changes and motivation

## Type of Change
- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to change)
- [ ] Documentation update

## Testing
- [ ] Unit tests added or updated
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Test coverage maintained or improved

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No new compiler warnings
- [ ] Tested on relevant platforms

## Related Issues
Closes #<issue-number>
```

### Code Review

All PRs require code review before merging. Reviewers check:

- Correctness and quality of implementation
- Test coverage and quality
- Documentation completeness
- Adherence to style guidelines
- Security implications
- Performance considerations
- Breaking changes properly documented

## Development Best Practices

### Code Quality

- Write self-documenting code with clear naming
- Keep functions focused and single-purpose
- Avoid premature optimization
- Use meaningful variable and function names
- Comment complex logic, not obvious code

### Error Handling

- Use custom error types, not strings
- Provide context in error messages
- Handle errors at appropriate level
- Log errors with sufficient detail
- Never ignore errors silently

### Performance

- Profile before optimizing
- Use appropriate data structures
- Minimize allocations in hot paths
- Consider async for I/O-bound operations
- Benchmark performance-critical code

### Security

- Validate all inputs
- Never log sensitive data
- Use constant-time comparisons for secrets
- Follow principle of least privilege
- Review security guidelines for security-related changes

## Getting Help

Need assistance with contributions?

1. Check existing documentation in `docs/`
2. Search for similar closed issues and PRs
3. Ask questions in GitHub Discussions
4. Reach out to maintainers

## Recognition

Contributors are recognized in:

- `CONTRIBUTORS.md` file
- Release notes for significant contributions
- Project documentation acknowledgments

Thank you for contributing to the Provisioning platform!
