Developer How-To Guides - Contribution-Oriented¶
Welcome to the developer guides section! These guides help you contribute effectively to the Qubinode KVM Host Setup Collection, from setting up your development environment to submitting high-quality pull requests.
Note
New contributor? Start with How to Set Up Development Environment to get your development environment ready.
Getting Started as a Contributor¶
Set Up Development Environment
Complete guide to setting up your local development environment with all required tools and dependencies.
Run Molecule Tests
Learn to run and debug Molecule tests locally to validate your changes before submitting.
Contributing Guidelines
Complete workflow from finding issues to getting your pull requests merged successfully.
Development Workflow Guides¶
Local Testing Requirements
Mandatory testing procedures that must be followed before pushing code to CI/CD.
Migrate Molecule Tests
Update existing Molecule configurations to current best practices and standards.
Automation and CI/CD¶
Set Up Dependabot Automation
Configure automated dependency management and security updates for the project.
Set Up Self-Hosted Runner
Configure a CentOS Stream 10 self-hosted runner for CI/CD pipelines.
Developer Guide Characteristics¶
All developer guides in this section:
Focus on contribution: Help you contribute effectively to the project
Assume development context: You’re working with source code and development tools
Provide complete procedures: End-to-end workflows from setup to completion
Include quality standards: Code quality, testing, and compliance requirements
Support collaboration: Guidelines for working with the community
Contribution Types¶
### Code Contributions - Bug fixes: Resolve issues and improve reliability - New features: Add functionality and capabilities - Performance improvements: Optimize existing code - Security enhancements: Improve security posture
### Documentation Contributions - Tutorial improvements: Enhance learning materials - How-to guide additions: Add solutions for new problems - Reference updates: Keep technical documentation current - Explanation enhancements: Improve architectural understanding
### Testing Contributions - Test coverage: Add tests for untested code - Test scenarios: Create new testing scenarios - Test infrastructure: Improve testing tools and processes - Performance testing: Add performance validation
Development Environment¶
### Required Tools - Git: Version control and collaboration - Python 3.9+: Runtime environment - Ansible 2.13+: Automation framework - Molecule: Testing framework - Container Runtime: Podman (preferred) or Docker - IDE/Editor: VS Code (recommended) with Ansible extensions
### Optional Tools - GitHub CLI: Enhanced GitHub integration - Pre-commit: Automated code quality checks - Ansible Lint: Code quality validation - YAML Lint: YAML formatting validation
Quality Standards¶
### Code Quality Requirements - Ansible Lint: Must pass without errors - YAML Lint: Proper YAML formatting required - Security Scan: No security vulnerabilities - Test Coverage: All changes must include tests - Documentation: Updates must include documentation changes
### Testing Requirements - Local Testing: All tests must pass locally before pushing - Molecule Tests: Role-specific testing with Molecule - Integration Tests: Multi-role interaction testing - Compliance Tests: ADR compliance validation
### Review Process - Automated Checks: All CI/CD checks must pass - Peer Review: At least one maintainer approval required - Documentation Review: Documentation changes reviewed - Security Review: Security-sensitive changes get additional review
Getting Help¶
### Community Support - GitHub Discussions: General questions and community support - GitHub Issues: Bug reports and feature requests - Maintainer Contact: Direct contact for complex issues
### Development Resources - Architecture Documentation: Collection Architecture Overview - Design Decisions: ../../explanations/architecture-decisions/index - Technical Reference: Reference Documentation - Technical Specifications - Testing Framework: ../../explanations/testing-framework-selection
Contribution Workflow¶
### Standard Workflow 1. Set up environment: How to Set Up Development Environment 2. Find something to work on: Check GitHub issues or discuss with maintainers 3. Create feature branch: Follow Git workflow best practices 4. Make changes: Implement your contribution 5. Test locally: How to Run Molecule Tests and Local Testing Requirements 6. Submit pull request: How to Contribute to the Project 7. Respond to feedback: Work with reviewers to refine your contribution
### Advanced Workflows - Large features: Break into smaller, reviewable chunks - Breaking changes: Follow deprecation and migration procedures - Security fixes: Follow responsible disclosure procedures - Performance improvements: Include benchmarking and validation
Next Steps¶
After setting up your development environment:
Explore the codebase: Understand the modular architecture
Run existing tests: Familiarize yourself with the testing framework
Find an issue: Look for “good first issue” labels on GitHub
Make your first contribution: Start with documentation or small bug fixes
Engage with community: Participate in discussions and reviews