mon-entreprise/CONTRIBUTING.md

# Comment contribuer ?

Merci de prendre le temps de contribuer ! 🎉

Voici quelques informations pour démarrer :

## Rapport de bug, nouvelles fonctionnalités

Nous utilisons GitHub pour suivre tous les bugs et discussions sur les nouvelles fonctionnalités. Pour rapporter un bug ou proposer une évolution vous pouvez [ouvrir une nouvelle discussion](https://github.com/betagouv/mon-entreprise/issues/new). N'hésitez pas à utiliser la recherche pour vérifier si le sujet n'est pas déjà traité dans une discussion ouverte.

## Développement

Si vous voulez participer au développement de nouvelles fonctionnalités, vous pouvez consulter la liste des «[good first issue](https://github.com/betagouv/mon-entreprise/issues?q=is%3Aopen+is%3Aissue+label%3A%22%3Anew%3A+good+first+issue%22) ». Ce sont des fonctionnalités intéressantes qui ne sont normalement pas trop complexe à implémenter. N'hésitez pas à poser toutes vos questions sur ces issues !

### Technologies

L'application est écrite en JavaScript, elle est exécuté uniquement côté client — il n'y a pas de serveur applicatif, nous générons des fichiers `.html` statiques

Nous utilisons :

-   [TypeScript](https://www.typescriptlang.org) pour ajouter un système de typage à notre code JavaScript. Le typage n'est pas utilisé partout et il n'est pas obligatoire de le prendre en compte pour contribuer.
-   [Yarn](https://yarnpkg.com/fr) pour la gestion des dépendances (à la place de NPM qui est souvent utilisé dans les applications JavaScript)
-   [React](https://reactjs.org) pour la gestion de l'interface utilisateur
-   [Redux](https://redux.js.org) pour gérer le “state” de l'application côté client
-   [Prettier](https://prettier.io/) pour formater le code source, l'idéal est de configurer votre éditeur de texte pour que les fichiers soit formatés automatiquement quand vous sauvegardez un fichier. Si vous utilisez [VS Code](https://code.visualstudio.com/) cette configuration est automatique.
-   [Webpack](https://webpack.js.org) pour le “bundling”
-   [Eslint](http://eslint.org) qui permet par exemple d'éviter de garder des variables inutilisées
-   [Ramda](https://ramdajs.com) comme libraire d'utilitaires pour manipuler les listes/objects/etc (c'est une alternative à lodash ou underscore)
-   [Mocha](https://mochajs.org), [Jest](https://jestjs.io) et [Cypress](https://www.cypress.io) pour les l'execution des tests. Plus d'informations dans la section consacrée aux tests.

### Démarrage

Si possible, assurez-vous d'avoir toutes les clés d'API nécessaires dans votre fichier
`mon-entreprise/.env`.  
**NB : ne vous inquiétez pas, ceci n'est pas nécessaire pour effectuer une première contribution à
la base de code !** Cependant, vous en aurez besoin pour la commande `yarn prepare` et pour les
commandes de traduction automatique français -> anglais. Si vous êtes confronté à ce type de besoin,
demandez l'aide des contributeurs du projet.

Si l'historique des commits est trop volumineux, vous pouvez utiliser le paramètre `depth` de git pour ne télécharger que les derniers commits.

```
# Clone this repo on your computer
git clone --depth 100 git@github.com:betagouv/mon-entreprise.git && cd mon-entreprise

# Install the Javascript dependencies through Yarn
yarn install

# Download some data
yarn prepare

# Watch changes in publicodes and run the server for mon-entreprise
yarn start
```

L'application est exécutée sur http://localhost:8080/mon-entreprise pour la version française et
http://localhost:8080/infrance pour la version anglaise.

Pour activer le traçage Redux:

```
REDUX_TRACE=true yarn start
```

### Messages de commit

A mettre sans retenue dans les messages de commit :

https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages

-   🎨 `:art:` when working on the app's visual style
-   🐎 `:racehorse:` when improving performance
-   📝 `:memo:` when writing docs
-   🐛 `:bug:` when fixing a bug
-   🔥 `:fire:` when removing code or files
-   💚 `:green_heart:` when fixing the CI build
-   ✅ `:white_check_mark:` when adding tests
-   ⬆️ `:arrow_up:` when upgrading dependencies
-   :sparkles: `:sparkles:` when formatting, renaming, reorganizing files

Et ceux spécifiques au projet :

-   :gear: `:gear:` pour une contribution au moteur qui traite les YAML
-   :hammer: `:hammer:` pour une contribution à la base de règles
-   :calendar: `:calendar:` pour un changement de règle du à une évolution temporelle (en attendant mieux)
-   :chart_with_upwards_trend: `:chart_with_upwards_trend:` pour une amélioration du tracking
-   :alien: `:alien:` pour ajouter des traductions
-   :wheelchair: `:wheelchair:` pour corriger les problèmes liés à l'accessibilité
-   :fountain_pen: `:fountain_pen:` pour séparer les commits liés à la modification du contenu
-   :mag: `:mag:` pour les modifications liées au référencement naturel

### Tests

Pour la vérification syntaxique :

```sh
$ yarn lint
```

Pour la vérification du typage :

```sh
$ yarn test:type
```

Pour executer les tests unitaires :

```sh
$ yarn test
```

Pour le snapshot testing :

```sh
$ yarn test:regressions
```

Si vous souhaitez mettre à jour les snapshots vous pouvez utiliser le paramètre `--updateSnapshot`, son raccourci `-u`, ou encore le [mode interactif](https://jestjs.io/docs/en/snapshot-testing#interactive-snapshot-mode).

Pour les tests d'intégration sur chacun des 3 sites :

```sh
$ yarn workspace mon-entreprise test:dev-e2e:mon-entreprise
$ yarn workspace mon-entreprise test:dev-e2e:mycompanyinfrance
$ yarn workspace mon-entreprise test:dev-e2e:publicodes
```

### Traduction 👽

Le site est disponible en français, et en anglais sur https://mycompanyinfrance.com

Les traductions se trouvent dans le répertoire `source/locales`.

La librairie utilisée pour la traduction de l'UI est
[react-i18next](https://react.i18next.com/).

Lorsque l'on introduit une nouvelle chaîne de caractère dans l'UI il faut
systématiquement penser à gérer sa traduction, via un composant `<Trans>`, ou
via la fonction `t`

Le circle-ci fait une analyse statique du code pour repérer les chaînes non
traduites, dans le moteur et l'UI :

```sh
$ yarn run i18n:rules:check
$ yarn run i18n:ui:check
```

Pour traduire automatiquement les chaînes manquantes via l'api Deepl :

```sh
$ yarn run i18n:rules:translate
$ yarn run i18n:ui:translate
```

N'oubliez pas de vérifier sur le diff que rien n'est choquant.

### CI/CD

-   Nous utilisons des [Github actions](https://github.com/features/actions) pour faire tourner les builds et
    tests.
-   [Netlify](https://www.netlify.com/), s'occupe de l’hébergement du site sur Internet avec gestion des DNS.

### Analyse des bundles

La commande `yarn run build:analyse-bundle` gènere une visualisation interactive du
contenu packagé, cf.
[webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)

### Modifier publicodes

Publicodes dispose désormais de son propre dépôt GitHub https://github.com/betagouv/publicodes

Néanmoins pour certaines nouvelles fonctionnalités de mon-entreprise nous concervons le besoin de
modifier publicodes avec le moins de frictions possible. Pour tester une évolution du moteur il
serait en effet trop lourd d'avoir à ouvrir d'abord une PR côté publicodes, la merger, publier une
nouvelle version du paquet, puis ré-intégrer cette nouvelle version sur mon-entreprise.

C'est pourquoi nous intégrons le code source du publicode dans le sous-répertoire `publicodes/`. La
commande `git subtree` nous permet de synchroniser les changements effectués dans l'un ou l'autre
des dépôts.

La première chose à faire est d'ajouter une nouvelle `remote` pour `betagouv/publicodes`, ici nous l'appelons simplement `publicodes` :

```sh
git remote add publicodes git@github.com:betagouv/publicodes.git
```

Ensuite il est possible de remonter les changements effectués dans le sous-repertoire `publicodes/` vers la branche master de la remote `publicodes`.

```sh
$ git subtree push --prefix=publicodes publicodes master
```

Dans l'autre sens il est possible de rapatrier les changements avec la commande

```sh
$ git subtree pull --prefix=publicodes publicodes master --squash
```

## Développement de modèles Publicodes

### Traduction des normes (lois) en règles Publicodes

Checklist:

-   [ ] Lire les articles de vulgarisation (sur le site de l'URSSAF, des impôts, etc.).
-   [ ] Utiliser un moteur de recherche spécialisé, comme [RFPaye](https://rfpaye.grouperf.com/).
-   [ ] [Lire les normes][wiki normes] et noter leurs référence dans les règles Publicodes.

[wiki normes]: https://github.com/betagouv/mon-entreprise/wiki/Comment-lire-les-normes-(la-loi)-efficacement-pour-r%C3%A9diger-des-r%C3%A8gles-Publicodes%3F

### Tests

Pour tester les règles, il est recommandé de:

-   faire tourner un simulateur et vérifier à la main l'adéquation des règles avec les normes
    traduites ;
-   créer des cas de tests de non-régression sous la forme de nouveaux snapshots (cf.
    `mon-entreprise/test/regressions`).

## Documentation

### Publicodes

Un tutoriel sur publicodes est disponible sur https://publi.codes.

Un wiki contenant des informations intéressantes sur publicodes et le
raisonnement ayant abouti à ce langage sont dispos sur le repository
[betagouv/publicodes](https://github.com/betagouv/publicodes/wiki), qui est par
ailleurs inutilisé.

Pour se familiariser avec les règles, vous pouvez jeter un œil aux fichiers
contenant les règles elles-mêmes (dans le dossier `rules`) mais cela peut
s'avérer assez abrupt.

Essayez plutôt de jeter un oeil [aux tests](./publicodes/test/mécanismes/expressions.yaml)
dans un premier temps, puis au [mécanismes en
place](./publicodes/source/mecanisms).

## Publier une nouvelle version des paquets publicodes

<!-- TODO: action à déplacer dans le dépot betagouv/publicodes -->

Voici la marche à suivre pour publier une nouvelle version :

1. Renseigner les modifications dans publicodes/CHANGELOG.md
2. Remplacer les références à la précédente version par la nouvelle version dans les packages.json
3. Ajouter tous les changement dans un commit avec le message suivant :
    ```
     📦 Publicodes v1.0.0-beta.<n>
    ```
    > **Important** Le message doit être exactement celui-ci (emoji compris), car le script de déploiement automatique sur le CI se base sur ce dernier.
4. Laisser faire le CI, une fois le commit mergé sur master, le paquet sera déployé effectivement