Commit c472dc4b authored by Lorien Benda's avatar Lorien Benda

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, [email protected], ID gitlab : @pajachiet),
- Olivier de Fresnoye (HDH, [email protected] , ID gitlab : @ofrsn),
- Tim Vlaar (HDH, [email protected], ID gitlab : @tim.vlaar),
- Salma El Oualydy (HDH, [email protected], ID gitlab : @salmael )
- Salma El Oualydy (HDH, [email protected], ID gitlab : @salmael )
- Maeva Kos (HDH, [email protected], 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`.
......@@ -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.
En bas de chaque fiche, il est indiqué la data de la dernière modification, la licence. Un bouton `Éditer` permet d'ouvrir directement la [page de modification](Modifier_une_fiche.md) sur Gitalb pour apporter des modifications. Le bouton `Proposez une modification` ouvre un [ticket](Ticket.md) sur Gitalb. Le bouton `Historique` permet d'ouvrir la liste des [commits](Introduction_Gitlab.md) soit une description des modifications apportées sur la fiche depuis sa création.
\ No newline at end of file
......@@ -5,7 +5,7 @@ La section [Tables](../../tables/README.md) de la documentation a un fonctionnem
Elle combine des **descriptions textuelles libres**, gérées comme le reste de la documentation, et des **informations structurées** issues du [schéma formel du SNDS](https://gitlab.com/healthdatahub/schema-snds).
Ce fonctionement est similaire à celui des pages wikipedia, où les informations structurées de wikidata sont gérées séparément du texte principal.
Ce fonctionnement est similaire à celui des pages wikipedia, où les informations structurées de wikidata sont gérées séparément du texte principal.
[![exemple wikidata](../../files/images/contribution_tables/exemple_wikidata.png)](https://fr.wikipedia.org/wiki/Direction_de_la_Recherche,_des_%C3%89tudes,_de_l%27%C3%89valuation_et_des_Statistiques)
......@@ -14,7 +14,7 @@ Ce fonctionement est similaire à celui des pages wikipedia, où les information
La description textuelle libre s'édite comme les autres pages de documentation, en suivant le lien `Éditer` en bas de page.
Le fichier source a 3 parties
Le fichier source a 3 parties:
1. l'en-tête, avec un lien court (permalink) et le titre ;
1. **la description textuelle à éditer**, souvent vide actuellement ;
......
# Demande de fusion
<!-- SPDX-License-Identifier: MPL-2.0 -->
Cette fiche comporte les principales fonctionnalités d'une demande de 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 liens 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>
\ No newline at end of file
# Erreurs courantes dans les pipelines
<!-- SPDX-License-Identifier: MPL-2.0 -->
En allant sur l'onglet `Pipelines` dans une demande de fusion, 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 liens externes et de la licence et une icône rouge apparaît pour le test des liens internes.
Si une icône orange ou rouge apparaît, il est possible de connaitre la source d'erreur. En cliquant sur l'icone du test, une fenêtre apparait. Les indications utiles se trouvent en bas de cette fenêtre.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-20_HDH_erreur-lien-int_MLP-2.0.png" alt="wip" width="1000"/>
</p>
Dans l'exemple ci-dessous, l'erreur est dans un lien interne, dans la fiche cmu_c.md à la ligne 7.
# Erreur lien interne
Les erreurs les plus courantes pour les liens internes sont les suivantes:
- la fiche/image du lien n'exite pas
- une erreur dans le format markdown
- `[texte](lien)` pour les liens
- `![texte](lien)`pour une image
- il y a une erreur dans le nom de la fiche/image
- deux fois `.md`
- ou aucun `.md`
- il y a une erreur dans le chemin du lien
- un `.` au lieu d'un `/`
- un seul point au lieu de deux pour remonter à la racine dans le dépôt
- une erreur dans la remontée à la racine
::: tip
Pour la remontée à la racine par exemple si dans la fiche `Formation PMSI` du sous-dossier Cnam dans le dossier ressource on souhaite ajouter une image présente dans le dossier files, la remontée se fera selon ce chemin, la fiche étant 2 niveaux en dessous de la racine :
`../../files/Cnam/2020-04-30_CNAM_Enoncés-EXERCICES-TOUS-PMSI-fev-2019_MLP-2.0.pdf`
:::
# Erreur lien externe
Les erreurs les plus courantes pour les liens externes sont:
- lien mort
- une faute de frappe
- une erreur dans le format markdown (`[texte](lien)`)
# Erreur licence
Si tous les fichiers ont une licence, un message disant que tous les fichiers ont une licence apparaît, sinon une liste des fichiers où la licence est absente s'affiche. Il suffit dans ce cas de rajouter cette ligne en seconde position de la fiche :
```
<!-- SPDX-License-Identifier: MPL-2.0 -->
```
......@@ -195,7 +195,7 @@ Exemple : `[CMU-C](../fiches/cmu_c.md)` pour [CMU-C](../../fiches/cmu_c.md)
### Ajouter un fichier en téléchargement
- Suivre le tutoriel pour [ajouter un nouveau](nouveau_fichier.md) dans le dossier `files`
- Suivre le tutoriel pour [ajouter un nouveau fichier](partage_document.md) dans le dossier `files`
- Insérer un lien relatif vers ce fichier pour permettre de le télécharger
### Ajouter une image
......@@ -219,7 +219,7 @@ TP optionnel :
## TP 9 : Créer une nouvelle fiche de glossaire
:::tip Note
Pour cet exercice, voir aussi la [page de documentation dédiée](nouvelle_page.md)
Pour cet exercice, voir aussi la [page de documentation dédiée](Creer_une_fiche.md)
:::
Ecrire une issue demandant à créer une fiche de glossaire sur une notion non abordée.
......
# Ajouter une image dans une fiche
<!-- SPDX-License-Identifier: MPL-2.0 -->
\ No newline at end of file
<!-- SPDX-License-Identifier: MPL-2.0 -->
Les images sont un type particulier de fichier. Comme pour tout fichier partagé, vérifiez en amont que vous avez les droits pour la publier.
## Image provenant d'un lien internet
Ouvrir en [édition la fiche](Modifier_une_fiche.md#ouvrir-et-éditer-le-fichier-en-mode-édition) dans laquelle vous souhaitez ajouter une image. Vous pourrez ensuite intégrer les images dans une page de documentation via un lien hypertexte précédé d'un point d'exclamation `!`.
Vous pouvez également utiliser des balises HTML pour centrer et choisir la taille de l'image.
La visualisation des fichiers pdf n'est pas supportée par le format Markdown. Il faut là aussi utiliser des balises HTML.
Pour plus d'information, se reporter au [tutoriel Markdown](tutoriel_markdown.md#liens-hypertextes).
## Image provenant d'un ordinateur en local
Si l'image provient d'un ordinateur en local, il faut d'abord l'ajouter dans le dépôt de Gitlab avant de pouvoir l'inclure dans une fiche. Lors de l'ajout de l'image dans Gitlab, une branche devra être créée. L'ajout de l'image dans la fiche devra ce faire dans la même branche que celle créée pour le versement de l'image dans Gitlab.
Si une image provient d'un document tierce, par exemple une présentation Powerpoint, il faut ajouter ce document tierce pour permettre des évolutions de l'image en repartant du fichier.
### Ajouter l'image dans Gitlab
Renommer sur votre ordinateur l'image à partager à ce format **date_auteur_nom-du-fichier_MPL-2.0.extension**
- `date` : a minima l'année, éventuellement le mois et le jour, au format AAAA-MM-JJ
- `auteur` : nom court de l'organisation détentrice des droits
- `nom-du-fichier` : remplacer les espaces par des tirets `-`
- `MPL-2.0` : identifiant de licence
- `extension` : par exemple `.csv`, `.pdf`, `.odp`.
::: warning Note
- **Supprimer les espaces** dans les noms de fichiers, car ils compliquent les liens hypertextes (l'espace doit être indiqué par le caractère `%20`).
- **Ne pas utiliser d'accents ou de caractères spéciaux**
- L'extension d'une image doit être en **minuscule**, sinon l'image n'est pas reconnue.
:::
Aller dans `Dépôt` > `Fichier` puis dans le dossier [files de Gitlab](https://gitlab.com/healthdatahub/documentation-snds/tree/master/files)). Vous pouvez soit ajouter les images dans le dossier de votre institut, soit dans le dossier générique `images`. Ouvrir le dossier où ajouter l'image.
Cliquer sur le bouton `+` et choisir `téléverser un fichier`.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-15_HDH_ajout-fichier_MLP-2.0.png" alt="wip" width="1000"/>
</p>
Ajouter l'image à téléverser, remplir une description de commit explicite, donner un nom de branche explicite (ne pas oublier de remplacer les espaces par des tirets). Laisser la case `Créer une nouvelle demande de fusion avec ces changements` cochée, puis cliquer sur `Téléverser un fichier`.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-15_HDH_televerser-fichier_MLP-2.0.png" alt="wip" width="1000"/>
</p>
### Insérer l'image dans la fiche
Pour insérer une image dans une fiche, il faut que l'insertion dans la fiche se fasse dans la même branche que celle créée pour le versement de l'image dans Gitlab.
Aller dans la [demande de fusion](demande_fusion.md) créée lors de l'ajout de l'image dans Gitlab. Aller dans l'onglet `Changes`, et copier le chemin de l'image. Si cela est nécessaire, vous pouvez vous remémorer le nom de la branche dans l'onglet `Vue d'ensemble`.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-15_HDH_chemin_MLP-2.0.png" alt="wip" width="1000"/>
</p>
Pour trouver la fiche à modifier, aller dans `Dépôt` > `Fichiers` et sélectionner la branche de travail précédemment utilisée.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-15_HDH_image-branche_MLP-2.0.png" alt="wip" width="1000"/>
</p>
Allez dans le dossier qui contient la fiche où l'image doit être incluse et ouvrir la fiche en mode édition.
<p style="text-align:center;">
<img src="../../files/images/tutoriel_gitlab/2020-05-15_HDH_modifier-fichier-branche_MLP-2.0.png" alt="wip" width="1000"/>
</p>
Vous pouvez ensuite intégrer l'image dans la page de documentation soit
- via un lien hypertexte précédé d'un point d'exclamation `!` (cf [tutoriel Markdown](tutoriel_markdown.md#inclure-une-image))
- via des balises HTLM (cf [tutoriel Markdown](tutoriel_markdown.md#inclure-une-image))
Il faudra ensuite remplir un commit. Le nom de la branche ne doit pas être modifié. Le commit apparaitra automatiquement dans la demande de fusion créée lors du versement de l'image.
Vous pouvez ensuite continuer à apporter des modifications sur la même branche, ajouter de nouvelles images sur la même branche puis faire valider votre contribution par le [processus de relecture/validation](../Guide_contribution/README.md#processus-de-relecture-et-validation).
\ No newline at end of file
# Ajouter des fichiers
<!-- SPDX-License-Identifier: MPL-2.0 -->
## Téléverser un fichier
Des documents de tout format peuvent être partagés dans la documentation collaborative.
Ils seront mis à disposition via un lien de téléchargement.
Pour ajouter un nouveau fichier, merci de bien vouloir :
- Vérifier que vous avez les droits pour le publier
- Le renommer en local au format **date_auteur_nom-du-fichier_MPL-2.0.extension**
- `date` : a minima l'année, éventuellement le mois et le jour, au format AAAA-MM-JJ
- `auteur` : nom court de l'organisation détentrice des droits
- `nom-du-fichier` : remplacer les espaces par des tirets `-`
- `MPL-2.0` : identifiant de licence
- `extension` : par exemple `.csv`, `.pdf`, `.odp`.
::: warning Note
- **Supprimer les espaces** dans les noms de fichiers, car ils compliquent les liens hypertextes (l'espace doit être indiqué par le caractère `%20`).
- **Ne pas utiliser d'accents ou de caractères spéciaux**
:::
- Ouvrir le dossier où ajouter le fichier
- dossier `files/` ([lien gitlab](https://gitlab.com/healthdatahub/documentation-snds/tree/master/files/)),
- sous-dossier au nom de votre organisation
- Téléverser le fichier
- Bouton `+` > `Upload file`
- Remplir une description de commit explicite
- Donner un nom de branche explicite, par exemple `upload-NOM-FICHIER`
- Ouvrez une merge-request à partir de cette branche
- Ajouter un lien de téléchargement sur une page
- Se placer sur la même branche
- Trouver le fichier où vous souhaitez mettre le lien
- sans doute une page de votre organisation dans la partie [Ressources](../../ressources/README.md)
- Mentionner le nom de l'organisation et la licence MPL-2.0.
## Nouvelle image
Les images sont un type particulier de fichier, à ajouter comme expliqué ci-dessus.
Les images peuvent être ajoutées dans le dossier `files` ([lien gitlab](https://gitlab.com/healthdatahub/documentation-snds/tree/master/files)), ou dans le dossier générique `images`.
Vous pouvez ensuite intégrer les images dans une page de documentation via un lien hypertexte précédé d'un point d'exclamation `!`
(cf [tutoriel Markdown](tutoriel_markdown.md#liens-hypertextes)).
Si une image provient d'un document tierce, par exemple une présentation Powerpoint :
- Ajouter ce document tierce pour permettre des évolutions de l'image en repartant du fichier
- Mettre l'image dans le même dossier, ou dans un sous-dossier du même nom s'il y a plusieurs images
::: warning Attention
L'extension d'une image doit être en **minuscule**, sinon [l'image n'est pas reconnue](https://github.com/vuejs/vuepress/issues/625#issuecomment-401614539).
Utiliser `.png` ou `.jpg`, **pas** `.PNG` ou `.JPG`.
:::
\ No newline at end of file
# Créer une nouvelle page du site ou un nouveau dossier
<!-- SPDX-License-Identifier: MPL-2.0 -->
## Créer une nouvelle page
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`.