Merge pull request #3070 from betagouv/comment-contribuer

Ajout d'un CONTRIBUTING.md

CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Comment contribuer
+
+demarches-simplifiees.fr est un [logiciel libre](https://fr.wikipedia.org/wiki/Logiciel_libre). Vous pouvez lire et modifier son code-source, sous les termes de la licence AGPL.
+
+Si vous souhaitez apporter des améliorations à demarches-simplifiees.fr, c’est possible !
+
+Le mieux pour cela est de **proposer une modification dans la base de code principale**. Une fois acceptée, votre améliorations sera ainsi disponible pour l’ensemble des utilisateurs de demarches-simplifiees.fr.
+
+Voici la marche à suivre recommandée pour effectuer une modification.
+
+## 1. Discuter de l’amélioration
+
+La première étape est généralement de discuter de l’amélioration que vous proposez (s’il ne s’agit pas d’un changement trivial, comme la correction d’une coquille).
+
+Pour cela, [créez une nouvelle issue](https://github.com/betagouv/tps/issues/new) concernant votre proposition. Autant que possible, indiquez clairement votre besoin, votre cas d’usage – et éventuellement comment vous pensez déjà le résoudre.
+
+Nous pouvons alors discuter, pour vérifier que le besoin exprimé correspond à l’usage de demarches-simplifiees.fr, proposer éventuellement des alternatives, et se mettre d’accord sur une implémentation technique pertinente.
+
+## 2. Proposer du code
+
+Une fois que la discussion est établie, et que les éléments techniques sont dégrossis, vous pouvez proposer des changements au code. Pour cela, effectuez vos modifications en local, et [ouvrez une Pull Request](https://github.com/betagouv/tps/issues/new) avec les changements que vous souhaitez apporter.
+
+Quelques conseils : pensez à bien décrire l’objectif et l’implémentation de votre PR au moment de la créer. Et si vos changements sont importants, découpez-les en plusieurs petites PRs successives, qui seront plus faciles à relire. N’oubliez pas d’ajouter des tests automatisés pour vous assurer que vos changements fonctionnent bien.
+
+Chaque PR ouverte déclenche l’exécution des tests automatisés, et la vérification du format du code. Si vos tests ou votre formattage est en rouge, corrigez les erreurs avant de continuer.
+
+Une personne de l’équipe de développement fera une relecture, en demandant éventuellement des détails ou des changements. Si personne n’a réagi au bout de 5 jours, n’hésitez pas à relancer en ajoutant un commentaire à la PR.
+
+## 3. Intégration
+
+Une fois votre PR approuvée, elle sera intégrée dans la base de code principale.
+
+Nous mettons en production au minimum une fois par semaine (et généralement plus) : vos changements seront disponibles en production sur [demarches-simplifiees.fr](https://www.demarches-simplifiees.fr) quelques jours après.
+
+
+# Héberger demarches-simplifiees.fr
+
+demarches-simplifiees.fr est **compliqué à héberger**. Parmi les problématiques que nous rencontrons :
+
+- **Sécurité et confidentialité des données** : par nature, demarches-simplifiees.fr traite une quantité importante de données personnelles. La sécurité de l’infrastructure doit être contrôlée et certifiée pour garantir la confidentialité des données. Cela implique par exemple une démarche de mise en conformité avec le [Référentiel Général de Sécurité](https://www.ssi.gouv.fr/entreprise/reglementation/confiance-numerique/le-referentiel-general-de-securite-rgs/), qui est un processus assez lourd.
+
+  C’est également valable pour le stockage des pièces-jointes, qui sont souvent des documents d’identités dont la confidentialité doit être garantie.
+- **Utilisation de services externes** : demarches-simplifiees.fr s’interconnecte à de nombreux services externes : des APIs (API Entreprise, API Carto, la Base Adresse Nationale, etc.) – mais aussi des services pour le stockage externe des pièces-jointes, l’analyse anti-virus ou l’envoi des emails. Le fonctionnement de demarches-simplifiees.fr dépend de la disponibilité de ces services externes.
+- **Mises à jour** : le schéma de la base de données change régulièrement. Nous codons également des scripts pour harmoniser les anciennes données. Parfois des modifications ponctuelles sont effectuées sur des démarches anciennes, pour les mettre en conformité avec de nouvelles règles métiers. Nous maintenons également les dépendances logicielles utilisées – notamment en réagissant rapidement lorsqu’une faille de sécurité est signalée. Ces mises à jour fréquentes en production sont indispensables au bon fonctionnement de l’outil.
+
+Si vous souhaitez adapter demarches-simplifiees.fr à votre besoin, nous vous recommandons de **proposer vos modifications à la base de code principale** (par exemple en créant une issue) **plutôt que d’héberger une autre instance vous-même**.
+
+Dans le cas où vous envisagez d’héberger une instance de demarches-simplifiees.fr vous-même, nous n'avons malheureusement pas les moyens de vous accompagner, ni d'assurer de support technique concernant votre installation.

README.md

@@ -2,29 +2,37 @@
 
 ## Contexte
 
-demarches-simplifiees.fr est un site web conçu afin de répondre au besoin urgent de l'État d'appliquer la directive sur le 100 % dématérialisation pour les démarches administratives.
+[demarches-simplifiees.fr](https://www.demarches-simplifiees.fr) est un site web conçu afin de répondre au besoin urgent de l'État d'appliquer la directive sur le 100 % dématérialisation pour les démarches administratives.
 
-## Dépendances
+## Comment contribuer ?
 
-### Tous environnements
+demarches-simplifiees.fr est un [logiciel libre](https://fr.wikipedia.org/wiki/Logiciel_libre) sous licence AGPL.
+
+Vous souhaitez y apporter des changements ou des améliorations ? Lisez notre [guide de contribution](CONTRIBUTING.md).
+
+## Installation pour le développement
+
+### Dépendances techniques
+
+#### Tous environnements
 
 - postgresql
 
-### Développement
+#### Développement
 
 - Yarn : voir https://yarnpkg.com/en/docs/install
 - Overmind :
   * Mac : `brew install overmind`
   * Linux : voir https://github.com/DarthSim/overmind#installation
 
-### Tests
+#### Tests
 
 - Chrome
 - chromedriver :
   * Mac : `brew install chromedriver`
   * Linux : voir https://sites.google.com/a/chromium.org/chromedriver/downloads
 
-## Création des rôles de la base de données
+### Création des rôles de la base de données
 
 Les informations nécessaire à l'initialisation de la base doivent être pré-configurées à la main grâce à la procédure suivante :
 
@@ -34,19 +42,19 @@ Les informations nécessaire à l'initialisation de la base doivent être pré-c
     > create user tps_test with password 'tps_test' superuser;
     > \q
 
-## Initialisation de l'environnement de développement
+### Initialisation de l'environnement de développement
 
 Afin d'initialiser l'environnement de développement, exécutez la commande suivante :
 
     bin/setup
 
-## Lancement de l'application
+### Lancement de l'application
 
     overmind start
 
 L'application tourne à l'adresse `http://localhost:3000`. Un utilisateur de test est disponible, avec les identifiants `test@exemple.fr`/`testpassword`.
 
-## Programmation des jobs
+### Programmation des jobs
 
     AutoArchiveProcedureJob.set(cron: "* * * * *").perform_later
     WeeklyOverviewJob.set(cron: "0 8 * * 0").perform_later
@@ -55,17 +63,17 @@ L'application tourne à l'adresse `http://localhost:3000`. Un utilisateur de tes
     Administrateurs::ActivateBeforeExpirationJob.set(cron: "0 8 * * *").perform_later
     WarnExpiringDossiersJob.set(cron: "0 0 1 * *").perform_later
 
-## Voir les emails envoyés en local
+### Voir les emails envoyés en local
 
-http://localhost:3000/letter_opener
+Ouvrez la page [http://localhost:3000/letter_opener](http://localhost:3000/letter_opener).
 
-## Mise à jour de l'application
+### Mise à jour de l'application
 
 Pour mettre à jour votre environnement de développement, installer les nouvelles dépendances et faire jouer les migrations, exécutez :
 
     bin/update
 
-## Exécution des tests (RSpec)
+### Exécution des tests (RSpec)
 
 Pour exécuter les tests de l'application, plusieurs possibilités :
 
@@ -84,34 +92,36 @@ Pour exécuter les tests de l'application, plusieurs possibilités :
         bin/rake spec SPEC=file_path/file_name_spec.rb
         bin/rspec file_path/file_name_spec.rb
 
-## Ajout de taches à exécuter au déploiement
+### Ajout de taches à exécuter au déploiement
 
         rails generate after_party:task task_name
 
-## Debug
+### Debug
 
 Une fois `overmind` lancé, et un breakpoint `byebug` inséré dans le code, il faut se connecter au process `server` dans un nouveau terminal afin d'intéragir avec byebug :
 
     overmind connect server
 
-## Linting
+### Linting
 
 Le projet utilise plusieurs linters pour vérifier la lisibilité et la qualité code.
 
 - Faire tourner tous les linters : `bin/rake lint`
 - [AccessLint](http://accesslint.com/) tourne automatiquement sur les PRs
 
+### Régénérer les binstubs
+
+    bundle binstub railties --force
+    bin/rake rails:update:bin
+
 ## Déploiement
 
 - Tout nouveau commit ajouté à la branche `dev` est automatiquement déployé [en intégration](https://dev.demarches-simplifiees.fr/)
 - Tout nouveau commit ajouté à la branche `master` est automatiquement déployé [en production](https://www.demarches-simplifiees.fr/)
 
-## Régénérer les binstubs
+## Tâches courantes
 
-    bundle binstub railties --force
+### Tâches Super Admin
-    bin/rake rails:update:bin
-
-## Tâches Super Admin
 
 - ajouter un compte super admin :
   `bin/rake admin:create_admin[email-du-compte-github@exemple.com]`
@@ -122,7 +132,7 @@ Le projet utilise plusieurs linters pour vérifier la lisibilité et la qualité
 - supprimer un compte super admin :
   `bin/rake admin:delete_admin[email-du-compte-github@exemple.com]`
 
-## Tâches d’aide au support
+### Tâches d’aide au support
 
 Des tâches d’aide au support sont prévues dans le namespace `support`.
 Pour les lister : `bin/rake -D support:`.
@@ -131,9 +141,7 @@ Pour les lister : `bin/rake -D support:`.
 
 L'application supporte les navigateurs récents : Firefox, Chrome, Safari, Edge et Internet Explorer 11 (voir `config/browser.rb`).
 
-La compatibilité est testée par Browserstack.
+La compatibilité est testée par Browserstack.<br>[<img src="app/assets/images/browserstack-logo-600x315.png" width="200">](https://www.browserstack.com/)
-
-[<img src="app/assets/images/browserstack-logo-600x315.png" width="300">](https://www.browserstack.com/)
 
 ## Performance