258 lines
5.7 KiB
Markdown
258 lines
5.7 KiB
Markdown
# 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!
|