-
Notifications
You must be signed in to change notification settings - Fork 97
Guide pour la contribution
Statut de cette page: RFC
Les recommandations de ce document sont proposées pour discussion par la communauté. Pour apporter un commentaire, éditez cette page à la section "Commentaires" ci-dessous, intervenez sur le Slack ou ouvrez une issue sur le dépôt.
OpenFisca France a pour ambition d'être une représentation exécutable des aspects calculables du droit français, notamment social, fiscal et du travail.
Les manifestations les plus notables de cette intention sont :
- une API de calcul exposée via le web
- un référentiel des éléments du modèle (variables, paramètres, entités…), accessible par le web
Le code source d'OpenFisca étant ouvert, toute personne est libre de le réutiliser en l'état et de le modifier pour l'adapter à ses besoins. Pour autant, la communauté OpenFisca n'intègre les modifications proposées comme contributions que sous certaines conditions.
Les contributions sont pertinentes quant elles constituent une évolution du système socio-fiscal sous la forme de variables, formules ou paramètres, ou une amélioration technique de l'existant. Les contributions qui ajoutent un nouveau "modèle d'exploitation" sont intrinsèquement plus difficiles à relire et évaluer, donc à intégrer.
Si vous vous proposer de contribuer à OpenFisca un travail qui présente l'une des caractéristiques ci-desous, nous vous invitons à prendre préalablement contact avec les mainteneurs pour guider vos contributions :
- contribution autre que l'ajout d'une variable, d'un paramètre, d'une formule
- modifications très substantielles (de nombreuses formules) du modèle
Une Pull Request représente l'aboutissement d'un travail de contribution, et l'étape qui précède immédiatement l'intégration de celle-ci dans OpenFisca-France.
Avant d'ouvrir une Pull Request, assurez-vous d'avoir répondu aux interrogations suivantes :
- de quelle demande découle cette fonctionnalité ?
- dans quel contexte cette fonctionnalité serait-elle utilisée ?
- quelles exigences de qualité (précision du calcul, mise à jour des données) en résulte ?
- quels sont les apports les plus substantiels de votre travail ?
- quel(les) formule(s) serviront probablement de point d'entrée ?
- avez-vous besoin pour ce travail d'un avis d'expert, fonctionnel ou technique ?
- si oui, avez-vous pris contact au préalable avec la communauté pour un accompagnement ?
- avez-vous pris soin de bien vérifier que votre modification n'affecte pas la cohérence globale du modèle entre ses différentes composantes de revenus, prélèvements sociaux, cotisations sociales, impôts et prestations ?
- votre contribution adhère-t-elle aux standards techniques du dépôt ?
- avez-vous limité autant que possible la duplication avec le code existant ?
- tous les éléments de votre PR sont-ils absolument nécessaires, avez-vous effacé vos "traits de construction" ?
- votre PR ajoute-t-elle des éléments inédits dont il faut assurer la maintenance dans le temps ?
- si oui, avez-vous documenté les procédures, la temporalité, les conditions de cette maintenance ?
- avez-vous doté cette PR d'un ensemble de cas de test qui en documente le fonctionnement ?
- cette couverture de test est-elle suffisante pour en assurer la non régression ?
/// - CETTE PARTIE EST UN DRAFT EN ATTENTE DE LA CLOTURE DE LA RFC 1672 ///
En 2021, il a été décidé de favoriser le reversement des travaux de l'Institut des Politiques Publiques vers OpenFisca. Cela implique de travailler sur des fichiers communs, notamment les fichiers de paramètres. Il a donc été enclanché le projet d'harmonisation, qui vise à fusionner les paramètres IPP et les paramètres OF tels qu'ils l'étaient.
Ces fichiers avaient divergé, par leur présence, pas tous n'existent dans l'un ou l'autre repo, et par leur contenu, notamment les différents champs des métadonnées. Cette fusion indiquait donc de:
- Choisir les champs à garder/supprimer
- Déterminer les règles de remplissage de chaque champ
- Déterminer une méthode de travail pour réaliser l'harmonisation
Une partie des règles listées dans la section Bonnes pratiques de la modélisation est donc issue de ce travail. Quant à la méthode de travail, nous allons la détailler ci-dessous.
La première règle de l'harmonisation est de ne perdre aucune information en cours de route. Cela implique notamment que les #commentaires trouvés dans les fichiers .yaml sont déplacés dans le champ notes.
La deuxième règle est de respecter l'arborescence IPP dans le dossier parameters. Cela implique donc de déplacer les fichiers de paramètres au fur et à mesure de l'harmonisation. Et donc d'updater les chemins correspondants dans le code des variables.
La troisième règle est de se plier aux formalismes décidés par la communauté OpenFisca (cf. section Bonnes pratiques de modélisation). Dans les cas où les règles ne sont pas exhaustives et où il faudrait faire des choix, la recommandation est la suivante:
- Expliciter le problème et le choix fait sur la PR
- Faire remonter la question en issue et ouvrir aux propositions en RFC
- Détailler le choix final de la conduite à tenir sur le présent WiKi
L'objectif est de garder un maximum de cohérence dans le travail effectué.
Afin de permettre des revues faciles, les PR doivent rester de taille raisonnable. Pour cela, on s'attaque à l'harmonisation par sous-dossiers. L'idée est de choisir un dossier (côté IPP) avec un nombre raisonnable de paramètres (environ 10-20).
On ouvre ensuite une branche au nom du dossier, par exemple harmonisation_csg_crds et on la pousse immédiatement pour indiquer que ce travail est en cours.
On peut ouvrir la PR associée en draft pour y noter ses questionnements et décisions au fur et à mesure.
Côté OpenFisca, on recréée l'arborescence IPP du dossier parameters jusqu'à notre sous-dossier. S'il faut renommer des dossiers, il faut penser à changer les chemins des paramètres affectés dans le code Python.
Chaque dossier et sous-dossier doit contenir un fichier index.yaml qui contient les informations suivantes:
-
description: reprend en français l'arborescence qui mène à ce dossier, ce qui donne une description exhaustive et unique de ce noeud -
ux_name: ce nom court détaille ce noeud par rapport au noeud en amont. Il est choisi de telle façon que l'enchaînement desux_namedesindex.yamlde tous les noeuds jusqu'à un paramètre donne une description unique et exhaustive de ce paramètre. -
description_en: la description en anglais de ce noeud
Par exemple, dans le dossier openfisca_france/parameters/prelevements_sociaux/contributions_sociales/csg/chomage, le fichier index.yaml sera:
description: Contribution Sociale Généralisée (CSG) sur les allocations chômage
metadata:
ux_name: Allocations chômage
description_en:
Une fois le dossier créé/renommé côté OpenFisca, il s'agit de reverser l'information des paramètres IPP dedans. Pour cela, il va falloir découper les .yaml IPP qui contiennent souvent plusieurs paramètres. En effet, côté OpenFisca, on a toujours un seul paramètre par fichier, à l'exception des barèmes qui contiennent un seuil et un taux.
Si le paramètre que l'on veut reverser existe déjà côté OpenFisca: il suffit d'ajouter les champs et/ou valeurs du paramètre IPP dans le paramètre OpenFisca, en respectant les règles de bonne pratiques (cf. section ci-dessus).
Pour les références, par défaut on transfère toutes les références IPP qui sont postérieures à la première valeur du paramètre, à moins d'être sûr qu'elles ne concernent pas ce paramètre, mais un autre paramètre du yaml. En effet, il est possible d'avoir des références qui ne correspondent pas à une date de changement de value d'un paramètre, mais qui lui sont bien associées, en indiquant par exemple un changement de place de l'article de loi, d'assiette ou autre.
Si on est face à des paramètres IPP qui n'existent pas côté OpenFisca, il faudra les créer. Avant tout, on fait une recherche poussée pour vérifier qu'ils n'existent pas ailleurs dans OpenFisca. Une recherche par value peut se révéler très efficace.
/// - FIN DU DRAFT ///
[🤔 @sandcha] Dans la section Apport fonctionnel, nous évoquons quels sont les apports les plus substantiels de votre travail ? : N'est-ce pas un peu vaste ? Une fois l'apport substantiel principal identifié, en quoi est-ce que cela peut guider la décision d'ouvrir la PR ? On peut interpréter cela en quels sont les calculs principaux apportés par votre travail ? (ce que nous souhaiterions ?) ou votre proposition a-t-elle un apport substantiel ? (ce qui ne devrait pas être une question ou venir à la revue ?)