Contributing to lifelib¶
lifelib is an open source project and welcomes your contribution. There are various ways to contribute to lifelib:
Play around with lifelib and blog about it or post feedbacks on the Discussion page.
Ask questions about lifelib on the Issue page. Others may also have the issues you have, and asking for the solutions may help others having the same issues.
Give enhancement ideas on the Discussion page.
Help improve the documentation of lifelib. Find and report typos, dead links, outdated or unclear descriptions by submitting issues. The lifelib site is generated by Sphinx, a widely used documentation generator, from the makedocs/source directory in the lifelib repository and from the docstrings of models, spaces and cells in lifelib models.
Report bugs by submitting issues on the Issue page if you find any.
Write examples using lifelib models. See the Writing examples section below for more details.
Add a new library to lifelib. See the Adding a new library section below for more details.
You can contribute to lifelib by writing an example using a model in a lifelib library. Before submitting a pull request, open an issue or start a discussion about your work to ask for review.
There are two formats for an example file to be included in a library:
Python script for sphinx-gallery
You can write an example in Jupyter notebook.
The notebook is rendered as part of the lifelib documentation
and linked from the library’s page, and also from the Notebooks page.
See 1. Simple Stochastic Example
for example. This example is written as a Jupyter notebook,
named savings_example1.ipynb, and included in the
In case your example uses a custom model modified from the original
model included in a lifelib library, the custom model is to be
included in the library in addition to the example notebook.
In the case of 1. Simple Stochastic Example,
a custom model named
CashValue_ME_EX1 is included in the
library for the example.
In stead of, or in addition to an example in Jupyter notebook,
you can write a Python script to plot a graph by matplotlib.
The script is rendered as part of the lifelib documentation
and linked from the library’s page, and also from the Gallery page.
To be auto-generated by Sphinx-Gallery, a Sphinx extension
for building a gallery of examples, the script’s name must
be prepended by plot_.
See Account value paths
for example. This example is
named plot_ex1_av_paths.py, and included in the
Adding a new library¶
A library contains at least one model and its documentation, and tests for the model should also be provided. Creating a new library takes a lot of time and effort, so before staring on building a new library, ask the lifelib community on the Discussion page whether the model you plan to develop deserves a new library. Here are some preferable characteristics desired for libraries.
General models without country specific implementations are more preferable than country specific models. In case of country specific models, applicable requirements and standards should be documented.
Practical models are more preferable than illustrative models.
The type of models in a library should not overlap with those in another library. For example, cashflow models of protection and savings products are covered by the
savingsmodels, so if you wants to develop the cashflow models, consider extending the
savingsmodels, instead of proposing a brand new library.
The docstrings of all the space and the cells in the model should be well-documented.