Commit c472dc4b authored by Lorien Benda's avatar Lorien Benda
Browse files

mise à jour de la partie sur les outils + correction pb de liens

parent 9cac66bc
Pipeline #148732075 passed with stages
in 4 minutes and 57 seconds
......@@ -23,7 +23,6 @@ const sidebar = [
title: "Guide de contribution",
path: "/contribuer/Guide_contribution",
children: [
"/contribuer/Guide_contribution/partager_des_sources",
"/contribuer/Guide_contribution/contactez_nous"
]
},
......@@ -35,15 +34,18 @@ const sidebar = [
"/contribuer/Guide_utilisation_des_outils/Introduction_Gitlab",
"/contribuer/Guide_utilisation_des_outils/tutoriel_markdown",
"/contribuer/Guide_utilisation_des_outils/Ticket",
"/contribuer/Guide_utilisation_des_outils/demande_fusion",
"/contribuer/Guide_utilisation_des_outils/Modifier_une_fiche",
"/contribuer/Guide_utilisation_des_outils/Creer_une_fiche",
"/contribuer/Guide_utilisation_des_outils/inclure_image",
"/contribuer/Guide_utilisation_des_outils/processus_relecture",
"/contribuer/Guide_utilisation_des_outils/erreur_pipelines",
"/contribuer/Guide_utilisation_des_outils/partage_document",
"/contribuer/Guide_utilisation_des_outils/contribution_tables",
"/contribuer/Guide_utilisation_des_outils/Forum",
"/contribuer/Guide_utilisation_des_outils/developpement_local",
"/contribuer/Guide_utilisation_des_outils/Cheat_Sheet.md",
"/contribuer/Guide_utilisation_des_outils/exercices_formation"
"/contribuer/Guide_utilisation_des_outils/exercices_formation",
"/contribuer/Guide_utilisation_des_outils/Forum"
]
},
"/contribuer/A_propos"
......
......@@ -5,8 +5,6 @@
Le projet de la documentation collaborative a démarré en [février 2019](https://gitlab.com/healthdatahub/formation/documentation-snds/-/commit/5c7086aa52624c3a1c59234064f78d3a82a4b03a) à l'initiative de la Drees, de la Cnam et de l'INDS devenu le Health Data Hub.
Il est actuellement le fruit de contributions de plusieurs auteurs, et est maintenu par l'équipe Open Source du Health Data Hub.
## Gouvernance
## Auteurs
La documentation étant collaborative, différents [auteurs/mainteneurs](https://gitlab.com/healthdatahub/documentation-snds/-/graphs/master) participent au projet.
......
......@@ -6,7 +6,8 @@ Toute contribution est la bienvenue, est soumise à la licence MPL-2.0 (comme l
Toute personne souhaitant contribuer est invitée à le faire. Les contributions peuvent porter sur:
* la proposition d'amélioration, correction, modification via l'utilisation des [Tickets](../Guide_utilisation_des_outils/Ticket.md),
* la [améliorations, corrections et modifications](../Guide_utilisation_des_outils/Modifier_une_fiche.md),
* la [création de nouvelles fiches](../Guide_utilisation_des_outils/Creer_une_fiche.md).
* la [création de nouvelles fiches](../Guide_utilisation_des_outils/Creer_une_fiche.md)
* le [partage de sources](../Guide_utilisation_des_outils/partage_document.md) : pdf, présentation, programmes, _etc_.
Toutes améliorations, même d'apparence mineure comme la correction de fautes d'orthographe, améliorent pour tous la qualité du contenu. Un processus de relecture et de validation, décrit ci-dessous, a été mis en place afin de garantir un contenu de qualité.
......@@ -17,7 +18,7 @@ Chaque contribution à la documentation est soumise à une relecture par les pai
Dès lors qu’une contribution est proposée comme ajout à la documentation dans sa version public (hors travail en cours), elle doit être relue par un pair. Pour cela, la [procédure de demande de fusion](../Guide_utilisation_des_outils/Introduction_Gitlab.md) doit être suivie et un relecteur doit être assigné. Ce relecteur peut-être n'importe quel membre de la communauté incluant les maintainers indiqués plus loin. Soit le relecteur invite le contributeur à modifier sa contribution, soit il l’approuve pour passer à l’étape suivante.
### Demande d’aide expertise SNDS
Si besoin est, les experts SNDS du Health Data Hub peuvent aider à la relecture : Anne Cuerq et Emmanuel Stranadica. Vous pouvez également contacter le Hub en cas de doute : <<opensource.healt-data-hub.fr>>
Si besoin est, les experts SNDS du Health Data Hub peuvent aider à la relecture : Anne Cuerq et Emmanuel Stranadica. Vous pouvez également contacter le Hub en cas de doute : <<opensource@healt-data-hub.fr>>
### Correction d’une contribution
Si une relecture appelle une [correction](../Guide_utilisation_des_outils/Modifier_une_fiche.md), le contributeur est invité à modifier sa contribution et la soumettre à nouveau en suivant la même procédure.
......@@ -28,7 +29,7 @@ Enfin, après avoir été relue et approuvée, la contribution doit être valid
- Pierre-Alain Jachiet (Drees, pierre-alain.jachiet@sante.gouv.fr, ID gitlab : @pajachiet),
- Olivier de Fresnoye (HDH, olivier.defresnoye@health-data-hub.fr , ID gitlab : @ofrsn),
- Tim Vlaar (HDH, tim.vlaar@health-data-hub.fr, ID gitlab : @tim.vlaar),
- Salma El Oualydy (HDH, salma.eloualydy@health-data-hub.fr, ID gitlab : @salmael )
- Salma El Oualydy (HDH, salma.eloualydy@health-data-hub.fr, ID gitlab : @salmael )
- Maeva Kos (HDH, maeva.kos@health-data-hub.fr, ID gitlab : @maevakos )
## Discuter avec la communauté
......
# Partage de documents existants/programmes
<!-- SPDX-License-Identifier: MPL-2.0 -->
De nombreuses organisations ont documenté le SNDS pour des besoins internes.
Ce travail n'est souvent pas accessible à la communauté plus large des utilisateurs du SNDS.
Une contribution de grande valeur consiste donc à partager publiquement des documents existants dans votre organisation.
## Où publier des documents (hors programmes) ?
Vous avez deux options pour publier ces documents
- un dossier servant de [boite aux lettres]() est disponible sur Gitlab. Vous pouvez y déposer des documents. Nous nous occuperons de les placer dans les dossiers adéquats et les documents pourront être convertis en page de documentation si cela est jugé approprié.
- ou directement dans le dossier de votre [organisme](https://gitlab.com/healthdatahub/documentation-snds/-/tree/master/ressourceses). Les documents pourront être également être convertis en page de documentation.
- sur le site internet de votre organisation.
Ils seront référencés par un lien hypertexte dans la section [ressources externes](../../ressources/internet.md).
Une [fiche explicative](../../contribuer/Guide_utilisation_des_outils/partage_document.md) sur le partage de document est diponible sur le guide de contribution.
::: Tips
N'oubliez pas de renommer le fichier partagé. Le nom doit être sous la forme : Année-Mois-Jour_Organisation_nom-fichier_MLP-2.0.extension`
:::
## Partage de programmes
Le partage de programmes ou scripts d'analyses est très utile pour la communauté.
Dans les fiches de courtes sections de code sont souvent partagées.
Les programmes plus conséquents, par exemple un script complet d'analyse, sont partagés dans le dépôt dédié [programme-snds](https://gitlab.com/healthdatahub/programmes-sdns). Les programmes partagés dans ce dépôt dédié sont sous licence APACHE 2.0. Une [fiche](../../ressources/programmes.md) les repertoriant est disponible sur le site de la documentation.
\ No newline at end of file
......@@ -5,11 +5,12 @@ L'essentiel du guide de contribution est résumé sous la forme de Cheat Sheet p
Une Cheat Sheet Markdown est [téléchargeable](../../files/images/tutoriel_gitlab/2020-03-30_HDH_Cheatsheet-markdown_MLP-2.0.pdf).
<object data="../../files/images/tutoriel_gitlab/2020-03-30_HDH_Cheatsheet-markdown_MLP-2.0.pdf" type="application/pdf" width="750px" height="750px">
<p style="text-align: center;">
<object data="../../files/images/tutoriel_gitlab/2020-03-30_HDH_Cheatsheet-markdown_MLP-2.0.pdf" type="application/pdf" width="500px" height="450px">
<embed src="../../files/images/tutoriel_gitlab/2020-03-30_HDH_Cheatsheet-markdown_MLP-2.0.pdf" type="application/pdf">
<p>This browser does not support PDFs. Please download the PDF to view it: <a href="../../files/images/tutoriel_gitlab/2020-03-30_HDH_Cheatsheet-markdown_MLP-2.0.pdf">Download PDF</a>.</p>
</embed>
</object>
</p>
D'autres Cheat Sheet sont à venir prochainement !
\ No newline at end of file
# Créer une fiche
<!-- SPDX-License-Identifier: MPL-2.0 -->
\ No newline at end of file
<!-- SPDX-License-Identifier: MPL-2.0 -->
Les pages du site internet sont des fichiers textuels, stockés dans différents dossiers à la racine, principalement `introduction` pour les tutoriels haut niveau, `fiches` pour les fiches thématiques, et `glossaire`.
## Créer un Ticket
Avant de créer une fiche, un [ticket](Ticket.md) décrivant une proposition de fiche doit être créé. Les personnes susceptibles de pouvoir participer à la fiche soit en tant que contributeurs, soit en tant que relecteur, peuvent être mentionnées dans le ticket. Cela permet d'informer la communauté sur l'évolution du projet de documentation.
## Créer une nouvelle fiche
Après avoir créé un ticket, retourner dans le menu principal `Dépot`. Allez dans le dossier `fiches` ou `glossaire` selon le type de fiche que vous souhaitez créer. Cliquer sur l'onglet `+` et choisir `nouveau fichier`.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-13_HDH_creer-fiche_MLP-2.0.png" alt="wip" width="900"/>
</p>
Une fenêtre d'édition s'ouvre. Celle-ci est identique à celle lors de la [modification de fiche](Modifier_une_fiche.md).
* Mettre un nom de fichier finissant par `.md`
* Écrire la fiche au format Markdown, en mettant cette ligne de commentaire après le titre.
```
<!-- SPDX-License-Identifier: MPL-2.0 -->
```
::: tip
- le nom d'une fiche doit obligatoirement se terminer par `.md` pour indiquer à Gitlab le format du fichier. Le nom doit être en minuscule (sauf sigle) et sans espace, pour simplifier les liens internes.
- le texte est rédigé au format markdown. Lorsque la fiche est créée, la barre d'édition Markdown n'est pas visible. Elle appraitra une fois le premier commit et la demande de fusion enregistrés.
- Cliquer sur Soft wrap pour éviter que la longueur des lignes soit supérieure à celle de l’écran.
- La fonction `Aperçu` (prévisualisation de la fiche) n'est pas disponible. Elle le sera une fois le premier commit et la demande de fusion enregistrés.
:::
Un formulaire en bas de la page éditée permet d'enregistrer vos modifications dans un commit :
* Écrivez un message décrivant les modifications apportées: une description courte, puis éventuellement une description plus longue séparée par une ligne vide.
* Choisissez le nom d'une nouvelle branche de travail, **avec un nom explicite**. N'oubliez pas de remplacer les espaces par des tirets, sinon un message d'erreur s'affichera.
* En bas de page, la case `créer une nouvelle demande de fusion` est automatiquement cochée. Laissez cette case cochée.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-13_HDH_creer-fiche-edition_MLP-2.0.png" alt="wip" width="900"/>
</p>
## Enregistrer la fiche (demande de fusion ou merge)
Une page s'ouvre alors pour configurer la demande de fusion.
- Donner un titre, remplir la description
- Ajouter des assignés pour la [relecture et validation](../Guide_contribution)
- Si le travail n’est pas fini et que des modifications seront apportées ultérieurement, cocher la case `Start the title with WIP`
- Soumettre votre merge-request en bas de page.
::: tip
Enregistrer une demande de fusion ne veut pas dire que la fusion se lancera automatiquement après cette demande. L'incorporation des modifications proposées dans la documentation nécessite une [validation](../Guide_contribution/README.md) de certains membres sur Health Data Hub. Des modifications peuvent toujours être apportées sur la même fiche, dans la même demande de fusion (et donc sur la même branche).
Les demandes de fusions sont validées par [certains membres de HDH](../Guide_contribution/README.md).
:::
## Naviguer dans une demande de fusion (merge-request)
Pour apprendre à naviguer dans une demande de fusion, se reporter à la fiche [dédiée](demande_fusion.md).
## Apporter des modifications supplémentaires dans la même demande de fusion
Ce processus est décrit dans la fiche [Modifier une fiche](Modifier_une_fiche.md#apporter-des-modifications-supplémentaires-dans-la-même-demande-de-fusion)
## Suggérer des modifications
Lors du [processus de relecture](../Guide_contribution/README.md#processus-de-relecture-et-validation), des modifications peuvent être suggérées par le relecteur.
Se référer à la fiche [processus de relecture](processus_relecture.md) dédiée.
## Incorporation des modifications dans le projet
Lorsque le [processus de relecture](../Guide_contribution/README.md#processus-de-relecture-et-validation) est terminé, les modifications peuvent être incorporées dans la documentation. Aller dans l'onglet `Vue d'ensemble` de la demande de fusion. Enlever l'étiquettes `Etape: en cours` si elle a été mise. Enlever le statut `WIP` en allant dans le bouton `Editer`. Ajouter l'étiquette `Etape : Prêt fusion`.
Cela permet aux mainteneurs du projet de savoir visuellement quelles demandes de fusion sont prêtes à être incorporées à la documentation.
Une description complète des demandes de fusion est disponible dans la fiche [dédiée](demande_fusion.md)
\ No newline at end of file
# Utilisation du Forum
<!-- SPDX-License-Identifier: MPL-2.0 -->
\ No newline at end of file
<!-- SPDX-License-Identifier: MPL-2.0 -->
Le [forum d'entraide du SNDS](https://entraide.health-data-hub.fr/) est ouvert à tous. Il peut permettre d'échanger sur le SNDS, sur les appels à projets proposés par le Hub et de discuter de la documentation collaborative. Les posts peuvent être lus par tous même sans être inscrit. Pour répondre à une question, ou en poser une, il faut s'identifier (bouton en haut à droite).
## Naviguer dans le forum
Les posts peuvent être affichés et classés par catégorie (bouton `Catégorie`), par le nombre de lecture (`Top`), ou par date de création (`Récent`).
Les catégories disponibles sont : `annonces`, `FAQ`, `Documentation collaborative`, `Divers`.
## Poser une question
Pour poser une question cliquer sur le bouton `Ouvrir une ébauche`. Une fenêtre d'édition de texte et une prévisualisation apparait. Il est possible de rédiger au format Markdown. Il faut mettre un titre, choisir une catégorie, éventuellement une étiquette optionnelle. En cliquant sur `Créer le sujet`, le post est publié.
## Répondre à une question
Pour répondre à une question, ouvrir le post, et cliquer sur le bouton bleu `répondre`.
## Gitlab et forum
Lors de la publication d'une fiche, il est fortement recommandé de faire une annonce sur le forum dans la catégorie `Documentation collaborative`.
......@@ -15,48 +15,131 @@ Nous présentons ici une introduction à GitLab pour les autodidactes, ou comme
La documentation est écrit en texte "brute", avec un balisage léger appelé **Markdown**, qui permet d'indiquer la mise en page.
Se référer au [Tutoriel Markdown](tutoriel_markdown.md) pour plus de détails.
## Concepts clés de git et GitLab
Gitlab est une plateforme opensource et collaborative de développement basé sur Git. Gitlab permet d'héberger des projets web, du code, de la documentation. La gestion des différentes versions et conflits est prise en compte dans Gitlab et permet le travail de nombreux collaborateurs simultanément, efficacement et de manière interactive.
- `commit` : Un commit est un ensemble de modifications sur un ou plusieurs fichiers
([exemple](https://gitlab.com/healthdatahub/documentation-snds/commit/553cdd3b07bd2853e7f642b077f48e493413c00e)).
Git a été développé à l'origine pour la gestion et le développement du code source pour le kernel de Linux.
À chaque commit est associé une description concise.
L'enchaînement des commits représente l'[historique](https://gitlab.com/healthdatahub/documentation-snds/commits/master) des modifications.
## Changer la langue dans Gitlab
Il est possible de paramétrer GitLab en français dans l'onglet `Preferences` des `Settings` de votre compte (en haut à droite de la fenêtre).
Ce guide se base sur la version française de l'interface. Il est à noter que la traduction n'est pas complète et que certains termes ne sont pas traduits.
- `branche` : Les branches permettent de gérer plusieurs versions de travail parallèles.
## Naviguer dans Gitlab
Le site web de la documentation publie la branche principale, appelée `master`.
Les branches de travail sont nommées selon l'objet des modifications apportées.
### Liste de projets
En cliquant sur le logo de gitlab en haut à droite, la liste des projets auxquels vous participez est disponible. Pour chaque projet, il est indiqué le nom, si le projet est public (logo de la Terre) ou privé (logo d'un cadenas), votre statut (développeur ou mainteneur), ainsi que la date de la dernière mise à jour.
- `merge-request` : Les merge-request (MR) permettent d'intégrer une branche de travail dans la branche principale.
![Editer sur Gitlab](../../files/images/2020-03-05-HDH-introduction-gitlab_MLP-2.0.jpg)
### Interface Gitlab pour un projet
Après avoir sélectionné un projet, la page qui s'affiche contient:
- le chemin du projet
- l'onglet [*Dépôt*](Introduction_Gitlab.md#dépôt) dans le menu à droite contient l'ensemble des données constituants le projet et la totalité des historiques de modification
- l'onglet [*Ticket*](Introduction_Gitlab.md#ticket) dans le menu déroulant contient les discussions préparatoires/Ticket
- l'onglet [*Demande de fusion*](Introduction_Gitlab.md#demande-de-fusion) permet l'intégration des travaux réalisés à la documentation
Chaque élément est détaillé ci-dessous.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-20_HDH_naviguer-projet_MLP-2.0.png" alt="changer branche" width="1000"/>
</p>
#### Dépôt
##### Fichiers
En cliquant sur `Dépôt`>`Fichiers` dans le menu à droite, les différents dossiers de la documentation sont accessibles. Les fiches de la documentation sont contenues dans le dossier `fiches`, les fiches du glossaire sont contenues dans le dossier `glossaire`. Les documents pdf, images sont contenus dans le dossier `files`.
Au-dessus des dossiers, il est affiché le dernier `commit` soit une description (auteur, date et description) des dernières modifications apportées au projet de la documentation.
En cliquant sur une fiche, une page de prévisualisation s'affiche. Cette page permet de prévisualiser la fiche, visualiser la fiche au format markdown, d'[éditer la fiche](Modifier_une_fiche.md). Au-dessus du titre de la fiche, il est indiqué la dernière modification ayant eu lieu sur cette fiche (le dernier `commit`).
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-15_HDH_presentation-fiche_MLP-2.0.png" alt="changer branche" width="1000"/>
</p>
##### Commits
En cliquant sur `Dépôt`>`Commits` dans le menu à droite, l'[historique](https://gitlab.com/healthdatahub/documentation-snds/commits/master) des modifications ayant eu lieu s'affiche via des commits. Un commit est une description des modifications effectuées. Il comprends l'auteur, la date et une courte description des modifications ([exemple](https://gitlab.com/healthdatahub/documentation-snds/commit/553cdd3b07bd2853e7f642b077f48e493413c00e)).
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-15_HDH_commit-depot_MLP-2.0.png" alt="changer branche" width="1000"/>
</p>
#### Ticket
Les [tickets](Ticket.md) sont des outils de communications autour du projet. Ils peuvent être attribués à une ou plusieurs personnes en désignant des assignés. Ils peuvent être utilisés pour signaler un problème, proposer une amélioration sur le site de la documentation, proposer une nouvelle idée de fiche.
Les tickets peuvent être visualisés sous la forme de liste, tableaux, ou encore par étiquettes.
##### Liste
Sous forme de liste les tickets sont classés par ordre de création. Chaque ticket comprend un numéro (`#numéro` permettant de l'identifier, un titre, la date d'ouverture ainsi que l'auteur. Des étiquettes peuvent être présentes à côté du ticket pour apporter des informations sur le type d'action à faire et l'état d'avancement. Dans le cadre de la documentation collaborative, les étiquettes disponibles sont Rédaction, Développement, Bug, A faire, En cours, Prêt fusion.
Tant que le ticket est ouvert, il est classé dans l'onglet `Open`, s'il est résolu il est classé dans l'onglet `Closed`.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-15_HDH_ticket-liste_MLP-2.0.png" alt="changer branche" width="1000"/>
</p>
*a) Représentation schématique des branches dans Gitlab
b) Exemple de visualisation obtenue dans Gitlab pour le projet de la documentation collaborative du SNDS*
##### Tableaux
L'affichage des tickets sous la forme de tableau permet de savoir quelles fiches sont à faire, celles qui sont en cours de rédaction et d’y contribuer éventuellement. Il est possible d'afficher uniquement les tickets qui comporte une étiquette en allant dans la barre de recherche `Lable` et en ajoutant `=` et `Nom de l'étiquette`.
Les modifications proposées dans la branche de travail sont discutées et validées avant d'être publiées.
Pour cela, les relecteurs commentent la MR dans l'onglet *Discussion*, ou font des remarques ligne par ligne dans l'onglet *Changes*.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-15_HDH_ticket-tableau_MLP-2.0.png" alt="changer branche" width="1000"/>
</p>
### Notion de branches et de travail à plusieurs en parallèle
Gitlab est un outil extrêmement puissant permettant de collaborer à plusieurs sur un même projet et en prenant en compte les conflits d'édition.
Pour cela, Gitlab utilise des *branches*. Les branches permettent de gérer plusieurs versions de travail en parallèles. Le site web de la documentation publie la branche principale, appelée `master`. Les notions de branches sont souvent illustrées dans des schémas comme celui-ci dessous.
Prenons l'exemple de deux contributeurs qui souhaitent pour l'un corriger une faute d'orthographe et pour l'autre créer une nouvelle fiche sur le cepidc.
Ces deux contributeurs vont pourvoir éditer la documentation de façon indépendante. Avant toute modification, le projet est représenté par un rond bleu dans le schéma ci-dessous et est sur la branche principale *master*.
Afin de pouvoir corriger les fautes d'orthographes repérées, le premier contributeur va faire une copie du projet de la documentation, corriger l'orthographe et va l'enregistrer sur une nouvelle branche appelée ici *correction orthographe*. Le nom de la branche est choisi par le contributeur lors que la copie du projet initial. Les branches de travail sont nommées selon l'objet des modifications apportées. Le projet initial qui était représenté par un rond bleu est donc copié dans une version de travail avec correction des fautes d'orthographes, qui est ici le rond vert. La correction des fautes d'orthographes est indiqué par un commit, représenté par une flèche dans le schéma.
Un second contributeur, souhaite lui ajoute une nouvelle fiche. Il va donc copier le projet initial (rond bleu) et intégrer à cette copie la nouvelle fiche. L'ajout sera enregistré avec un commit. La version de travail de ce second contributeur correspond donc au premier rond violet sur le schéma.
A ce stage 3 versions coexistent donc en même temps: la version principale disponible sur le site web dans la branche master. La version du premier contributeur avec des corrections de faute d'orthographe sur la branche *correction-orthographe*, et la version du second contributeur avec une nouvelle fiche sur la branche *creation-fiche-cepidc*. Ces deux dernières versions ne sont visibles que sur Gitlab, en [choisissant la branche de travail](Introduction_Gitlab.md#choisir-une-version-de-travail).
Le premier contributeur ayant fini ses corrections décide de les intégrer à la documentation principale, les différences entre le rond vert et le rond bleu initial seront donc incorporées à la documentation pour donner un nouveau rond bleu. Ce processus d'incorporation s'appelle une demande de fusion (_Merge Request_ en anglais).
Le second contributeur peut continuer d'apporter des ajouts/modifications sur la nouvelle fiche. Ce second apport, sera encore une fois enregistré par un commit. Le projet correspondra alors à ce moment le second rond violet pour le second contributeur. A ce stade, la version web de la documentation comprendra donc les corrections d'orhographe (puisqu'elles ont été intégrées) mais pas encore la nouvelle fiche cepidc. Pour rendre disponible la fiche cepidc, il faudra donc faire une nouvelle demande de fusion entre le second rond violet et le second rond bleu.
Les demandes de fusion/merge-request (MR) permettent donc d'intégrer une branche de travail dans la branche principale.
<style>
.responsive-wrap iframe{ max-width: 95%; }
</style>
<div class="responsive-wrap">
<p style="text-align:center;">
<iframe src="https://docs.google.com/presentation/d/e/2PACX-1vTNK8oG33Ikp4aqr_7KIWTvfC3ka9lu0G54uSfEMuyC9j67kOgwMhZE4nEc-_RgG1BDE-QGiR0PouS_/embed?start=false&loop=false&delayms=3000" frameborder="0" width="960" height="569" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true">
</iframe>
</iframe>
</p>
</div>
### Demande de fusion
Les modifications proposées dans la branche de travail sont discutées et validées avant d'être publiées. Ces modifications peuvent être retrouvées dans l'onglet `Demande de fusion` du menu à droite.
Pour cela, les relecteurs commentent la demande de fusion dans l'onglet `Discussion`, ou font des remarques ligne par ligne dans l'onglet `Changes`.
Par défaut, seul l'auteur initial d'une branche en modifie le contenu, afin d'éviter des conflits d'édition.
Si un relecteur souhaite ajouter des modifications (=commits) sur une branche, il en fait d'abord la demande.
Lors de l'intégration d'une MR à la branche master, d'éventuels conflits d'éditions sont gérés par les mainteneurs.
Lors de l'intégration d'une demande de fusion à la branche principale master, d'éventuels conflits d'éditions sont gérés par les mainteneurs.
Pour limiter ces conflits, il faut limiter la divergence des branches de travail par rapport à la branche master.
On découpera donc les contributions en petit morceaux cohérents, rapides à valider et intégrer.
## Édition en ligne sur gitlab.com
Une fiche détaillée est dédiée aux [demandes de fusion](demande_fusion.md)
### Choisir une version de travail
Pour choisir une version de travail, il suffit d'aller dans l'onglet `Dépôt`, puis de cliquer sur le menu déroulant où il est indiqué *master*. Toutes les branches encore ouverte et n'ayant pas encore été fusionnées à la branche principale sont disponibles dans ce menu.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-15_HDH_image-branche_MLP-2.0.png" alt="changer branche" width="1000"/>
</p>
La solution la plus simple pour éditer la documentation est d'utiliser le site web [GitLab](https://gitlab.com).
## Procédure de contribution à la documentation
Les différentes notions abordées précédemment sont exploitées lors d'une contribution à la documentation via Gitlab. Le processus de contribution est décrit dans la figure ci-dessous.
::: tip GitLab Web IDE
Nous décrivons ici le mode d'édition simple, fichier par fichier.
Gitlab offre une interface d'édition plus aboutie, appelée `Web IDE`, que nous vous invitons à tester également.
:::
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-10_HDH_procedure-contribution_MLP-2.0.png" alt="wip" width="900"/>
</p>
::: tip Interface en français
Il est possible de paramétrer GitLab en français dans l'onglet `Preferences` des `Settings` de votre compte.
Ce guide se base sur la version française de l'interface. Il est a noter que la traduction n'est pas complète et certains termes ne sont pas traduits.
:::
Des fiches sur les [tickets](Ticket.md), la [modification d'une fiche](Modifier_une_fiche.md), la [création d'une fiche](Creer_une_fiche.md) et sur les [demandes de fusions](demande_fusion.md) permettent d'aller plus loin dans l'utilisation de Gitlab.
\ No newline at end of file
......@@ -32,7 +32,7 @@ Dans l'interface d'édition, il est possible de modifier le nom d'une fiche, mod
- En cliquant sur `Aperçu`, une prévisualisation de la fiche peut être obtenue (certaines images peuvent ne pas s'afficher. Les blocs d'information étant des objets View Press, la prévisualisation ne pourra pas se faire.)
:::
Vous pouvez vous reporter aux fiches [inclure une image](inclure_image.md), [tutoriel Markdown](tutoriel_markdown.md) pour aller plus loin.
Vous pouvez vous reporter aux fiches [inclure une image](inclure_image.md), [tutoriel Markdown](tutoriel_markdown.md#liens-hypertextes) pour aller plus loin.
<p style="center">
<img src="../../files/images/tutoriel_gitlab/2020-04-27_HDH_modifier-fiche_MLP-2.0.png" width="1000"/>
......@@ -43,7 +43,7 @@ Un formulaire en bas de la page éditée permet d'enregistrer vos modifications
- Écrivez un message décrivant les modifications apportées: une description courte, puis éventuellement une description plus longue séparée par une ligne vide.
- Choisissez le nom d'une nouvelle branche de travail, **avec un nom explicite**. N'oubliez pas de remplacer les espaces par des tirets, sinon un message d'erreur s'affichera.
- En bas de page, la case `créer une nouvelle demande de fusion` est automatiquement cochée. Laissez cette case cochée. Cela permettra une fois une fois les modifications enregistrées dans une branche cible, de demander à incorporer les modification effectuée dans la branche cible dans la branche master. Cela permettra également de discuter et valider les modifications apportées avant de les inclures dans la documentation.
- En bas de page, la case `créer une nouvelle demande de fusion` est automatiquement cochée. Laissez cette case cochée. Cela permettra une fois une fois les modifications enregistrées dans une branche cible, de demander à incorporer les modifications effectuée dans la branche cible dans la branche master. Cela permettra également de discuter et valider les modifications apportées avant de les inclure dans la documentation.
- Cliquer sur `Commit Changes`
......@@ -55,7 +55,7 @@ Un formulaire en bas de la page éditée permet d'enregistrer vos modifications
Une page s'ouvre alors pour configurer la demande de fusion.
- Donner un titre, remplir la description
- Ajouter des assignés pour la [relecture et validation](../Guide_contribution)
- Ajouter des assignés pour la [relecture et validation](../Guide_contribution/README.md#processus-de-relecture-et-validation)
- Si le travail n’est pas fini et que des modifications seront apportées ultérieurement, cocher la case `Start the title with WIP`
- Soumettre votre merge-request en bas de page.
......@@ -64,72 +64,13 @@ Une page s'ouvre alors pour configurer la demande de fusion.
</p>
::: tip
Enregistrer une demande de fusion ne veut pas dire que la fusion se lancera automatiquement après cette demande. L'incorporation des modifications proposées dans la documentation nécessite une [validation](../Guide_contribution/README.md) de certains membres sur Health Data Hub. Des modifications peuvent toujours être apportées sur la même fiche, dans la même demande de fusion (et donc sur la même branche).
Enregistrer une demande de fusion ne veut pas dire que la fusion se lancera automatiquement après cette demande. L'incorporation des modifications proposées dans la documentation nécessite une [validation](../Guide_contribution/README.md#processus-de-relecture-et-validation) de certains membres sur Health Data Hub. Des modifications peuvent toujours être apportées sur la même fiche, dans la même demande de fusion (et donc sur la même branche).
Les demandes de fusions sont validées par [certains membres de HDH](../Guide_contribution/README.md).
Les demandes de fusions sont validées par [certains membres de HDH](../Guide_contribution/README.md#validation-et-fusion).
:::
## Naviguer dans une demande de fusion (merge-request)
Lorsqu'une demande de fusion est créée, quatre onglets sous le titre de la demande de fusion permettent d'avoir une vue d'ensemble, avoir accès à l'historique des modifications, d'effectuer des tests sur la fiche, d'apporter de nouvelles modifications et comparer deux versions.
* Onglet `Vue d'ensemble`
L'onglet vue d'ensemble permet d'avoir accès à une visualisation générale de la demande de fusion. L'interface est très proche de celle des tickets.
On y retrouve le titre, la description remplie lors de l'ouverture de demande de fusion. Il est possible de rajouter des assignés et des étiquettes dans le panneau de droite. La boite de dialogue peut être utilisée comme dans les tickets pour des discussions autour des modifications apportées.
En cliquant sur le bouton `Edit` il est possible d'éditer la demande de fusion (changer le titre, la description principale, ajouter/enlever le statut `WIP`)
Des icônes rondes (de couleur verte, orange, rouge, bleue) sont présentes. Ces icônes correspondent à des pipelines (se référer au point pipelines ci-dessous pour plus de détails) .
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-12_HDH_vue-densemble-MR_MLP-2.0.png" alt="wip" width="1000"/>
</p>
* Onglet `Commits`
En allant sur l'onglet `Commits`, l’historique des commits et donc des modifications s'affiche. On retrouve également les icônes rondes des pipelines.
* Onglet `Pipelines`
En allant sur l'onglet `Pipelines`, on retrouve les icônes rondes rencontrées dans les onglets `Vue d'ensemble`et `Commits`.
Lorsqu'une merge-request est ouverte, un "`pipeline`" est démarré pour effectuer des tests sur les liens hypertextes, la licence et construire une prévisualisation du site de la documentation. Ces 2 étapes sont symbolisées par des icônes rondes (la première icône correspond aux tests et la seconde à la prévisualisation du site de la documentation)
Les tests permettent de vérifier que les liens externes et internes sont valides. Il y a également un test permettant de vérifier que l'identifiant de la licence est bien présent. En cas d’échec, des icônes oranges apparaissent pour les tests des lien externes et de la licence et une icône rouge apparaît pour le test des liens internes.
La [fiche](erreur_pipelines.md) reprenant les erreurs courantes rencontrées peut être utilisée pour corriger de manière autonome ces erreurs si le contributeur se sent à l'aise.
Avant d’accepter une demande de fusion, ces tests sont toujours vérifiés par les mainteneurs et les corrections nécessaires sont apportées en cas d’échec.
Lorsque la prévisualisation est construite, la deuxième icône passe au vert.
Cliquer dessus, permet d'ouvrir la prévisualisation du site.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-12_HDH_pipelines_MLP-2.0.png" alt="wip" width="1000"/>
</p>
À chaque nouveau commit sur la branche, le pipeline est relancé, et la prévisualisation est mise à jour avec la même url.
* Onglet `Changes`
L'onglet `Changes` permet de comparer deux versions de la fiche, d'apporter de nouvelles modification et de suggérer des modifications.
En cliquant sur le bouton `paramètre`, il est possible de comparer les modifications par ligne ou comparer deux versions côte-à-côte. Les lignes supprimées/modifiées sont surlignées en rouge avec un symbole `-`. Les lignes ajoutées/sur lesquels des modifications ont eu lieu, sont surlignées en vert avec un symbole `+`.
Dans le menu déroulant `compare` il est possible de choisir quelles versions sont à comparer.
Le bouton Crayon `Edit File` permet d'apporter de nouvelles modifications (voir ci-dessous)
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-10_HDH_MR-comparaison_MLP-2.0.png" alt="wip" width="1000"/>
</p>
## Retrouver sa demande de fusion
Pour retrouver une demande de fusion dans lequel on s'est assigné, il faut aller dans la barre de navigation de Gitlab et cliquer sur le bouton orange `Demande de fusion`. Si on ne s'est pas assigné dans la demande de fusion, il faut aller dans l'onglet `Demande de fusion` dans la barre à gauche de l'interface Gitlab et chercher sa demande de fusion parmi la liste.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-12_HDH_retrouver-MR_MLP-2.0.png" alt="wip" width="1000"/>
</p>
Pour apprendre à naviguer dans une demande de fusion, se reporter à la fiche [dédiée](demande_fusion.md).
## Apporter des modifications supplémentaires dans la même demande de fusion
Il existe deux méthodes pour apporter des modifications supplémentaires dans la même demande de fusion.
......@@ -148,20 +89,11 @@ Pour cela aller dans la barre présente à gauche de l'interface Gitlab. Aller d
</p>
## Suggérer des modifications
Lors du [processus de relecture](../Guide_contribution/README.md), des modifications peuvent être suggérées par le relecteur.
* Soit en utilisant la boite de dialogue présente dans l'onglet `Vue d'ensemble` de la demande de fusion et en taguant la personne à qui les remarques sont adressées.
* Soit en faisant un commentaire ou une proposition de modification sur une ligne spécifique. Pour cela, aller dans l'onglet `Changes` de la demande de fusion, et passer la souris sur la ligne à commenter/modifier. Un bouton bleu contenant une bulle de conversation apparait à gauche. En le sélectionnant il est possible d'écrire un commentaire spécifique à la ligne sélectionnée. Une suggestion de modification peut être insérée à partir de la fenêtre des commentaires en cliquant sur le bouton `Insert Suggestion`. Cela fera apparaitre une suggestion de modification dans l'onglet `Vue d'ensemble` de la demande de fusion. Celle-ci pourra être acceptée ou refusée par l'auteur de la fiche.
Lors du [processus de relecture](../Guide_contribution/README.md#processus-de-relecture-et-validation), des modifications peuvent être suggérées par le relecteur.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-10_HDH_proposer-correction_MLP-2.0.png" alt="changer branche" width="1000"/>
</p>
::: tip
Pour taguer une personne il suffit de taper `@` et une liste déroulante des personnes participant au projet de la documentation apparait. En tapant le nom de la personne recherchée dans la barre de recherche on peut donc sélectionner la personne souhaitée.
:::
Se référer à la fiche [processus de relecture](processus_relecture.md) dédiée.
## Incorporation des modifications dans le projet
Lorsque le [processus de relecture](../Guide_contribution/README.md) est terminée, les modification peuvent être incorporées dans la documentation. Aller dans l'onglet `Vue d'ensemble` de la demande de fusion. Enlever l'étiquettes `Etape: en cours` si elle a été mise. Enlever le statut `WIP` en allant dans le bouton `Editer`. Ajouter l'étiquette `Etape : Prêt fusion`.
Lorsque le [processus de relecture](../Guide_contribution/README.md#processus-de-relecture-et-validation) est terminé, les modifications peuvent être incorporées dans la documentation. Aller dans l'onglet `Vue d'ensemble` de la demande de fusion. Enlever l'étiquettes `Etape: en cours` si elle a été mise. Enlever le statut `WIP` en allant dans le bouton `Editer`. Ajouter l'étiquette `Etape : Prêt fusion`.
Cela permet aux mainteneurs du projet de savoir visuellement quelles demandes de fusion sont prêtes et de pouvoir incorporer à la documentation les modifications proposées.
\ No newline at end of file
Cela permet aux mainteneurs du projet de savoir visuellement quelles demandes de fusion sont prêtes à être incorporées à la documentation.
\ No newline at end of file
......@@ -7,7 +7,7 @@ Différents outils opensource sont mis à disposition par le Health Data Hub et
Les fiches et documents sont partagés un dépôt dans [Gitlab](https://gitlab.com/healthdatahub/documentation-snds) par les contributeurs avant d'être compilés par un logiciel Open Source [Vuepress](https://vuepress.vuejs.org/) pour donner le site de la documentation.
<p style="center">
<img src="../../files/images/tutoriel_gitlab/2020-05-10_HDH_outils-documentation_MLP-2.0.png" alt="Éditer sur GitLab" width="700"/>
<img src="../../files/images/tutoriel_gitlab/2020-05-10_HDH_outils-documentation_MLP-2.0.png" alt="Éditer sur GitLab" width="600"/>
</p>
### Gitlab
......@@ -21,15 +21,19 @@ Vous retrouverez notamment:
- Comment [modifier une fiche](Modifier_une_fiche.md)
- Comment [créer une fiche](Creer_une_fiche.md)
- Comment rajouter une [image](inclure_image.md) dans une fiche
- Comment [partager un document](partage_document.md)
- Comment [partager un document](partage_document.md)`
- Comment naviguer dans une [demande de fusion](demande_fusion.md)
- Comment suggérer des modifications lors du [processus de relecture](processus_relecture.md)
- quelles sont les erreurs classiques conduisant à un échec des [pipelines](erreur_pipelines.md)
- Comment [contribuer aux tables de données synthétiques](contribution_tables.md)
- La formation Gitlab ainsi que des [exercices](exercices_formation.md) pour s'entrainer
- Des [cheat sheet](Cheat_Sheet.md) reprenant les points essentiels pour contribuer à la documentation via Gitlab
### Site de la documentation
Le site de la documentation est obtenu à partir de VuePress et de Gitlab. Une fiche récapitule les [principales fonctionnalités](Utiliser_le_site_de_documentation.md) du site.
### Forum entraide SNDS
Il est fortement recommandé de partager la publication de d'une fiche sur le [forum d'entraide du SNDS](https://entraide.health-data-hub.fr/) pour lui donner plus de visiblité. Une fiche récapitule les [principales fonctionnalités du forum](Forum.md).
Il est fortement recommandé de partager la publication de d'une fiche sur le [forum d'entraide du SNDS](https://entraide.health-data-hub.fr/) pour lui donner plus de visibilité. Une fiche récapitule les [principales fonctionnalités du forum](Forum.md).
## Comment utiliser Gitlab pour contribuer
Toute personne souhaitant contribuer est invitée à le faire. Les contributions peuvent porter sur la correction des erreurs, la mise à jour de certains champs, compléter des pages existantes, et en créer de nouvelles. Toutes améliorations, même d'apparence mineure comme la correction de fautes d'orthographe, améliorent pour tous la qualité du contenu. Un processus de relecture et de validation a été mis en place afin de garantir un contenu de qualité. Merci de s'y [référer](../../contribuer/Guide_contribution/README.md) avant toute contribution.
......@@ -38,7 +42,7 @@ Il est possible de contribuer de plusieurs manières :
- en créant un [ticket](Ticket.md) pour signaler une erreur, proposer une nouvelle idée de fiche par exemple
- en modifiant une à plusieurs fois une [fiche](Modifier_une_fiche.md)
- en créant une [nouvelle fiche](Creer_une_fiche.md)
- en partageant des [programmes](../../contribuer/Guide_contribution/partager_des_sources.md)
- en partageant des [programmes](partage_document.md)
<p style="center">
<img src="../../files/images/tutoriel_gitlab/2020-05-10_HDH_procedure-contribution_MLP-2.0.png" alt="Éditer sur GitLab" width="800"/>
......
......@@ -10,8 +10,7 @@ Ils peuvent être attribués à une ou plusieurs personnes en désignant des ass
</p>
Des étiquettes peuvent être ajoutées pour décrire les tickets. Dans le cadre de la
documentation collaborative, les étiquettes disponibles sont `Rédaction`, `Développement`, `Bug`,
`A faire`, `En cours`, `Prêt fusion
documentation collaborative, les étiquettes disponibles sont `Rédaction`, `Développement`, `Bug`,`A faire`, `En cours`, `Prêt fusion`
<p align="center">
<img src="../../files/images/tutoriel_gitlab/2020-04-27_HDH_etiquette_MLP-2.0.png" width="800px"/>
......
# Naviguer dans le site de la documentation
<!-- SPDX-License-Identifier: MPL-2.0 -->
## Généralité
### Contributeurs
Cette documentation est maintenue par le Health data hub.
Elle résulte d'une mise en commun de documents et travaux par plusieurs organisations, dont :
- la Caisse nationale d'assurance maladie - [Cnam](https://www.ameli.fr/)
- le Health Data Hub - [HDH](https://www.health-data-hub.fr)
- la Direction de la Recherche, des études, de l’évaluation et des statistiques -
[DREES](https://drees.solidarites-sante.gouv.fr/etudes-et-statistiques/la-drees/)
- les Agences régionales de santé - [ARS](https://www.ars.sante.fr/)
- Santé publique France - [SpF](https://www.santepubliquefrance.fr/)
- L'Organisation de la direction de la sécurité sociale - [DSS](https://solidarites-sante.gouv.fr/ministere/organisation/organisation-des-directions-et-services/article/organisation-de-la-direction-de-la-securite-sociale-dss)
### Licence
Ce dépôt est publié par le Health data hub sous
licence Mozilla Public License 2.0 (MPL-2.0)
## Organisation
### Sections
La documentation est organisée en 5 sections disponible dans le menu de droite :
- [Introduction](../../introduction/README.md) est un guide introductif au SNDS ;
- [Fiches thématiques](../../fiches/README.md) contient des fiches thématiques détaillées ; Les fiches sont rangées par ordre alphabétique.
- [Glossaire](../../glossaire/README.md) contient des fiches explicitant des concepts importants, utilisées comme références ailleurs ;
- [Ressources](../../ressources/README.md) liste de nombreuses ressources externes ou à télécharger ; La partie ressources contient des documents partagés par la Cnam et Santé publique France notamment.
- [Tables](../../tables/README.md) est un dictionnaire des tables et variables ;
- [Contribuer](../../contribuer/README.md) est un guide de contribution à cette documentation.
Chacune de ces sections correspond à un dossier sur [GitLab](https://gitlab.com/healthdatahub/documentation-snds), avec un [dossier supplémentaire](https://gitlab.com/healthdatahub/documentation-snds/files) pour les fichiers et images.
### Naviguer sur le site
En haut de la page de la documentation, une barre de recherche permet de retrouver des fiches en tapant un mot-clé. Des boutons `Forum entraide`, `Dico interactif`, `Groupe Meetup`, `Gitlab` permettent de se rediriger vers les sites respectifs.