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.

.. _Issue: https://github.com/lifelib-dev/lifelib/issues
.. _Discussion: https://github.com/lifelib-dev/lifelib/discussions
.. _issues: https://github.com/lifelib-dev/lifelib/issues
.. _lifelib site: https://lifelib.io
.. _repository: https://github.com/lifelib-dev/lifelib
.. _makedocs/source: https://github.com/lifelib-dev/lifelib/tree/master/makedocs/source
.. _Sphinx: https://www.sphinx-doc.org/


Important notes
----------------

Your contribution must be your original work
or based on other open-source projects
released under any `permissive open source licenses`_.
Note that GPL is not a `permissive open source license`_.
If your contribution includes code modified from other open source projects,
cite the fact appropriately.
If sample data accompanies your contribution, check the terms of use of
the data and make sure the inclusion of the data does not violate the
terms of use.

.. _permissive open source licenses: https://en.wikipedia.org/wiki/Permissive_software_license
.. _permissive open source license: https://en.wikipedia.org/wiki/Permissive_software_license


Writing examples
------------------

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:

    * Jupyter notebook
    * 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 :doc:`/libraries/savings/savings_example1`
for example. This example is written as a Jupyter notebook,
named *savings_example1.ipynb*, and included in the :mod:`savings` library.
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 :doc:`/libraries/savings/savings_example1`,
a custom model named ``CashValue_ME_EX1`` is included in the :mod:`savings`
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 :doc:`/generated_examples/savings/plot_ex1_av_paths`
for example. This example is
named *plot_ex1_av_paths.py*, and included in the :mod:`savings` library.

.. _Notebooks: https://lifelib.io/notebooks.html
.. _Gallery: https://lifelib.io/generated_examples/index.html
.. _Sphinx-Gallery: https://sphinx-gallery.github.io/stable/index.html

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.
* Names of cells, refs, spaces, models, model folders should
  follow the same naming convention as
  the :mod:`basiclife` and :mod:`savings` 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 :mod:`basiclife` and :mod:`savings` models,
  so if you wants to develop the cashflow models,
  consider extending the :mod:`basiclife` and :mod:`savings` models,
  instead of proposing a brand new library.

Libraries are located in the `lifelib/libraries`_ path in the lifelib repository,
and their documents are located in `makedocs/source/libraries`_ path in the repo.

.. _lifelib/libraries: https://github.com/lifelib-dev/lifelib/tree/master/lifelib/libraries

.. _makedocs/source/libraries: https://github.com/lifelib-dev/lifelib/tree/master/makedocs/source/libraries

The docstrings of all the space and the cells in the model should
be well-documented.