Contributing to FORCE¶

Thank you for considering contributing to force-dataset! Building a reliable open-source catalogue of French power-system data is a massive undertaking, and we welcome help from the community to improve it.

Whether you are fixing a bug, adding a new data source, or improving the documentation, this guide will help you get started.

How to Report Bugs¶

If you run into an issue (such as an API change from a data provider, a gap in the data, or an installation failure), please open a GitHub Issue. To help us fix it quickly, please include:

The exact command you ran (e.g., energy-collect).
The full traceback (the detailed block of error text printed in your terminal).
Your environment details (Operating system and Python version).

How to Suggest Features¶

We are always looking to expand! If you have an idea for a new data source (e.g., Gas consumption, Market Prices) or a methodological improvement for the imputation engine, please open an Issue and tag it with the enhancement label.

Local Development Setup¶

If you want to write code for the project, set up your local environment like this:

Clone the repository to your machine:

git clone [https://github.com/EDF-Lab/force.git](https://github.com/EDF-Lab/force.git)
cd force

Install the package in “editable mode” along with the development tools. (Editable mode links the code directly to your environment, meaning any changes you make to the Python files will take effect immediately without needing to reinstall the package).
```
pip install -e ".[dev]"
```
Run the test suite to verify everything installed correctly:
```
pytest tests/ --tb=short -q
```

Testing a Collector or Transformation Change¶

Running the complete pipeline processes about 1 GB of data and takes several hours. You don’t need to do this for every minor code change! For most patches, you only need to verify the last 60 days of data.

Here is the recommended workflow for testing your changes locally:

Run the collection phase in TEST mode (when prompted for the mode in your terminal, enter 2). This restricts the API calls to just the last two months.
```
energy-collect
```
Run the transformation and assembly scripts to process the data you just downloaded:
```
energy-transform
energy-assemble
```
Audit the resulting DuckDB files (our local analytical database) to ensure your changes didn’t break the table schemas or introduce gaps:
```
energy-check
```

This restricted 60-day window is perfectly sufficient for verifying schema updates, new columns, or fixes to the API mappings.

Note: If you are making changes to the Machine Learning imputation engine, run energy-impute after assembly. If you are modifying pure logic that doesn’t require data downloads, just rely on the unit tests (pytest tests/).

Submitting a Pull Request¶

Ready to share your code?

Fork the repository and create a new branch branching off from main.
Make your changes. Ensure you haven’t broken any existing tests by running pytest tests/.
Keep your commits focused—try to group related changes together rather than mixing a bug fix with a new feature in the same commit.
Open a Pull Request against our main branch. Provide a clear description of what you changed, why you changed it, and any issues it resolves.

Code Style Guidelines¶

To keep the codebase clean and maintainable across multiple contributors, please adhere to the following rules:

Comment the “Why”, not the “What”: Python code is generally readable. Only write inline comments to explain why a specific decision was made (e.g., explaining a quirky workaround for an API limit).
Use Logging, not Print: Avoid using bare print() statements. Use the Python logging module so users can control the verbosity of the output.
Path Management: Always resolve file paths dynamically using __file__-based absolute paths (e.g., Path(__file__).resolve().parent...). Hardcoded relative paths will break depending on where the user executes the script.