complement doc contribution

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contribuer
 
-Merci d'envisager nous aider sur ce projet. Tout type de contribution est bienvenue.
+Merci de nous aider sur ce projet ou d'envisager de le faire. Tout type de contribution est bienvenue.
 
 ## Contributions autres que du code
 
@@ -10,4 +10,150 @@ Vous pouvez également parcourir les [issues existantes](https://github.com/IGNF
 
 ## Modifier le code ou la documentation
 
-Si vous voulez corriger une anomalie ou apporter une nouvelle fonctionnalité vous-même, faites ces modifications dans un fork du dépôt et soumettez-nous une [pull request](https://docs.github.com/fr/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
+Si vous voulez corriger une anomalie ou apporter une nouvelle fonctionnalité vous-même, faites ces modifications dans un fork du dépôt et soumettez-nous une [pull request](https://docs.github.com/fr/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
+
+N'hésitez pas à consulter la documentation [rédacteur](docs/redacteur.md) si vous voulez modifier le contenu du site ou [développeur](docs/developpeur.md) si vous voulez modifier ses fonctionnalités.
+
+Ci-dessous, un guide pas à pas décrit le processus de contribution via un fork et une pull request. Si vous êtes déjà familier de Git et Github, il ne vous sera pas nécessaire mais peut constitue néanmoins un document auquel vous pouvez vous référer en cas de doute. Il répète quelques éléments présents dans la documentation d'installation.
+
+### Première installation
+
+-   Créez un compte Github
+-   Installez Git sur votre poste de travail
+-   Configurez Git avec votre nom et votre email
+-   Forkez le dépôt
+-   Clonez votre fork (en utilisant SSH ou l'url HTTPS) :
+
+```bash
+git clone [email protected]:your_GH_account/cartes.gouv.fr-documentation.git
+```
+
+-   Placez vous dans le nouveau dossier créé :
+
+```bash
+cd cartes.gouv.fr-documentation
+```
+
+-   Ajoutez le dépôt principal comme source "upstream" (en utilisant l'url HTTPS) :
+
+```bash
+git remote add upstream https://github.com/IGNF/cartes.gouv.fr-documentation
+```
+
+-   Votre remote devrait maintenant être "origin", votre fork, et "upstream" devrait correspondre au dépôt principal sur IGNF. Vous pouvez le vérifier en utilisant la commande :
+
+```bash
+git remote -v
+```
+
+-   Vous devriez voir quelque-chose comme ça :
+
+```
+origin	[email protected]:your_GH_account/cartes.gouv.fr-documentation.git (fetch)
+origin	[email protected]:your_GH_account/cartes.gouv.fr-documentation.git (push)
+upstream	https://github.com/IGNF/cartes.gouv.fr-documentation.git (fetch)
+upstream	https://github.com/IGNF/cartes.gouv.fr-documentation.git (push)
+```
+
+Il est important qu'"origin" pointe bien vers votre fork.
+
+### Maintenir votre dépôt à jour
+
+-   Assurez vous d'être sur la branche main :
+
+```bash
+git checkout main
+```
+
+-   Téléchargez les mises à jour de toutes les branches de upstream :
+
+```bash
+git fetch upstream
+```
+
+-   Mettez à jour votre branche main locale au même niveau que la branche main du dépôt principal :
+
+```bash
+git rebase upstream/main
+```
+
+### Mettre à jour si vous avez des changements locaux
+
+Si la commande précédente `rebase` échoue avec le message "error: cannot rebase: You have unstaged changes...",
+mettez vos modifications locales de côté dans le "stash" en utilisant la commande :
+
+```bash
+git stash
+```
+
+-   Maintenant vous pouvez "rebaser" :
+
+```bash
+git rebase upstream/main
+```
+
+-   Puis réappliquez vos changements mis de côté :
+
+```bash
+git stash apply
+```
+
+-   Supprimez les changements que vous aviez mis dans le "stash" (optionnel):
+
+```bash
+git stash pop
+```
+
+### Créer une branche
+
+Maintenant que vous avez mis à jour votre branche main locale, vous pouvez créer une nouvelle branche à partir d'elle :
+
+-   Créez une branche (ici appelée "nouvelle-doc") et placez vous dessus :
+
+```bash
+git checkout -b nouvelle-doc
+```
+
+### Apporter des changements
+
+Vous pouvez utiliser l'éditeur de votre choix pour apporter des changements. Nous recommandons [Visual Studio Code](https://code.visualstudio.com/download).
+
+### Commiter les changements
+
+-   Ajoutez les fichiers au commit (fichiers modifiés ou ajoutés) :
+
+```bash
+git add file1
+git add file2
+```
+
+-   Commitez le changement :
+
+```
+git commit -m "ajout nouvelle doc"
+```
+
+NB : dans l'exemple, le commit porte le message "ajout nouvelle doc". Utilisez un message court mais explicite pour décrire vos changements. Ne décrivez pas tous vos commits de la même façon.
+
+### Pousser les changements sur GitHub
+
+-   Poussez les changements de votre nouvelle branche sur votre fork sur github :
+
+```bash
+git push origin nouvelle-doc
+```
+
+### Créer une pull-request
+
+AU moement de votre push, GitHub va vous répondre directement en vous donnant l'URL à laquelle vous pouvez créer votre pull request. Vous pouvez suivre cette URL ou vous rendre à tout moment sur votre fork sur Github, afficher la branche "nouvelle-doc" et Github vous montrera un bandeau avec un bouton pour créer une nouvelle pull request.
+
+### Après avoir créé une pull request
+
+Les mainteneurs du dépôt vont maintenant examiner votre pull request.
+Si besoin, ils travailleront avec vous pour améliorer vos changements.
+
+Une fois que les changements dans votre pull request seront prêts à être intégrés, les mainteneurs décideront de la façon la plus appropriée de les intégrer dans la branche main du dépôt principal :
+
+-   en mergeant la branche avec tous ces commits + un merge commit,
+-   en combinant tous les commits en un seul (squash)
+-   ou en rebasant tous vos commits sur la branche main, à la suite des commits déjà présents.

docs/developpeur.md

@@ -2,43 +2,15 @@
 
 ## Installation
 
-**Cloner le dépôt** :
+Voir [la documentation d'installation](installation.md).
 
-```bash
-git clone https://github.com/IGNF/cartes.gouv.fr-documentation
-```
-
-**Naviguer dans le dossier** :
-
-```bash
-cd cartes.gouv.fr-documentation
-```
-
-**Installer les dépendances** :
-
-```bash
-npm install
-```
-
-**Exécuter Eleventy** :
-
-Construire un livrable, indexé avec pagefind pour la recherche :
-
-```bash
-npm run build
-```
-
-L'exécuter sur le serveur de développement local :
-
-```bash
-npm start
-```
+## Soumettre une contribution
 
-Ou exécuter un [mode de débogage](https://www.11ty.dev/docs/debugging/).
+Voir [CONTRIBUTING.md](../CONTRIBUTING.md).
 
 ## Développement
 
--   Modifier le fichier [`eleventy.config.js`](eleventy.config.js) pour configurer les paramètres d'Eleventy différemment.
+-   Modifier le fichier [`eleventy.config.js`](eleventy.config.js) pour configurer les paramètres de build d'Eleventy différemment.
 -   Ajouter des composants du DSFR dans le dossier [`_includes/components`](_includes/components) et des [mises en page](https://www.11ty.dev/docs/layouts/) dans le
     dossier [`_includes/layouts`](_includes/layouts).
     -   Ajouter de nouveaux conteneurs markdown dans le fichier [`markdown-custom-containers.js`](markdown-custom-containers.js).

docs/installation.md

@@ -0,0 +1,65 @@
+# Installation de l'environnement de travail
+
+Cette documentation s'adresse aussi bien aux développeurs qu'aux rédacteurs qui souhaitent installer le site localement.
+
+Pour les rédacteurs, cette documentation est technique mais vous permet de visualiser vos modifications et nouveaux articles dans un navigateur avant de les proposer en les poussant sur github.com.
+
+## Prérequis
+
+Pour disposer d'un environnement de travail confortable, il est recommandé de disposer des logiciels suivants :
+
+-   **Visual Studio Code** (https://code.visualstudio.com/download) comme éditeur pour tous les langages utilisés par le site, notamment le markdown (mais vous pouvez utiliser un autre éditeur si vous préférez)
+-   **NodeJS** (https://nodejs.org/en/download/prebuilt-installer) pour pouvoir construire le site localement sur votre poste de travail et le prévisualiser.
+-   **Git** (https://gitforwindows.org/, lien pour Windows) pour interagir avec le dépôt de code et github.com.
+
+Git et NodeJS sont indispensables pour aller plus loin dans l'installation.
+
+## Installation
+
+Sous Windows, après avoir installé _Git for Windows_, vous devriez avoir accès au clic droit dans l'explorateur à un menu contextuel "Git Bash here" qui vous permet de lancer une invite de commande qui est très adaptée à l'utilisation de Git et offre une bonne coloration syntaxique. Il est recommandé de la préférer à l'invite de commande par défaut de Windows.
+
+### Cloner le dépôt
+
+Clonez le dépôt (ou votre fork du dépôt, ce qui est préférable) sur votre poste de travail dans un nouveau dossier nommé `cartes.gouv.fr-documentation` :
+
+```bash
+git clone https://github.com/IGNF/cartes.gouv.fr-documentation
+```
+
+Rendez vous dans le dossier pour exécuter les commandes suivantes :
+
+```bash
+cd cartes.gouv.fr-documentation
+```
+
+### Installer les dépendances
+
+```bash
+npm install
+```
+
+Cette commande créé un sous-dossier `node_modules` dans lequel vont s'installer toutes les dépendances du projet, conformément à ce qui est décrit dans les fichiers `package.json` et `package-lock.json`.
+
+### Exécuter Eleventy pour construire le site
+
+```bash
+npm run build
+```
+
+**Eleventy** est le logiciel utilisé pour construire le site. Il transforme les fichiers _markdown_ ou _nunjucks_ du dossier `content` en pages html à l'aide des gabarits du dossier `_includes`. Ensuite **Pagefind** indexe le contenu de ces pages pour que le moteur de recherche du site soit fonctionnel.
+
+A l'issu de cette commande, le dossier `_site` est rempli ou modifié avec un contenu HTML, visualisable dans un navigateur.
+
+### Déployer en local
+
+```bash
+npm start
+```
+
+Cette commande rend le site disponible à l'adresse `https://localhost:8080/fr/` et reste active, à l'écoute des changements que vous effectuez dans le projet.
+
+**:sparkles: Vous avez maintenant réussi à déployer le site en local :sparkles:**
+
+Le site est ainsi maintenu à jour en même temps que vous modifiez des fichiers. Mais les contenus modifiés ne sont pas indexés pour la recherche et il peut arriver que certaines modifications ne soient pas immédiatement prises en compte. Dans ce cas, arrêtez le site (`Ctrl+C`) et relancez les 2 commandes précédentes : `npm run build` puis `npm start`.
+
+Les développeurs peuvent exécuter un [mode de débogage](https://www.11ty.dev/docs/debugging/).

docs/redacteur.md

@@ -1,5 +1,15 @@
 # Documentation rédacteur
 
+## Installer le projet et le déployer localement
+
+Installer le projet localement pour prévisualiser les modifications que vous effectuez est recommandé.
+
+Voir [la documentation d'installation](installation.md).
+
+## Soumettre une contribution
+
+Voir [CONTRIBUTING.md](../CONTRIBUTING.md).
+
 ## Structure
 
 Tout le contenu du site se trouve dans le répertoire `content`. En tant que rédacteur, aucune modification n'est généralement nécessaire dans d'autres répertoires.
@@ -9,8 +19,6 @@ Il est toutefois conseillé d'avoir une arborescence qui correspond à cette nav
 
 Documentation : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/navigation/
 
-La mise en page avec un menu de navigation latéral n'est pas encore implémentée.
-
 ## Syntaxe Markdown
 
 Référence : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/md-cheatsheet/