FACTS Module Contributor Guide¶

Here you'll find an overview of contributing a module to FACTS, including links to detailed instructions for various steps of the process.

Most of the content assumes you already have a module partially developed, or already developed elsewhere and will be porting a version into the FACTS framework.

Process¶

Below are steps and associated documentation and examples to guide you through the process of developing a FACTS module and contributing it to the FACTS framework.

Step 1: Review FACTS module requirements¶

Find the module requirements document here

Step 2: Create a repository for your module¶

We suggest using the module template available on the FACT-Sealevel GitHub organization.

Step 3: Develop your module¶

For a step-by-step guide on building your module, see the module development tutorial.

Step 4: Add your module to the FACTS module registry¶

See the tutorial on submitting a module to the module registry.

Other information¶

Modules written in other languages¶

The examples in this documentation focus on modules that are developed in Python (so far). However, your module does not need to be written in Python to be a part of FACTS. As long as your module generates projections that look like the outputs of other FACTS modules, and, if applicable, ingests projections generated by FACTS modules, it can be a part of the FACTS framework.

FACTS-wrapper of existing modules¶

If you have a module written in another language that you would like to submit to FACTS, it is possible to generate a thin Python wrapper to allow it to run within a FACTS experiment alongside other modules. For an example, see the emulandice2 module. Feel free to reach out to the FACTS development team if you are in this situation, we are happy to work with you to bring your module into FACTS.

Making changes to your module¶

It is very likely that you will need to make updates to your module after it has been submitted to the FACTS framework. FACTS's modular and flexible design means that no other modules or packages need to be updated to accomodate changes in a particular module, only that module's registry entry.

FACTS/FEB will not start using a new version of a module until the container specified in its module YAML file is updated. Therefore, once changes are made in a module, it is highly recommended that you issue a new release of the module. Then, go through the steps in the FMR tutorial to clone the repo, make updates and open a PR with the changes. Check back soon for more detailed instructions on this step, or don't hesitate to reach out to a member of the FACTS development team.