Contributing

Contributing#

chainladder-python welcomes volunteers at all levels, whether you are new to actuarial reserving, Python, or both. Feedback, questions, suggestions, and contributions are all highly encouraged.

Why Contribute#

  • Gain practical experience with Python, software development, and actuarial methods.

  • Meet like-minded actuaries that prefer open-source software.

  • Help advance open-source actuarial research and reproducible methodologies.

  • Contributing is rewarding and fun!

How to Contribute#

You can help improve and shape the project in many ways:

  1. Submit bugs or enhancement requests via the issue tracker.

  2. Volunteer to implement code changes for existing issues.

  3. Ask questions or discuss ideas on the discussion forum.

  4. Improve documentation where it is unclear.

  5. Create new examples or tutorials in the examples section.

Contributors Working Group#

We also have a Contributors Working Group that meets for one hour approximately every two weeks. We are part of the CAS volunteer groups and are supported by the CAS. If you are interested, you are welcome to join us through the Open-Source Projects Working Group.

We currently meet on Fridays 11:00am - Noon ET, but we periodically adjust meeting times to accommodate contributors across time zones around the globe. Our meetings are relaxed and collaborative, with discussions around milestones, package design ideas, open issues, and other behind-the-scenes work on GitHub.

We welcome contributors of all skill levels, including CAS members, its affiliate members, industry researchers, educators, students, and CAS candidates. To join us, you may respond to the CAS annual Volunteer Interest and Participation (VIP) Survey, reach out to a CAS staff persons (Heather Davis hdavis@casact.org, Elizabeth Smith esmith@casact.org), or the working group chair (Kenneth Hsu kennethshsu@gmail.com), and we will be happy to welcome you into the group.

API Guidelines#

chainladder-python is designed to follow the style of pandas and scikit-learn. This ensures a consistent API and simplifies new development:

  1. Estimators and transformers should follow the scikit-learn estimator API.

  2. Triangle methods should align with pandas (then NumPy) naming and signature conventions. Domain-specific methods with no equivalent should follow PEP8.

  3. Triangle methods are non-mutating by default. Mutation is allowed only via an inplace argument.

For domain-specific exceptions, discuss on the issue tracker.

Development Environment#

After forking the repository, you can set up a development environment using uv:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add uv to your PATH
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Navigate to your working directory
cd chainladder-python

# Create virtual environment and install all dependencies
uv sync --extra all

Once the environment is set up, we may go into development mode with uv:

# Activate the environment
uv run jupyter-lab # or uv run python

This will install the package in editable mode with all development dependencies. After finishing work, deactivate:

deactivate

Documentation#

Documentation is built with Jupyter Book. From your development environment:

cd docs
jb build .

The generated site is in _build/html. Documentation is maintained in:

  1. Docstrings within the code (hosted in API reference).

  2. User Guide notebooks (/docs/modules).

  3. Tutorial notebooks (/docs/tutorials).

Contributions to documentation are especially helpful for new users.

Pull Requests (PRs)#

Guidelines for PRs:

PRs must:

  • Pass all existing unit tests

  • Undergo independent peer review

PRs are encouraged to:

  • Be small, focused, and modular

  • Link to relevant Issue ticket(s)

  • Include docstring updates for any code changes

  • Update the documentation site for corresponding changes

  • Follow established naming conventions

  • Include new unit tests with reasonable coverage

All PRs should be run locally before submission.

For codebase tests, run:

pytest

For documentation changes, rebuild the docs locally with:

uv run jb build docs --builder=custom --custom-builder=doctest

Large or unfocused PRs may delay merging. Each PR should address a single issue or feature to maintain clarity and quality.