betagouv
/
mon-entreprise
mirror of https://github.com/betagouv/mon-entreprise
1
0
Fork 0
Code Releases Activity
mon-entreprise/CONTRIBUTING.md

143 lines
6.4 KiB
Markdown
Raw Normal View History

Prose dans CONTRIBUTION.md
2019-07-09 12:17:09 +00:00
# Comment contribuer ?
Conseils pour le style de code des contributeurs
2018-01-03 16:18:58 +00:00
Prose dans CONTRIBUTION.md
2019-07-09 12:17:09 +00:00
Merci de prendre le temps de contribuer ! 🎉
Conseils pour le style de code des contributeurs
2018-01-03 16:18:58 +00:00
Prose dans CONTRIBUTION.md
2019-07-09 12:17:09 +00:00
Voici quelques informations pour démarrer :
Conseils pour le style de code des contributeurs
2018-01-03 16:18:58 +00:00
Prose dans CONTRIBUTION.md
2019-07-09 12:17:09 +00:00
## Rapport de bug, nouvelles fonctionnalités
Renommage de syso en mon-entreprise
2019-09-25 15:42:06 +00:00
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.
Prose dans CONTRIBUTION.md
2019-07-09 12:17:09 +00:00
## Développement
Renommage de syso en mon-entreprise
2019-09-25 15:42:06 +00:00
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 !
Prose dans CONTRIBUTION.md
2019-07-09 12:17:09 +00:00
### 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 :
🔥 Migration vers TypeScript Outils ====== Ce commit retire le tooling de Flow, et ajoute le support de TypeScript pour les fichiers .ts et .tsx. Il n'est pas nécessaire de tout migrer d'un coup ce qui facilite la transition. On garde en effet le compilateur Babel avec un preset TypeScript (ce qui permet donc de retirer à la fois les types Flow et TypeScript) plutôt que d'utiliser le compilateur standard pour la conversion du code. Cela permet aussi de mieux s'intégrer avec d'autres outils, notamment les test-runners. Ajout d'une nouvelle commande `yarn run type-check`, intégrée dans CircleCI. Par ailleurs ajout du support de l'opérateur ?? pour donner des valeurs par défaut (nullish-coalescing-operator). Typage des libraires tierces ============================ Les principales libraires que nous utilisons ont un typage TypeScript de bon niveau, ce qui facilite l'intégration. J'ai mis à jour react-i18next et i18next afin de corriger un problème de typage. Typage du code ============== Le typage est loin d'être complet dans ce commit, en particulier il manque les types relatifs au state Redux, ainsi qu'au moteur (règle, explication). Néanmoins le typage des contextes fonctionne, en particulier sitePaths (avec un type récursif non trivial !) qui a déjà permis de détecter un lien mort. Le typage des "paths" (Components/, Règles/, etc.) fonctionne bien, y compris avec l'auto-complétion automatique des import par Typescript. TypeScript se révèle déjà bien agréable dans VSCode (auto-complétion, refacto, etc.) ! Reste à migrer progressivement le reste du code !
2019-10-26 16:21:09 +00:00
- [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.
Prose dans CONTRIBUTION.md
2019-07-09 12:17:09 +00:00
- [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)
✅ Snapshot testing Ajout de tests de non-regressions des calculs afin d'éviter de déployer silencieusement des effets de bord non-désirés dans les règles de calculs. J'ai ajouté Jest pour sa fonction de snapshot testing qui est particulièrement adaptée pour ce type de cas (voir #717). J'ai essayé avec mocha-snapshot sans succès. J'ai eu un petit peu de mal à configurer Jest, car il n'est pas possible de ré-utiliser la configuration Webpack, qu'il faut alors dupliquer. C'est pourquoi j'ai limité l'utilisation de Jest aux seuls tests de snapshot. À voir s'il y a un intérêt à migrer les tests Mocha vers Jest ultérieurement. Fixes #717
2019-10-18 17:15:58 +00:00
- [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.
Prose dans CONTRIBUTION.md
2019-07-09 12:17:09 +00:00
### Démarrage
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
Renommage de syso en mon-entreprise
2019-09-25 15:42:06 +00:00
git clone --depth 100 git@github.com:betagouv/mon-entreprise.git && cd mon-entreprise
Prose dans CONTRIBUTION.md
2019-07-09 12:17:09 +00:00
# Install the Javascript dependencies through Yarn
yarn install
# Run the server
yarn start
```
L'application est exécuté sur https://localhost:8080/mon-entreprise pour la version française et http://localhost:8080/infrance pour la version anglaise.
### Messages de commit
Conseils pour le style de code des contributeurs
2018-01-03 16:18:58 +00:00
Create CONTRIBUTION.md
2017-03-20 09:24:02 +00:00
A mettre sans retenue dans les messages de commit :
https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages
:memo: ajoute l'emoji :fountain_pen: pour les modifications liées au contenu
2018-08-24 10:13:28 +00:00
- 🎨 `: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
[cdd] :art: Amélioration visuelle de la partie réponses de la conversation
2017-03-27 13:55:09 +00:00
Create CONTRIBUTION.md
2017-03-20 09:24:02 +00:00
Et ceux spécifiques au projet :
Conseils pour le style de code des contributeurs
2018-01-03 16:18:58 +00:00
:memo: ajoute l'emoji :fountain_pen: pour les modifications liées au contenu
2018-08-24 10:13:28 +00:00
- :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
✅ Snapshot testing Ajout de tests de non-regressions des calculs afin d'éviter de déployer silencieusement des effets de bord non-désirés dans les règles de calculs. J'ai ajouté Jest pour sa fonction de snapshot testing qui est particulièrement adaptée pour ce type de cas (voir #717). J'ai essayé avec mocha-snapshot sans succès. J'ai eu un petit peu de mal à configurer Jest, car il n'est pas possible de ré-utiliser la configuration Webpack, qu'il faut alors dupliquer. C'est pourquoi j'ai limité l'utilisation de Jest aux seuls tests de snapshot. À voir s'il y a un intérêt à migrer les tests Mocha vers Jest ultérieurement. Fixes #717
2019-10-18 17:15:58 +00:00
### Tests
Pour executer les tests unitaires :
```sh
$ yarn run test-common
```
Pour le snapshot testing :
```sh
$ yarn run 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).
Enfin pour les tests d'intégration :
```sh
$ yarn run test-cypress
```
:alien: Vérifie que tous les éléments d'ui sont traduits Tous les éléments à traduire (via la balise <Trans> ou la fonction 't') sont analysé statiquement. Si il manque une traduction, la PR est bloquée Ajoute un script de traduction automatique via `yarn run i18n:ui:translate` Met à jour CONTRIBUTING.md avec les infos sur la traduction
2020-01-21 18:29:43 +00:00
### Traduction 👽
Le site est disponible en français, et en anglais sur https://mycompanyinfrance.com
🔥 Rangement * Suppression de fichiers "documentation" qui n'avaient pas été modifiés depuis deux ans et n'étaient plus à jour * Déplacement de base.yaml dans un répertoire publicode de premier niveau. Déplacement de la traduction des règles dans le répertoire source/locales * Suppression de la page /documentation/exemples qui n'était pas référencée sur le site, pas consultée dans nos stats, et boguée. * Suppression de la configuration git quotepath qui ne semble plus utile
2020-02-04 16:05:59 +00:00
Les traductions se trouvent dans le répertoire `source/locales`.
:alien: Vérifie que tous les éléments d'ui sont traduits Tous les éléments à traduire (via la balise <Trans> ou la fonction 't') sont analysé statiquement. Si il manque une traduction, la PR est bloquée Ajoute un script de traduction automatique via `yarn run i18n:ui:translate` Met à jour CONTRIBUTING.md avec les infos sur la traduction
2020-01-21 18:29:43 +00:00
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 le diff que rien n'est choquant.
:memo: CI/CD in contributing docs (#935) :memo: CI/CD in contributing docs
2020-03-26 20:12:04 +00:00
### CI/CD
- [CircleCI](https://circleci.com/) s'occupe de faire tourner les builds et
tests.
- [Netlify](https://www.netlify.com/), s'occupe de l’hébergement du site sur Internet
sur internet avec gestion des DNS.
## Documentation
### Publicodes
Le code publicodes, relatif aux règles, est dans le dossier `publicodes`. Vous y trouverez notamment un README qui vous initiera au langage.
Pour information, 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 oeil aux fichiers contenant les règles elles-mêmes (dans le dossier `publicodes/rules`) mais cela peut s'avérer assez abrupt.
Essayez plutôt de jeter un oeil [aux tests](./test/mécanismes/expressions.yaml) dans un premier temps, puis au [mécanismes en place](./source/engine/mecanisms.yaml).