jesus/provisioning
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
provisioning/docs/src/development/contributing.md
Jesús Pérez 27dbc5cd08
chore: review docs from scratch
2026-01-17 03:58:28 +00:00

5.7 KiB
Raw Blame History

Contributing

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

Getting Started

Prerequisites

Install required development tools:

# 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

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

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

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

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