Submitting Changes¶

This guide walks you through the process of submitting your contributions to quactuary, from preparing your changes to getting them merged into the main repository.

Before You Submit ¶

Pre-submission Checklist ¶

Before creating a pull request, ensure your changes meet these requirements:

Code Quality

[ ] Code follows PEP 8 style guidelines
[ ] All new code has comprehensive docstrings (Google format)
[ ] Type hints are included for all public functions
[ ] No lint errors from flake8 or similar tools

Testing

[ ] All existing tests pass
[ ] New code has ≥90% test coverage
[ ] Edge cases and error conditions are tested
[ ] Integration tests included for new features

Documentation

[ ] Docstrings follow our standards
[ ] User-facing changes are documented
[ ] Examples are included and working
[ ] Changelog is updated for significant changes

Git Hygiene

[ ] Commits have clear, descriptive messages
[ ] Branch is up to date with main
[ ] No merge conflicts
[ ] Commit history is clean (consider squashing)

Running Pre-submission Checks ¶

Run these commands to verify your changes:

# Code formatting
black .
isort .

# Style checking
flake8 quactuary/ tests/

# Type checking
mypy quactuary/

# Run full test suite with coverage
pytest --cov=quactuary --cov-report=html --cov-report=term

# Check documentation builds
cd docs/
make html

Creating a Pull Request ¶

Step 1: Push Your Branch ¶

Push your feature branch to your fork:

# Ensure your branch is up to date
git fetch upstream
git checkout main
git merge upstream/main
git checkout your-feature-branch
git rebase main  # or git merge main

# Push to your fork
git push origin your-feature-branch

Step 2: Create the Pull Request ¶

Navigate to your fork on GitHub
Click “Compare & pull request” for your branch
Select the base repository: AlexFiliakov/quactuary
Select the base branch: main
Write a clear title and description

Pull Request Title ¶

Use a clear, descriptive title that summarizes the change:

Good titles: - “Add quantum amplitude estimation for VaR calculation” - “Fix edge case in compound distribution sampling” - “Improve performance of JIT-compiled simulation” - “Add comprehensive documentation for pricing module”

Avoid: - “Bug fix” - “Update code” - “Various improvements”

Pull Request Description ¶

Write a comprehensive description using this template:

## Description
Brief summary of what this PR does and why it's needed.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Changes Made
- Detailed list of changes
- Include both what was added and what was modified
- Mention any files that were deleted or moved

## Testing
- Describe how you tested your changes
- Include test coverage information
- Mention any manual testing performed

## Performance Impact
(If applicable)
- Benchmarks or performance measurements
- Memory usage considerations
- Scalability implications

## Breaking Changes
(If applicable)
- What breaks and why
- Migration guide for users
- Version compatibility notes

## Documentation
- [ ] Documentation has been updated
- [ ] Docstrings added/updated
- [ ] Examples included
- [ ] Changelog updated

## Related Issues
- Closes #123
- Fixes #456
- Related to #789

## Additional Notes
Any other information reviewers should know.

Example Pull Request Description ¶

## Description
This PR implements quantum amplitude estimation (QAE) for Value at Risk
calculations, providing a theoretical quadratic speedup over classical
Monte Carlo methods for portfolios with specific structure.

## Type of Change
- [x] New feature (non-breaking change which adds functionality)

## Changes Made
- Added `QuantumVaRCalculator` class in `quantum.py`
- Implemented QAE circuit construction and execution
- Added integration with existing VaR calculation pipeline
- Created comprehensive test suite with 95% coverage
- Added performance benchmarks comparing quantum vs classical
- Updated documentation with usage examples and theory

## Testing
- All existing tests pass
- Added 23 new tests for QAE implementation
- Coverage: 95% for new code, 92% overall
- Tested on both simulator and real quantum hardware
- Performance tests validate speedup claims

## Performance Impact
- 4x speedup for portfolios with >10,000 policies (theoretical)
- 2x speedup observed on current quantum simulators
- Memory usage: ~50MB additional for circuit construction
- No impact on classical code paths

## Breaking Changes
None - all changes are additive and backward compatible.

## Documentation
- [x] Documentation has been updated
- [x] Docstrings added for all new functions
- [x] Examples included in docstrings and user guide
- [x] Theory section added explaining QAE algorithm

## Related Issues
- Closes #123 (Add quantum VaR calculation)
- Related to #89 (Quantum algorithm roadmap)

## Additional Notes
- Requires Qiskit ≥1.0.0
- Quantum features remain experimental
- Classical fallback when quantum backend unavailable

Review Process ¶

What Happens After Submission ¶

Automated Checks: CI will run tests and style checks
Initial Review: A maintainer will review within 2-3 business days
Feedback Phase: You may receive requests for changes
Iteration: Work with reviewers to address feedback
Approval: Once approved, changes will be merged

Types of Reviews ¶

Technical Review

Code correctness and efficiency
Test coverage and quality
Architecture and design decisions
Performance implications

Documentation Review

Clarity and completeness of docstrings
User guide accuracy
Example correctness
Consistency with existing docs

Domain Review

Actuarial correctness
Mathematical accuracy
Industry best practices
Regulatory considerations (if applicable)

