Development Guidelines

Welcome to the quactuary development documentation! We’re excited that you’re interested in contributing to the quantum-accelerated actuarial modeling framework. This guide will help you get started with contributing to the project, whether you’re fixing bugs, adding new features, or improving documentation.

quactuary is an open-source project that welcomes contributions from the community. We believe that diverse perspectives and contributions make the project stronger and more useful for everyone.

Contributing to quactuary

• Contributing to quactuary
  • Getting Started
  • Finding Something to Work On
  • Contribution Workflow
  • Pull Request Guidelines
  • Review Process
  • Common Issues and Solutions
  • Getting Help
• Setting Up Your Environment
  • Prerequisites
  • Setting Up the Repository
  • Python Environment Setup
  • Installing Dependencies
  • Verify Installation
  • Development Tools Setup
  • IDE/Editor Setup
  • IDE Integration with run_dev.py
  • Docker Environment (Optional)
  • Common Issues and Solutions
  • Updating Your Environment
  • Environment Variables
  • Next Steps
• Code Standards
  • Style Guide
  • Code Formatting
  • Import Organization
  • Naming Conventions
  • Type Hints
  • Documentation Standards
  • Comments
  • Error Handling
  • Performance Considerations
  • Testing Code Quality
  • Git Commit Standards
  • Code Review Guidelines
  • Common Code Patterns
  • Backward Compatibility
• Testing Guidelines
  • Testing Philosophy
  • Testing Framework
  • Test Organization
  • Types of Tests
  • Test Fixtures
  • Parametrized Tests
  • Coverage Requirements
  • Mock and Patch
  • Error and Edge Case Testing
  • Continuous Integration
  • Test Markers
  • Writing Good Tests
  • Common Testing Pitfalls
  • Testing New Features
• Performance Testing Guide
  • Overview
  • Key Components
  • Writing Performance Tests
  • Managing Baselines
  • CI/CD Integration
  • Regression Detection
  • Best Practices
  • Troubleshooting
• Documentation Guidelines
  • Documentation Philosophy
  • Types of Documentation
  • Docstring Standards
  • Docstring Elements
  • Examples in Docstrings
  • User Guide Documentation
  • Jupyter Notebook Documentation
  • API Reference Documentation
  • Building Documentation
  • Documentation Standards
  • Documentation Maintenance
  • Common Documentation Issues
  • Tools and Resources
• MCP Tool Development
  • Overview
  • Architecture
  • Creating a New Tool
  • Best Practices
  • Testing MCP Tools
  • Performance Considerations
  • Debugging Tools
  • Development Workflow
  • Next Steps
• Submitting Changes
  • Before You Submit
  • Creating a Pull Request
  • Review Process
  • Responding to Feedback
  • Common Review Feedback
  • Advanced Submission Topics
  • Release Process Integration
  • Troubleshooting Submissions
  • Getting Help
  • Communication Tips
  • Success Metrics
• Issue Reporting
  • Where to Report Issues
  • Before Creating an Issue
  • Types of Issues
  • Writing Effective Issues
  • Issue Labels and Categories
  • Special Issue Types
  • Following Up on Issues
  • Issue Etiquette
  • Quality Checklist
• Community Guidelines
  • Our Values
  • Code of Conduct
  • Communication Guidelines
  • Contributing Guidelines
  • Recognition and Credit
  • Types of Contributions
  • Decision-Making Process
  • Conflict Resolution
  • Community Events and Initiatives
  • Special Programs
  • Contributing to These Guidelines
  • Feedback and Questions
  • Contact Information
  • Thank You

Quick Start for Contributors

If you’re eager to get started, here’s the quickest path to making your first contribution:

1. Browse Issues: Check out open issues to find something that interests you

2. Fork & Clone: Fork the repository and clone your fork locally

3. Set Up Environment: Follow our Setting Up Your Environment guide

4. Make Changes: Create a feature branch and implement your changes

5. Test: Ensure your code has ≥90% test coverage with pytest --cov

6. Submit: Open a pull request with a clear description of your changes

Getting Help

If you need help at any point in the contribution process:

• GitHub Issues: Ask questions on our issue tracker

• Documentation: Check our comprehensive docs at docs.quactuary.com

• Community: Join discussions in our GitHub repository

We’re here to help make your contribution experience as smooth as possible!

Types of Contributions We Welcome

We welcome many different types of contributions:

Code Contributions

• Bug fixes

• New features

• Performance improvements

• Algorithm implementations

• Test coverage improvements

• MCP tool development

Documentation

• API documentation improvements

• Tutorial writing

• Example notebooks

• Translation of documentation

Community

• Bug reports

• Feature requests

• Code reviews

• Helping other contributors

Research

• Quantum algorithm development

• Actuarial method research

• Performance benchmarking

• Mathematical validation

Recognition

Contributors are recognized in several ways:

• Contributors list in the repository

• Acknowledgment in release notes for significant contributions

• Co-authorship opportunities for research contributions

• Community recognition and thanks

We value all contributions, from single-line bug fixes to major feature additions!