Contributing#
chainladder-python
welcomes volunteers for all aspects of the
project. Whether you’re new to actuarial reserving, new to python, or
both, feedback, questions, suggestions and, of course, contributions are
all welcomed.
How Do I Contribute?#
There are tons of ways to improve and shape the direction of this project.
Submitting bugs or enhancements to the issue tracker.
Volunteer to draft code changes for existing issues.
Ask questions through the discussion forum.
Improve the documents where they are unclear.
Make new examples.
Why Contribute?#
Contributing to an open-source project is an incredibly rewarding learning experience. Whether your interests are in learning python, implementing functionality you need, software development, or gaining a deeper appreciation for how actuarial methods work, you will learn a ton.
Actuarial literature has a history of being free and open source, but we’re barely scratching the surface on reproducible research or a similar level of freedom with regard to tools.
It’s fun.
If you are interested in contributing. Here are a few helpful hints to make the journey enjoyable.
API Guidelines#
chainladder-python
by design is intended to mimic the API styles of
pandas
and scikit-learn
. This benefits the on-going development
of the package as API design is not up for debate which should eliminate
many inquiries on how to write new functionality. In general,
the API for any estimator/transformer must strive to follow the scikit-learn estimator API.
Methods for the
Triangle
classes should generally follow the same name and signature aspandas
if it exists, followed bynumpy
. Methods that are truly domain specific with no equivalency inpandas
ornumpy
should follow PEP8 naming convention.Triangle
methods should never be self-mutating by default. Mutation is allowable with aninplace
argument similar to pandas.
Occasionally, there will be cases where domain-specific functionality does not fit neatly into the existing API and these should be discussed in issue.
Setting Up Development Environment#
Once you’ve forked the repository, you’ll need a development
environment. A conda development environment chainladder
including
all testing and documentation dependencies can be set up as follows:
conda config --set channel_priority strict
conda env create --file environment-dev.yaml
conda config --set channel_priority false
conda activate cl_dev
When you are done with development, you should exit cl_dev
.
conda deactivate
Updating the Documentation#
The documentation is build using jupyter-book
.
From your cl_dev
or cl_docs
conda environment, docs can be generated by navigating
to the ‘/docs’ folder and running jb build .
at the command line. The
built site will be available in your _build\html
folder.
Editing of the documentation happens in one of four places:
First, the docstrings of the actual library live with the code and get hosted as part of the API reference
The User Guide is written in jupyter notebooks in the ‘/docs/modules’ folder.
The tutorials are jupyter notebooks stored at ‘docs/tutorials’.
Docs are a great way for newer users to get involved. New user help is especially helpful in clarifying the docs as they are the primary user of the docs.
Pull Requests#
Pull requests (PR) should be tied to an issue. It’s generally a good idea to keep issues and pull requests small. Like all projects, the larger the PR, the less likely it will be merged.
All pull requests must pass existing unit tests. On occasion, existing unit tests can be in violation of the API guidelines. These unit tests should be refined to accommodate the API ethos set forth above. It is a good practice to run tests ahead of pushing changes to Github. That said, these unit tests will be run by Github.
pytest chainladder
New functionality should include new unit tests with a reasonable level of code coverage.