-
Notifications
You must be signed in to change notification settings - Fork 0
Contribution Guidelines
James Maes edited this page Dec 28, 2025
·
6 revisions
QQQ welcomes contributions from the community! This guide covers the complete process for contributing code, documentation, and improvements to the QQQ framework.
QQQ accepts various types of contributions:
- Code Contributions: New features, bug fixes, improvements
- Documentation: Wiki updates, code comments, examples
- Bug Reports: Issues and problems you've encountered
- Feature Requests: Ideas for new capabilities
- Testing: Test improvements and coverage enhancements
Before contributing, ensure you have:
- Development Environment: See Developer Onboarding
- GitHub Account: For issues and pull requests
- Understanding: Read QQQ's High-Level Architecture
- Code Standards: Review Code Review Standards
- Fork the Repository: Create your own fork of the QQQ project
- Clone Locally: Set up your development environment
- Choose an Issue: Pick something from the issue tracker or create your own
- Follow the Workflow: Use the contribution process outlined below
Start by creating or finding an issue:
Issue Types:
- Bug Report: Something isn't working as expected
- Feature Request: New capability you'd like to see
- Documentation: Missing or unclear documentation
- Enhancement: Improvement to existing functionality
Good Issue Template:
## Summary
Brief description of the issue or feature request
## Current Behavior
What currently happens (for bugs) or what's missing (for features)
## Expected Behavior
What should happen or what you'd like to see
## Steps to Reproduce
For bugs: numbered steps to reproduce the issue
For features: use case or scenario
## Environment
- QQQ Version: [e.g., 0.26.1-SNAPSHOT]
- Java Version: [e.g., 17]
- OS: [e.g., macOS 14.0]
## Additional Context
Any other information that might be helpfulFollow the complete setup process:
# Clone your fork
git clone git@github.com:YOUR_USERNAME/qqq.git
cd qqq
# Add upstream remote
git remote add upstream git@github.com:QRun-IO/qqq.git
# Install QQQ development tools
./qqq-dev-tools/install.sh
# Set up development environment
setup-environments.sh --qqq
# Verify setup
mvn clean installCreate a feature branch following QQQ's GitFlow:
# Start from develop branch
git checkout develop
git pull upstream develop
# Create feature branch
git checkout -b feature/your-feature-name
# Or for bug fixes
git checkout -b fix/issue-descriptionFollow QQQ's development standards:
# Make your changes
# Follow QQQ code style and patterns
# Write tests for new functionality
# Update documentation as needed
# Check code quality
mvn checkstyle:check
mvn test
# Verify full build
mvn clean installEnsure your changes meet QQQ's quality standards:
# Run tests with coverage
mvn test jacoco:report
# Verify coverage thresholds
mvn verify
# Run integration tests
mvn test -pl qqq-sample-projectBefore submitting your PR:
- Code follows QQQ style (Checkstyle passes)
- Tests pass (All tests green)
- Coverage maintained (80% instruction, 95% class)
- Documentation updated (Code comments, wiki if needed)
- No breaking changes (Unless intentional and documented)
- Commit messages follow conventions (See below)
Submit your contribution:
# Commit your changes
git add .
git commit -m "feat(core): add new streaming action capability
- Implements StreamingAction for data stream processing
- Adds QStreamingMetaData for configuration
- Includes comprehensive test coverage
- Updates documentation with usage examples"
# Push to your fork
git push origin feature/your-feature-name
# Create PR to develop branch
# Include:
# - Clear description of changes
# - Link to related issues
# - Screenshots for UI changes
# - Test results and coverageAll contributions require review:
- At least one approval from QQQ team members
- All CI checks pass (build, tests, coverage, style)
- No merge conflicts with target branch
- Follows QQQ patterns and standards
Be responsive to review comments:
- Address feedback promptly and thoroughly
- Ask questions if feedback isn't clear
- Update PR based on review suggestions
- Resolve all comments before merge
- Initial review: Within 2-3 business days
- Follow-up reviews: Within 1-2 business days
- Merge: After approval and all checks pass
When reporting bugs:
- Be specific about what's not working
- Include steps to reproduce the issue
- Provide environment details (QQQ version, Java version, OS)
- Attach logs or error messages if available
- Check existing issues to avoid duplicates
When requesting features:
- Explain the use case and why it's needed
- Describe the desired behavior clearly
- Consider alternatives and trade-offs
- Provide examples of how it would work
- Discuss impact on existing functionality
Improving QQQ documentation:
- Follow existing style and structure
- Use clear, concise language
- Include practical examples
- Link to related content
- Update outdated information
Improving code documentation:
- Follow QQQ comment standards (see Code Review Standards)
- Explain complex logic and business rules
- Document public APIs with Javadoc
- Keep comments current with code changes
- Be respectful and constructive
- Ask questions when you need help
- Share knowledge and help others
- Follow QQQ's code of conduct
- Work together on complex features
- Share progress and challenges
- Help review other contributions
- Mentor new contributors
Your contributions become part of QQQ:
-
Feature branches merge to
develop -
Release branches merge to
main - Version bumps follow semantic versioning
- Release notes credit contributors
Contributors are recognized:
- GitHub contributors list
- Release notes acknowledgments
- Community recognition for significant contributions
- Potential team membership for active contributors
- Start small: Fix typos, improve documentation
- Report issues: Help identify problems
- Suggest improvements: Share ideas and feedback
- Code contributions: Implement features and fixes
- Community support: Help other contributors
- Ask questions in issues or discussions
- Review existing code to understand patterns
- Study documentation and examples
- Join community discussions and meetings
- Build failures: Check Java version, Maven version, dependencies
- Test failures: Review test output, check environment setup
- Style violations: Run Checkstyle locally, fix formatting issues
- Coverage failures: Add tests for uncovered code paths
- Search existing issues for similar problems
- Check documentation and examples
- Ask for help in issues or discussions
- Start with simple changes to build confidence
- Developer Onboarding - Development setup
- Code Review Standards - Code standards
- Team Roles - Team structure