Responding to Feedback ¶

How to Handle Review Comments ¶

Read thoroughly: Understand each comment before responding
Ask questions: If something isn’t clear, ask for clarification
Be responsive: Respond within a few days when possible
Be open: Consider suggestions even if you initially disagree
Explain decisions: If you disagree, explain your reasoning

Making Changes ¶

When reviewers request changes:

# Make your changes
git checkout your-feature-branch
# Edit files...

# Add and commit
git add .
git commit -m "Address review feedback: improve error handling"

# Push updates
git push origin your-feature-branch

The pull request will automatically update with your new commits.

Resolving Conversations ¶

Mark conversations as “resolved” after addressing them
Leave a comment explaining what you changed
Don’t resolve conversations that you disagree with - discuss instead

Common Review Feedback ¶

Code Issues ¶

“This function is too complex”

Break into smaller functions
Reduce cyclomatic complexity
Add helper methods

“Missing error handling”

Add appropriate try/catch blocks
Validate input parameters
Provide helpful error messages

“Performance concern”

Profile the code to identify bottlenecks
Consider algorithmic improvements
Add performance tests

Testing Issues ¶

“Insufficient test coverage”

Add tests for uncovered lines
Test edge cases and error conditions
Include integration tests

“Tests are flaky”

Fix non-deterministic behavior
Use proper mocking for external dependencies
Set random seeds for reproducibility

“Missing performance tests”

Add benchmarks for performance-critical code
Test scalability with large inputs
Set performance regression thresholds

Documentation Issues ¶

“Unclear docstring”

Improve parameter descriptions
Add more detailed examples
Clarify the purpose and behavior

“Missing user documentation”

Add user guide sections
Include tutorial notebooks
Update API reference

Advanced Submission Topics ¶

Large Features ¶

For significant features:

Discuss first: Open an issue to discuss the approach
Break into phases: Consider multiple smaller PRs
Feature flags: Use flags to enable features incrementally
Documentation: Include comprehensive docs and examples

Breaking Changes ¶

If your change breaks backward compatibility:

Discuss necessity: Ensure the breaking change is justified
Version planning: Coordinate with maintainers on timing
Migration guide: Provide clear upgrade instructions
Deprecation period: Consider deprecating before removing

Performance Changes ¶

For performance-related changes:

Benchmark first: Measure current performance
Profile changes: Verify improvements with profiling
Regression tests: Add tests to prevent performance regression
Document impact: Explain performance characteristics

Release Process Integration ¶

Version Planning ¶

Changes are integrated into releases based on:

Patch releases (x.x.1): Bug fixes, documentation
Minor releases (x.1.x): New features, non-breaking changes
Major releases (1.x.x): Breaking changes, major features

Your PR will be labeled and assigned to appropriate milestones.

Changelog Updates ¶

For user-facing changes, update CHANGELOG.md:

## [Unreleased]

### Added
- Quantum amplitude estimation for VaR calculations (#123)
- New distribution: Inverse Gaussian (#456)

### Changed
- Improved performance of JIT compilation (#789)

### Fixed
- Edge case in compound distribution sampling (#321)

### Deprecated
- `old_function_name` in favor of `new_function_name` (#654)

Troubleshooting Submissions ¶

CI Failures ¶

Tests failing:

# Run the same tests locally
pytest tests/test_specific.py -v

# Check for environment differences
pip list  # Compare with CI environment

Style check failures:

# Auto-fix most issues
black .
isort .

# Check remaining issues
flake8 quactuary/

Documentation build failures:

cd docs/
make clean
make html
# Check for syntax errors in rst files

Merge Conflicts ¶

If your branch has conflicts with main:

# Update your local main
git checkout main
git pull upstream main

# Rebase your feature branch
git checkout your-feature-branch
git rebase main

# Resolve conflicts manually, then:
git add .
git rebase --continue

# Force push (since history changed)
git push --force-with-lease origin your-feature-branch

Stale Branches ¶

If your PR sits idle for a while:

Rebase on latest main to resolve conflicts
Address any new CI failures
Ping reviewers if needed
Consider breaking into smaller PRs if very large

Getting Help ¶

If you need assistance:

Comment on your PR: Ask specific questions
GitHub Discussions: For broader questions
Issue tracker: For bug reports or feature discussions
Documentation: Check our development guides

Communication Tips ¶

Effective Communication ¶

Be patient: Reviews take time, especially for large changes
Be humble: Everyone’s goal is improving the project
Be collaborative: Work with reviewers, not against them
Be clear: Explain your reasoning and approach

Cultural Considerations ¶

Assume good intent: Reviewers want to help improve your code
English proficiency: Don’t worry if English isn’t your first language
Different perspectives: Embrace diverse viewpoints and approaches
Learning opportunity: Use reviews to improve your skills

Success Metrics ¶

A successful contribution:

Solves a real problem for users
Maintains code quality standards
Includes comprehensive tests and documentation
Integrates smoothly with existing codebase
Follows project conventions and best practices

Your contributions make quactuary better for everyone. Thank you for taking the time to follow these guidelines and help us maintain a high-quality project!