# Contribuer à OpenFisca-France

Avant tout, merci de votre volonté de contribuer au bien commun qu'est OpenFisca !

Afin de faciliter la réutilisation d'OpenFisca et d'améliorer la qualité du code, les contributions à OpenFisca suivent certaines règles.

Certaines règles sont communes à tous les dépôts OpenFisca et sont détaillées dans [la documentation générale](https://openfisca.org/doc/contribute/guidelines.html).

## Vérifications de code automatiques avec pre-commit

Avant chaque commit, des vérifications automatiques sont exécutées via [pre-commit](https://pre-commit.com/) pour assurer la qualité du code et la cohérence du style.

### Installation

Pre-commit est installé comme dépendance du projet. Pour l'activer, lancez :

```sh
uv run pre-commit install
```

### Vérifications exécutées

Les vérifications suivantes sont automatiquement exécutées avant chaque commit :

- **flake8** : Validation du style Python (même chose que `make check-style`)
- **yamllint** : Validation du format YAML des paramètres et tests
- **Vérifications de base** : Fusion de conflits, fin de fichier, espaces inutiles, etc.

### Exécuter les vérifications manuellement

Vous pouvez exécuter les vérifications manuellement sur tous les fichiers :

```sh
uv run pre-commit run --all-files
```

Ou sur les fichiers staged uniquement :

```sh
uv run pre-commit run
```

## Format du Changelog

Les évolutions d'OpenFisca-France doivent pouvoir être comprises par des réutilisateurs qui n'interviennent pas nécessairement sur le code. Le Changelog, rédigé en français, se doit donc d'être le plus explicite possible.

Chaque évolution sera documentée par les éléments suivants :

- Sur la première ligne figure en guise de titre le numéro de version, et un lien vers la Pull Request introduisant le changement. Le niveau de titre doit correspondre au niveau d'incrémentation de la version.

> Par exemple :
> # 13.0.0 - [#671](https://github.com/openfisca/openfisca-france/pull/671)
>
> ## 13.2.0 - [#676](https://github.com/openfisca/openfisca-france/pull/676)
>
> ### 13.1.5 - [#684](https://github.com/openfisca/openfisca-france/pull/684)

- La deuxième ligne indique de quel type de changement il s'agit. Les types possibles sont :
  - `Évolution du système socio-fiscal` : Amélioration, correction, mise à jour d'un calcul. Impacte les réutilisateurs intéressés par les calculs.
  - `Amélioration technique` : Amélioration des performances, évolution de la procédure d'installation, de la syntaxe des formules… Impacte les réutilisateurs rédigeant des règles et/ou déployant leur propre instance.
  - `Correction d'un crash` : Impacte tous les réutilisateurs.
  - `Changement mineur` : Refactoring, métadonnées… N'a aucun impact sur les réutilisateurs.

- **Dans le cas d'une `Évolution du système socio-fiscal`** , il est ensuite précisé :
  - Les périodes concernées par l'évolution. Les dates doivent être données au jour près pour lever toute ambiguïté : on écrira `au 01/01/2017` et non `pour 2017` (qui garde une ambiguïté sur l'inclusion de l'année en question).
  - Les zones du modèle de calcul impactées. Ces zones correspondent à l'arborescence des fichiers dans le modèle, sans l'extension `.py`.

> Par exemple :
> - Périodes concernées : Jusqu'au 31/12/2015.
> - Zones impactées : `prestations/minima_sociaux/cmu`

- Enfin, dans tous les cas hors `Changement mineur`, les corrections apportées doivent être explicitées de détails donnés d'un point de vue fonctionnel : dans quel cas d'usage constatait-on un erreur / un problème ? Quelle nouvelle fonctionalité est disponible ? Quel nouveau comportement est adopté ?

> Par exemple:
>
> * Détails :
>   - Ces variables renvoient désormais un montant annuel et non mensuel :
>     - `acs`
>     - `bourse_college`
>     - `bourse_lycee`
>   - _Les valeurs mensuelles précédentes étaient obtenues par une division par 12 et non par un calcul réel._
>
> Ou :
>
> * Détails :
>   - Déplacement du test runner depuis `france` vers `core`.
>   - _Il devient possible d'exécuter `openfisca-run-test` sur un fichier YAML. [Plus d'informations](https://openfisca.org/doc/openfisca-python-api/openfisca-run-test.html)._

Dans le cas où une Pull Request contient plusieurs évolutions distinctes, plusieurs paragraphes peuvent être ajoutés au Changelog.

## Tester une version spécifique de Python

Grace à UV il est facile de tester la compatibilité d'OpenFisca-France avec une version spécifique de Python, de Numpy et de Core par exemple :

```sh
uv run --python 3.13.7 --with numpy==2.4.0 --with openfisca_core==44.0.3 openfisca test  --country-package openfisca_france tests/calculateur_impots/yaml/credit_assloy.yaml
```

## Mettre à jour les dépendances

Pour mettre à jour le fichier `uv.lock` avec les dernières version compatible avec le [pyproject.toml](pyproject.toml) il faut lancer la commande suivante :

```sh
uv sync --upgrade
```

## Debug des tests YAML avec VS Code

Si vous souhaitez utiliser le debugger de VS Code avec les tests YAML, par exemple pour investiguer la commande suivante :

`openfisca test --country-package openfisca_france --verbose tests/impot_revenu/contribution_differentielle_hauts_revenus_2026.yaml`

Il faut créer un fichier de configuration `.vscode/launch.json` avec le contenu suivant :

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Debug current YAML test file",
            "type": "debugpy",
            "request": "launch",
            "module": "openfisca_core.scripts.openfisca_command",
            "args": [
                "test",
                "--country-package",
                "openfisca_france",
                "--verbose",
                "${file}"
            ],
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}",
            "python": "${workspaceFolder}/.venv/bin/python",
            "justMyCode": false,
        }
    ]
}
```

Puis dans VS Code, ouvrir le fichier YAML à debugger, et lancer le debugger avec la configuration `Python: Debug current YAML test file` dans l'onglet _Run and Debug_ à gauche.
