diff --git a/.gitignore b/.gitignore index d2e99add758353effc952294152ba7ec22d34909..59b72dd4236ad61e0c8bfe82dc7fc7f558408176 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ public/01_initiation/ public/02_gitlab_depot_distant/ public/03_branches/ +public/04_avance_bonnes_pratiques/ public/*.png /.quarto/ *.Rproj diff --git a/01_initiation/11_etiquetage.qmd b/01_initiation/11_etiquetage.qmd index 823099714bde7a677ea951b86a009577da517376..4b57a4700b7aaa889b310c87a89e597fcbf33151 100644 --- a/01_initiation/11_etiquetage.qmd +++ b/01_initiation/11_etiquetage.qmd @@ -153,7 +153,7 @@ Lister les étiquettes existantes : dans le menu, cliquer sur *Basculer sur…* ::: :::{.column width="40%"} -... et choisir parmi les étiquettes proposées +… et choisir parmi les étiquettes proposées {width=50%} ::: diff --git a/02_gitlab_depot_distant/09_navigation.qmd b/02_gitlab_depot_distant/09_navigation.qmd index 7b9053ae6a4ebe2ca47fc748821a5de30683b691..6067215b074026f1d7ed9dfbdb527894ac5b5f9f 100644 --- a/02_gitlab_depot_distant/09_navigation.qmd +++ b/02_gitlab_depot_distant/09_navigation.qmd @@ -1,6 +1,6 @@ # Navigation dans un projet GitLab {.inverse} -Où comment s'y retrouver au milieu de toutes ces informations... +Où comment s'y retrouver au milieu de toutes ces informations… ---- diff --git a/03_branches/scenario_branches_formateur.md b/03_branches/scenario_branches_formateur.md new file mode 100644 index 0000000000000000000000000000000000000000..2e789cb814025ce758fe3a4b940db6c598d8f712 --- /dev/null +++ b/03_branches/scenario_branches_formateur.md @@ -0,0 +1,113 @@ +# Scénario GitLab « branches » + +Pour mémoire, un document scenario_branches_utilisateurs.md doit être fourni aux apprenants. + +Il reprend les instructions à réaliser à chaque étape. + +Le présent document est destiné au formateur afin de le guider de manière efficace dans le suivi du scénario. + +Trois cas d'utilisations sont déroulés + +- use case idéal: une issue = une MR = une branche = un commit = un push = une PR +- use case rebasage: +- use case conflit: + +## Préparation formation + +### Création d'une copie du projet exercice_session3 + +- Aller à la page [du projet exercice_session3](https://forgemia.inra.fr:git-gitlab-paca/exercice_session3) +- Récupération du code (tgz) projet `git@forgemia.inra.fr:git-gitlab-paca/exercice_session3.git` et installation dans un nouveau répertoire local + +- Création d'un nouveau projet dans un autre espace de nom (au choix) + - Nouveau nom du projet : session3_labo + - Description : démo session 3, pour groupe… , date… + - Visibilité : _private_ + - Casser le lien avec le projet source (fork relationship / relation de bifurcation) via _General settings / Advanced / Fork relationship_ + +### Configuration du nouveau projet + +- Déclarer les membres en fonction des présents (Manage/Members), en rôle "developper" +- configuration à faire pour empêcher la modification de la branche "main" par les stagiaires: + - bloquer qui peut modifier la branche main (settings/Merge request,Merge commit with semi-linear history ) + - repository / protected branch et sur main, bloquer les push (no one ) + +# Use case idéal + +## (Formateur) + +- Envoyer un mail aux utilisateurs présents avec le nom du projet à cloner et le lien vers le fichier scenario_branches_utilisareur.md. +- Création et affectation des issues à chaque utilisateur (script à venir pour automatiser cette action car c'est un peu long) +- Au passage, expliquer qu'il joue le rôle de chef de projet +- Il explique les règles de MR (pas sur main) et que ce sont des conventions à définir/appliquer dès le début du projet +- On choisi le modèle une branche main stable, et des branches par issues pour faire évoluer le code. + +## (Formateur) démo de fusion et ménage + +- montre le contenu de la fusion, les changements , les commits associés +- procède à une revue de code sur les changements proposés (option) +- valide la fusion +- déclenche la fusion +- s'il a le temps, fermeture de toutes les issues, ménage dans les branches et les MR en attente + +# Use case conflit + +Nous allons volontairement créer une situation de conflit, que Git va vous demander de régler. + +Diapos ? + +Un conflit apparait lorsque deux modifications ont été faite au même endroit dans un fichier. +Git ne sait pas choisir qu'elle est la version à retenir, il va donc vous inviter à résoudre le conflit vous même. + +## (Formateur) Démo résolution de conflit + +- Prise en charge de l'issue Partie2_Chapitre2_bis (création branche à faire avant le push de la branche de l'issue précédente) +- Activation de la fusion précédente sans pull (en local, main est en retard, ainsi que la branche de l'issue) +- récupération de la nouvelle branche en local +- Correction de l'erreur dans le même fichier texte +- commit +- push +- Connexion à la forge +- Activation de la demande de fusion +- Constat de l'impossibilité à cause d'un conflit (git ne sait pas choisir laquelle des deux versions conserver) +- On peut voir les marques du conflit depuis les outils de la forge +- On peut aussi (bonne pratique) gérer ce conflit localement + +```bash +git switch Partie2_Chapitre2_bis +git fetch +git rebase origin/main +``` + +- lire les messages retournés par git !! +- ouvrir le fichier en conflit dans un éditeur +- constater les marques de conflit +- corriger (choisir le code à conserver, supprimer l'autre, supprimer les marques de conflit) + +```bash +git add . +git commit -m "Fix conflict on issue Partie2_Chapitre2_bis" +git rebase --continue +``` + +# Use case rebasage + +On veut illustrer ici la fonctionnalité de rebasage, sans conflit. + +Diapos: + +## (Formateur) Création des issues + +- Création des issues et affectation aux utilisateurs +- il s'en prévoit une pour lui, afin de faire la démo d'accompagnement + +## (Formateur) Démo rebasage + +- Constat que la troisième fusion ne peut être faite parce que le dépôt n'est plus à jour (il ne contient pas la fusion 2 par exemple) + +- résolution du problème par rebasage (on embarque dans la branche locale ) + +```bash +git checkout issue3 +git rebase origin/main +``` diff --git a/04_avance_bonnes_pratiques/.gitignore b/04_avance_bonnes_pratiques/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..5c86aa4019b6270ec5b549ffed1d0537104fd694 --- /dev/null +++ b/04_avance_bonnes_pratiques/.gitignore @@ -0,0 +1,3 @@ +*.html + +/.quarto/ diff --git a/04_avance_bonnes_pratiques/00_00_introduction.qmd b/04_avance_bonnes_pratiques/00_00_introduction.qmd new file mode 100644 index 0000000000000000000000000000000000000000..f11138629eea1120f1cac75e89d756e78c2b540b --- /dev/null +++ b/04_avance_bonnes_pratiques/00_00_introduction.qmd @@ -0,0 +1,10 @@ +# Objectifs {.inverse} + +---- + +Selon vos attendus : + +* Autres fonctionnalités de GitLab +* Fonctionnalités avancées de Git +* Bonnes pratiques de développement +* Ouverture du code diff --git a/04_avance_bonnes_pratiques/01_00_gitlab.qmd b/04_avance_bonnes_pratiques/01_00_gitlab.qmd new file mode 100644 index 0000000000000000000000000000000000000000..29f7736f6f35e5cf946225fa0299723e964bd6b9 --- /dev/null +++ b/04_avance_bonnes_pratiques/01_00_gitlab.qmd @@ -0,0 +1,13 @@ +# Autres fonctionnalités de GitLab {.inverse} + +--- + +* syntaxe Markdown +* *release* +* modèles de ticket +* organisation des projets en groupes et sous-groupes +* gestion des tickets +* étiquettes de projet +* *pipeline* +* *runner* +* intégration à Mattermost diff --git a/04_avance_bonnes_pratiques/01_01_gflm.qmd b/04_avance_bonnes_pratiques/01_01_gflm.qmd new file mode 100644 index 0000000000000000000000000000000000000000..599cc4ddca28dcc2c0ac4cc2c3081250fe30bd82 --- /dev/null +++ b/04_avance_bonnes_pratiques/01_01_gflm.qmd @@ -0,0 +1,124 @@ +# Autres fonctionnalités de GitLab − Syntaxe Markdown {.inverse} + +## Markdown ? + +Format texte pour écrire des documents structurés, mise en forme de caractères, liens, images, citations, listes… + +Utilisation pour : livres, articles, présentations (ce support de formation !), lettres, prises de notes. + +## Markdown dans GitLab + +Version enrichie de la syntaxe d’origine : *GitLab Flavored Markdown* : + +- spécification officielle de Markdown ([CommonMark](https://spec.commonmark.org/current/)) +- extensions de GitHub ([GFM](https://github.github.com/gfm/)) +- extensions spécifiques à GitLab + +## Utilisable dans… + +- tickets +- demandes de fusion +- commentaires, revues de code +- jalons +- wiki +- fichiers du dépôt (extension `.md`) + +## Markdown de base + +--- + +### Markdown de base − Titre + +```markdown +# Titre de chapitre + +## Titre de sous-chapitre +``` + +--- + +### Markdown de base − Paragraphes + +Pour créer un nouveau paragraphe, il faut simplement laisser une ligne vide entre deux portions de texte : + +```markdown +Premier paragraphe. + +Second paragraphe. +``` + +--- + +### Markdown de base − Liens + +```markdown +[ForgeMIA](https://forgemia.inra.fr/) +``` + +--- + +### Markdown de base − Styles de texte + +```markdown +_italique_ +**gras** +**_gras/italique_** +~~barré~~ +``` + +--- + +### Markdown de base − Citation + +```markdown +> Ceci est une citation. +``` + +--- + +### Markdown de base − Liste non ordonnée + +```markdown +* Un élément +* Un autre élément + * Un élément enfant + * Un deuxième élément enfant +* Encore un +``` + +--- + +### Markdown de base − Liste ordonnée + +```markdown +1. Un élément +2. Un autre élément + 1. Un élément enfant + 2. Un deuxième élément enfant +3. Encore un +``` + +--- + +### Markdown de base − Image + +```markdown + +``` + +## Extension de Markdown dans GitLab {.smaller} + +[Liste complète](https://docs.gitlab.com/ee/user/markdown.html) + +- couleur du texte +- texte barré +- emoji +- listes à cocher +- diagrammes et flux +- équations mathématiques +- tableaux, tableaux triables et filtrables +- notes de bas de page +- bloc de métadonnées (Jekill, Hugo, RMarkdown…) +- sommaire +- références GitLab +- différences de texte diff --git a/04_avance_bonnes_pratiques/01_02_release.qmd b/04_avance_bonnes_pratiques/01_02_release.qmd new file mode 100644 index 0000000000000000000000000000000000000000..27d3d5d3821479bef5c381afe9be166fc5a439ac --- /dev/null +++ b/04_avance_bonnes_pratiques/01_02_release.qmd @@ -0,0 +1 @@ +# Autres fonctionnalités de GitLab − Release {.inverse} diff --git a/04_avance_bonnes_pratiques/01_03_issue_template.qmd b/04_avance_bonnes_pratiques/01_03_issue_template.qmd new file mode 100644 index 0000000000000000000000000000000000000000..13ba29e8c65f932a9655adc74e087d2fccc34f06 --- /dev/null +++ b/04_avance_bonnes_pratiques/01_03_issue_template.qmd @@ -0,0 +1 @@ +# Autres fonctionnalités de GitLab − Modèles de ticket {.inverse} diff --git a/04_avance_bonnes_pratiques/01_04_groupe.qmd b/04_avance_bonnes_pratiques/01_04_groupe.qmd new file mode 100644 index 0000000000000000000000000000000000000000..9ad8d72ea27873dc45634fcaab24dd4c06a2b2bd --- /dev/null +++ b/04_avance_bonnes_pratiques/01_04_groupe.qmd @@ -0,0 +1 @@ +# Autres fonctionnalités de GitLab − Organisation en groupe et sous-groupe {.inverse} diff --git a/04_avance_bonnes_pratiques/01_05_planification.qmd b/04_avance_bonnes_pratiques/01_05_planification.qmd new file mode 100644 index 0000000000000000000000000000000000000000..344b05f77eb1d0453a56f4fc071679ae7cd14203 --- /dev/null +++ b/04_avance_bonnes_pratiques/01_05_planification.qmd @@ -0,0 +1,100 @@ +# Autres fonctionnalités de GitLab − Gestion des tickets {.inverse} + +--- + +- Dans un projet ou un groupe + - Liste des tickets + - Jalons + - Tableau de tickets +- Ses tickets + +## Liste des tickets + +Dans un projet ou un groupe de projets. + +*Plan* > *Issues* + +Et le raccourci pour ses propres tickets. + +## Jalons + +Dans un projet ou un groupe de projets. + +*Plan* > *Milestones* + +## Tableau de tickets + +Dans un projet ou un groupe de projets. + +*Plan* > *Issue boards* + +2 listes verticales par défaut : *Open*, *Closed* + +--- + +### Modifier le tableau de tickets + +Dans un projet ou un groupe de projets. + +- Masquer les listes *Open*, *Closed* +- Ajouter des listes pour les tickets ayant des *labels*. + +On peut réordonner ou réduire les listes. + +On peut créer un ticket directement dans une liste. + +--- + +### Créer un nouveau tableau de tickets + +Uniquement dans un projet. + +Possibilité créer d'autres tableaux. + +--- + +### Filtrer un tableau de tickets + +Pour limiter à un ou plusieurs : + +- responsable de ticket +- *label* +- auteur du ticket +- *milestone* +- *release* +- type (Incident, Ticket) + +--- + +### Exemples de tableaux de tickets + +- *Open*, label *En cours*, label *Rejeté*, *Closed* + +--- + +### Application pour un jalon + +- créer 2 *labels* : En cours, Rejeté +- ajouter un filtre sur `Milestone = %v1.0.0` + +--- + +### Application pour carnet de produit Scrum + +- créer 4 *labels* : Bac à sable, Bac à glace, Bac de culture, Bac de départ +- créer un tableau en n'affichant pas les tickets fermés, avec 4 listes pour les 4 *labels* +- ajouter un filtre sur `Milestone = None` + +=> Permet de glisser-déposer les tickets dans les bacs (plus rapide que de modifier les tickets) + +## Ses tickets + +Raccourci vers le tableau des tickets avec tous les tickets auxquels on est affectés : pour avoir l'ensemble des tâches à accomplir. + +Tri par : + +- date de dernière mise à jour +- priorité +- … + +=> La forge devient le lieu unique de sa gestion des tâches. diff --git a/04_avance_bonnes_pratiques/01_06_topic.qmd b/04_avance_bonnes_pratiques/01_06_topic.qmd new file mode 100644 index 0000000000000000000000000000000000000000..b1557586369d5074ed0519bef0c6261d675b3c6b --- /dev/null +++ b/04_avance_bonnes_pratiques/01_06_topic.qmd @@ -0,0 +1,5 @@ +# Autres fonctionnalités de GitLab − Étiquetter un projet {.inverse} + +--- + +Objectif : favoriser la recherche dans les projets diff --git a/04_avance_bonnes_pratiques/01_07_organisation_projets.qmd b/04_avance_bonnes_pratiques/01_07_organisation_projets.qmd new file mode 100644 index 0000000000000000000000000000000000000000..279b672a4cb4cee0e6dce7424922ca655b7d19ff --- /dev/null +++ b/04_avance_bonnes_pratiques/01_07_organisation_projets.qmd @@ -0,0 +1,11 @@ +# Autres fonctionnalités de GitLab − Organiser les projets {.inverse} + +--- + +TODO + +::: callout-tip +## Ressources + +- Wiki de la forge CIRAD : [Scénarios d'affiliation](https://gitlab.cirad.fr/cirad/documentation/-/wikis/Les%20sc%C3%A9narios) +::: diff --git a/04_avance_bonnes_pratiques/01_08_pipeline.qmd b/04_avance_bonnes_pratiques/01_08_pipeline.qmd new file mode 100644 index 0000000000000000000000000000000000000000..ec3ddd387ba1b8b07869f64ce9ad4ef53a94635b --- /dev/null +++ b/04_avance_bonnes_pratiques/01_08_pipeline.qmd @@ -0,0 +1,28 @@ +# Autres fonctionnalités de GitLab − *Pipeline* {.inverse} + +--- + +Successions d’étapes dans l’intégration continue ou dans le déploiement continu. + +## Intégration continue + +Ensemble de pratiques utilisées en génie logiciel consistant à vérifier à chaque modification de code source que le résultat des modifications ne produit pas de régression dans l’application développée. + +Le principal but de cette pratique est de détecter les problèmes d’intégration au plus tôt lors du développement. De plus, elle permet d’automatiser l’exécution des suites de tests et de voir l’évolution du développement du logiciel. + +--- + +Exemples : + +- exécution automatique des tests +- construction (compilation, empaquetage) de logiciels + +## Déploiement continu + +Déploiement à chaque modification de code source du résultat de la construction du projet. + +Exemples : + +- publication du logiciel empaqueté, +- mise à disposition d'une bibliothèque logicielle, +- mise en ligne d’un site web… diff --git a/04_avance_bonnes_pratiques/01_09_runner.qmd b/04_avance_bonnes_pratiques/01_09_runner.qmd new file mode 100644 index 0000000000000000000000000000000000000000..e97d8cac9520e6ff9673f5bef64eb329ecbcfae3 --- /dev/null +++ b/04_avance_bonnes_pratiques/01_09_runner.qmd @@ -0,0 +1 @@ +# Autres fonctionnalités de GitLab − Cas d'utilisation des *runners* maison {.inverse} diff --git a/04_avance_bonnes_pratiques/01_10_mattermost.qmd b/04_avance_bonnes_pratiques/01_10_mattermost.qmd new file mode 100644 index 0000000000000000000000000000000000000000..857dd4cba6965db709f4c3ee72e45a4fb597f141 --- /dev/null +++ b/04_avance_bonnes_pratiques/01_10_mattermost.qmd @@ -0,0 +1 @@ +# Autres fonctionnalités de GitLab − Intégration à Mattermost {.inverse} diff --git a/04_avance_bonnes_pratiques/02_00_git.qmd b/04_avance_bonnes_pratiques/02_00_git.qmd new file mode 100644 index 0000000000000000000000000000000000000000..0f0f3baef89e8865c9af3a0c268d495faa79b0bd --- /dev/null +++ b/04_avance_bonnes_pratiques/02_00_git.qmd @@ -0,0 +1,9 @@ +# Git : fonctionnalités particulières et astuces {.inverse} + +--- + +* crochets Git +* alias de commande +* `git cherry-pick` +* `git rebase --interactive` +* `git bisect` diff --git a/04_avance_bonnes_pratiques/02_01_hook.qmd b/04_avance_bonnes_pratiques/02_01_hook.qmd new file mode 100644 index 0000000000000000000000000000000000000000..5dfcd5a35aa25b9557b97e63ed88e3e097f0b268 --- /dev/null +++ b/04_avance_bonnes_pratiques/02_01_hook.qmd @@ -0,0 +1,5 @@ +## Crochets Git + +::: {.notes} +https://git-scm.com/book/fr/v2/Personnalisation-de-Git-Crochets-Git +::: diff --git a/04_avance_bonnes_pratiques/02_02_alias.qmd b/04_avance_bonnes_pratiques/02_02_alias.qmd new file mode 100644 index 0000000000000000000000000000000000000000..6047a33fa81f762245a9e55388a4932397f6e8b6 --- /dev/null +++ b/04_avance_bonnes_pratiques/02_02_alias.qmd @@ -0,0 +1,48 @@ +## Alias de commande + +Objet : rendre l'utilisation de Git plus simple, facile ou familier. + +--- + +### Alias de commande − exemple 1 + +Pour désindexer un fichier, on utilise la commande + +``` +git reset HEAD mon_fichier.txt +``` + +Configurer un alias avec + +``` +git config --global alias.unstage 'reset HEAD --' +``` + +permet d'utiliser la commande + +``` +git unstage mon_fichier.txt +``` + +--- + +### Alias de commande − exemple 2 + +Pour mettre en forme l'affichage de l'historique : + +``` +git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit" +``` + +`git lg` affiche alors : + +``` +* 3595b95 - Suppression de la diapo de titre sur la gestion des branches en local. (il y a 7 mois) <Jean-Baptiste Louvet> +* b680a92 - Suppression de la partie pointeurs et HEAD. (il y a 7 mois) <Jean-Baptiste Louvet> +* 5d23760 - Ajout de titres et clarification dans les principes. (il y a 7 mois) <Jean-Baptiste Louvet> +* e50c200 - Amélioration de la formulation des mauvais cas d’utilisation (il y a 7 mois) <Jean-Baptiste Louvet> +``` + +::: {.notes} +https://git-scm.com/book/fr/v2/Les-bases-de-Git-Les-alias-Git +::: diff --git a/04_avance_bonnes_pratiques/02_03_cherry-pick.qmd b/04_avance_bonnes_pratiques/02_03_cherry-pick.qmd new file mode 100644 index 0000000000000000000000000000000000000000..950da5380f59404c56769ece5d02402573e33a1f --- /dev/null +++ b/04_avance_bonnes_pratiques/02_03_cherry-pick.qmd @@ -0,0 +1,7 @@ +## `git cherry-pick` + +Appliquer les modifications introduites par certains commits (d’une autre branche) existants sur la branche. + +::: {.notes} +https://git-scm.com/docs/git-cherry-pick/fr +::: diff --git a/04_avance_bonnes_pratiques/02_04_rebase-i.qmd b/04_avance_bonnes_pratiques/02_04_rebase-i.qmd new file mode 100644 index 0000000000000000000000000000000000000000..243a3ddaa836906ba29a4ec25ef35fa11d71c02b --- /dev/null +++ b/04_avance_bonnes_pratiques/02_04_rebase-i.qmd @@ -0,0 +1,13 @@ +## `git rebase --interactive` + +Objet : intégrer les modifications d’une branche dans une autre (ou la même) + +Cas d'utilisation : + +- réécrire l'historique +- regrouper plusieurs commits (*squash*) + + +::: {.notes} +https://git-scm.com/docs/git-rebase https://git-scm.com/book/fr/v2/Les-branches-avec-Git-Rebaser-Rebasing +::: diff --git a/04_avance_bonnes_pratiques/02_05_bisect.qmd b/04_avance_bonnes_pratiques/02_05_bisect.qmd new file mode 100644 index 0000000000000000000000000000000000000000..cfa2bcac6478c45f63f7f425c121d42d3def54ab --- /dev/null +++ b/04_avance_bonnes_pratiques/02_05_bisect.qmd @@ -0,0 +1,5 @@ +## `git bisect` + +::: {.notes} +https://git-scm.com/docs/git-bisect/fr +::: diff --git a/04_avance_bonnes_pratiques/03_00_bonnes_pratiques.qmd b/04_avance_bonnes_pratiques/03_00_bonnes_pratiques.qmd new file mode 100644 index 0000000000000000000000000000000000000000..680dad8f5eff96ad92a9330f1e097f444b202ccd --- /dev/null +++ b/04_avance_bonnes_pratiques/03_00_bonnes_pratiques.qmd @@ -0,0 +1,3 @@ +# Bonnes pratiques {.inverse} + +Bon code : (répond aux besoins et est) maintenable, réutilisable et testable. diff --git a/04_avance_bonnes_pratiques/03_01_pourquoi.qmd b/04_avance_bonnes_pratiques/03_01_pourquoi.qmd new file mode 100644 index 0000000000000000000000000000000000000000..ea1ec13b6615b759cb54609b99d58350af615627 --- /dev/null +++ b/04_avance_bonnes_pratiques/03_01_pourquoi.qmd @@ -0,0 +1,31 @@ +## Pourquoi suivre les bonnes pratiques ? + +--- + +### Suivre les bonnes pratiques pour… la lisibilité + +- toujours penser aux lecteurs +- utiliser des standards de codage pour unifier les pratiques + +--- + +### Suivre les bonnes pratiques pour… la clarté + +- utiliser un code générique, mais pas au dépend de la clarté +- tirer avantages des fonctionnalités du langage et éviter les fonctionnalités ésotériques +- sophistication entraîne complexité, veiller à ce que l'utilité dépasse le coût +- ne pas dupliquer (*Don't Repeat Yourself*) +- séparer par domaines (accès aux données, traitement, affichage…) +- documenter + +::: {.notes} +Les doublons augmentent aussi le nombre de bogues à corriger, réusiner fait donc gagner du temps. +::: + +--- + +### Suivre les bonnes pratiques pour… maintenir la qualité + +- automatiser les tests +- automatiser les vérifications de code +- automatiser la construction diff --git a/04_avance_bonnes_pratiques/03_02_processus.qmd b/04_avance_bonnes_pratiques/03_02_processus.qmd new file mode 100644 index 0000000000000000000000000000000000000000..abfa37a93edb07c68a8952f0b6f16372cbbbb96f --- /dev/null +++ b/04_avance_bonnes_pratiques/03_02_processus.qmd @@ -0,0 +1 @@ +## Présentation d'un processus de développement diff --git a/04_avance_bonnes_pratiques/03_03_structuration.qmd b/04_avance_bonnes_pratiques/03_03_structuration.qmd new file mode 100644 index 0000000000000000000000000000000000000000..866b0f567ecfb412098a3e1d8a8eba0a9742c8bd --- /dev/null +++ b/04_avance_bonnes_pratiques/03_03_structuration.qmd @@ -0,0 +1,13 @@ +## Structurer son code + +--- + +### Structurer son code − Utiliser des analyseurs de code + +*linter* : outil de contrôle (et suggestions et corrections) pour la qualité de code + +- * : [SonarLint](https://www.sonarsource.com/products/sonarlint/) +- Java : [checkstyle](https://checkstyle.org/), [PMD](https://pmd.github.io/), +- Python : Flake8, isort, Black, [Ruff](https://astral.sh/ruff) +- R : [lintr](https://lintr.r-lib.org/) +- Rust : [clippy](https://doc.rust-lang.org/clippy/) diff --git a/04_avance_bonnes_pratiques/03_04_test.qmd b/04_avance_bonnes_pratiques/03_04_test.qmd new file mode 100644 index 0000000000000000000000000000000000000000..afd51f0d1c92ec744dadb2852baf02ce1a259e6f --- /dev/null +++ b/04_avance_bonnes_pratiques/03_04_test.qmd @@ -0,0 +1,39 @@ +## Tester son code + +--- + +### Pourquoi tester + +Écrire des tests pour : + +- garantir l’adéquation entre les développements et les attentes, +- pouvoir modifier sans crainte et faciliter le maintien à long terme du projet, +- fournir des exemples d’utilisation des composants. + +--- + +### Les différents types de tests (1/3) + +- Test unitaire : test de chaque composant individuellement +- Test fonctionnel : test des fonctionnalités de l’application +- Test de conformité +- Test de non-régression : menés pour détecter la réapparition de bogues déjà réparés. +- Test de dégradations des transactions, + +--- + +### Les différents types de tests (2/3) + +- Test de robustesse, d’endurance, de fiabilité : pour renforcer une application dans un domaine (ergonomie, mode dégradé, sécurité, architecture…). + - Test à données aléatoires, fuzzing, https://fr.m.wikipedia.org/wiki/Fuzzing +- Test de performance, +- Test de charge, + +--- + +### Les différents types de tests (3/3) + +- Test utilisateur : *Usability testing* + - Test de couloir : *hallway testing*, un test utilisateur avec des nouvelles personnes prises au hasard +- Test d’intégration : interaction de composants préalablement testés individuellement, +- Test d’acceptation, *Acceptance Testing*, test de recette : le logiciel répond aux exigences du client diff --git a/04_avance_bonnes_pratiques/03_05_environnement_virtuel.qmd b/04_avance_bonnes_pratiques/03_05_environnement_virtuel.qmd new file mode 100644 index 0000000000000000000000000000000000000000..dbc5a4cb5c93abdd7dd06c40ee37ab026324f9cf --- /dev/null +++ b/04_avance_bonnes_pratiques/03_05_environnement_virtuel.qmd @@ -0,0 +1 @@ +## Utiliser des environnements virtuels diff --git a/04_avance_bonnes_pratiques/03_06_dependances.qmd b/04_avance_bonnes_pratiques/03_06_dependances.qmd new file mode 100644 index 0000000000000000000000000000000000000000..d07da24bda0951841bb54ffb3494092a6cedc8ff --- /dev/null +++ b/04_avance_bonnes_pratiques/03_06_dependances.qmd @@ -0,0 +1,17 @@ +## Gérer ses dépendances dans son dépôt Git + +Utiliser les fichiers de constructions pour définir les versions des dépendances. + +--- + +Exemples de gestionnaires de projets : + +- Java : + - Maven : `pom.xml` + - Gradle : `build.gradle` +- PHP : + - Composer : `composer.json` +- Python : + - Hatch : `pyproject.toml` +- Rust : + - Cargo : `cargo.toml` diff --git a/04_avance_bonnes_pratiques/03_07_documentation.qmd b/04_avance_bonnes_pratiques/03_07_documentation.qmd new file mode 100644 index 0000000000000000000000000000000000000000..d807169a759ceba0507b3916c3276c6d5eaeaf0d --- /dev/null +++ b/04_avance_bonnes_pratiques/03_07_documentation.qmd @@ -0,0 +1,150 @@ +## Documenter + +La documentation fait partie du processus de développement. +Elle doit être considérée comme le code et les tests et écrite lorsque la connaissance est acquise. + +Une documentation utile est facilement maintenue par toute l’équipe. +Une documentation à jour est utilisable pour le développement et l’utisation du code. + +--- + +Plusieurs types de documentation + +- dans le code (commentaires) +- documentation générale, à choisir selon les besoins du projet : + exigences du système, conception, vision, portée, cas d’utilisation, schémas, diagrammes de flux, documentation utilisateur, documentation du code… +- documentation du projet + +--- + +### Documenter le code + +--- + +#### Pourquoi documenter son code ? + +* reproductibilité +* principes FAIR (*findable*, *accessible*, *interopable*, *reusable*) +* rendre réutilisable pour d’autres, notamment vous dans le futur ! + +NB : plus de temps est passé à reprendre un code qu’à l’écrire. + +--- + +#### Comment documenter son code ? + +Règles documenter un logiciel scientifique, selon [Lee et al. 2018](https://doi.org/10.1371/journal.pcbi.1006561) : + +* écrire et modifier les commentaires en même temps que le code +* ajouter un fichier README (voir plus loin) +* utiliser un gestionnaire de version aussi pour la documentation +* utiliser des outils automatiques de documentation (voir plus loin) +* écrire des messages d’erreur qui fournissent des solutions ou pointent vers la documentation + +Intégrer la génération de la documentation dans le processus d’intégration et de déploiement continus (CI/CD). + +--- + +#### Que documenter dans le code ? + +Toujours documenter les blocs de code délicats, fonctions, classes, fichiers, modules, données d’entrée d’exemple… selon les normes du langage : + +* Java : JavaDoc +* R : roxygen2 +* paquet R : vignette en RMarkdown, site web (*GitLab Pages*) + +--- + +Utiliser des noms de variables et de fonction les plus explicites. +S’il faut documenter les variables, c’est peut-être qu’il faut les renommer. Exemples : + +* `plant_metadata` au lieu de `df` +* `data_cleaned` au lieu de `df2` + +Préciser le périmètre, les entrées, les sorties, les unités. + +--- + +Exemple de documentation de code R pour *roxygen2* + +```r +#’ Add together two numbers. +#’ +#’ @param x A number. +#’ @param y A number. +#’ @return The sum of \code{x} and \code{y}. +#’ @examples +#’ add(1, 1) +#’ add(10, 1) +add <- function(x, y) { + x + y +} +``` + +- [Mastering Software Development in R − Documentation](https://bookdown.org/rdpeng/RProgDA/documentation.html) + +--- + +### Documenter son projet + +--- + +#### Décisions techniques du projet + +Arbitrages et raisons des choix techniques et architecturaux réalisés. + +Exemple de structuation : [MADR − Markdown Architectural Decision Records](https://adr.github.io/madr/) + +--- + +#### Fichier README + +Fichier texte `README` (format Markdown ou texte simple). +Point d’entrée par convention pour se renseigner sur un projet et utiliser le projet. + +Exemple de structuration : titre, description, fonctionnalités, dépendances techniques, installations, exemples d’utilisation. + +::: callout-tip +## Ressources + +- Outil en ligne pour la mise en forme : <https://readmi.xyz/> +- [Art of readme version française](https://github.com/hackergrrl/art-of-readme/blob/master/README-fr.md) +- [Software Release Practice](https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme) +::: + +--- + +#### Autres fichiers recommandés + +(extensions : aucune, `.txt` ou `.md`) + +- `AUTHORS` : liste des auteurs principaux et des contributeurs, les contributeurs peuvent être séparés dans `CONTRIBUTORS` +- `CONTRIBUTING` : guide pour contribuer au projet +- `LICENCE` : fichier texte avec la licence choisie + +::: callout-tip +## Ressource + +licences les plus fréquentes chez [SPDX](https://spdx.org/licenses/). +::: + +--- + +Mais aussi : + +- `CHANGELOG` : les changements apportés dans chaque version +- `SUPPORT` : explications pour obtenir de l’aide sur le dépôt de code +- `SECURITY`, `CODE_OF_CONDUCT`, `ACKNOWLEDGMENTS`, `CODEOWNERS`, `FUNDING` + +--- + +#### Fichiers pour le moissonnage des projets + +- [`CITATION.cff`](https://citation-file-format.github.io/) : texte de la citation pour le code, +- [`codemeta.json`](https://codemeta.github.io/) : moissonnage par *Software Heritage*, + [Formulaire en ligne](https://codemeta.github.io/codemeta-generator/), +- [`publiccode.yml`](https://docs.italia.it/italia/developers-italia/publiccodeyml-en/) ([standard](https://github.com/publiccodeyml/publiccode.yml)) : + obligatoire pour les logiciels publics en Italie, utilisé par [code.gouv.fr](https://github.com/codegouvfr/awesome-codegouvfr/blob/main/README.fr.md) (voir [GitHub](https://github.com/codegouvfr/awesome-codegouvfr-tooling)), + [Formulaire en ligne](https://publiccode-editor.etalab.studio/). + +Voir les consignes *Software Heritage* à la @sec-software-heritage. diff --git a/04_avance_bonnes_pratiques/04_00_ouverture.qmd b/04_avance_bonnes_pratiques/04_00_ouverture.qmd new file mode 100644 index 0000000000000000000000000000000000000000..29092c86802a1df4d45dc3d06cb65c4bca282391 --- /dev/null +++ b/04_avance_bonnes_pratiques/04_00_ouverture.qmd @@ -0,0 +1 @@ +# Licence et ouverture du code {.inverse} diff --git a/04_avance_bonnes_pratiques/04_01_publication.qmd b/04_avance_bonnes_pratiques/04_01_publication.qmd new file mode 100644 index 0000000000000000000000000000000000000000..ce33e48732b04faecbf36dd6cd74f68058660382 --- /dev/null +++ b/04_avance_bonnes_pratiques/04_01_publication.qmd @@ -0,0 +1 @@ +## Publier son code diff --git a/04_avance_bonnes_pratiques/04_02_choix_licence_gitlab.qmd b/04_avance_bonnes_pratiques/04_02_choix_licence_gitlab.qmd new file mode 100644 index 0000000000000000000000000000000000000000..6a43354558acbb7cae86e01bbb156c20c6ecd865 --- /dev/null +++ b/04_avance_bonnes_pratiques/04_02_choix_licence_gitlab.qmd @@ -0,0 +1,6 @@ +## Utiliser GitLab pour choisir une licence + +NB : + +- exigences État et INRAE en matière de licence +- attention aux contributions des stagiaires diff --git a/04_avance_bonnes_pratiques/04_03_software_heritage.qmd b/04_avance_bonnes_pratiques/04_03_software_heritage.qmd new file mode 100644 index 0000000000000000000000000000000000000000..5f39f0b6844318dc1fa6a41b3a75456c2e9201b2 --- /dev/null +++ b/04_avance_bonnes_pratiques/04_03_software_heritage.qmd @@ -0,0 +1,11 @@ +## Software Heritage {#sec-software-heritage} + +### Badge numérique + +Il est possible d'ajouter le badge dans le projet GitLab + +Menu _Général > Badges numériques_ : + +- Nom : `Software Heritage` +- Lien : `https://archive.softwareheritage.org/browse/origin/?origin_url=https://%{gitlab_server}/%{project_path}` +- URL de l'image : `https://archive.softwareheritage.org/badge/origin/https://%{gitlab_server}/%{project_path}` diff --git a/04_avance_bonnes_pratiques/04_04_oscar.qmd b/04_avance_bonnes_pratiques/04_04_oscar.qmd new file mode 100644 index 0000000000000000000000000000000000000000..a28b6079ae8dac6fd9f833283aa161c8bc625ec0 --- /dev/null +++ b/04_avance_bonnes_pratiques/04_04_oscar.qmd @@ -0,0 +1,9 @@ +## Module de formation Oscar + +3 modules sont disponibles : + +- Les fondamentaux de la science ouverte, +- Gestion et partage des données, +- Publication ouverte. + +OSCAR est accessible [ici](https://elearning.formation-permanente.inrae.fr/course/view.php?id=668). diff --git a/04_avance_bonnes_pratiques/05_00_plus_loin.qmd b/04_avance_bonnes_pratiques/05_00_plus_loin.qmd new file mode 100644 index 0000000000000000000000000000000000000000..0e9c424c616211811f12e513cb3df68c5b7cf0ba --- /dev/null +++ b/04_avance_bonnes_pratiques/05_00_plus_loin.qmd @@ -0,0 +1,24 @@ +# Ressources complémentaires {.inverse} + +--- + +## Ressources complémentaires − GitLab + +- [Bonnes pratiques GitLab pour l'ESR](https://coso-college-codes-sources-et-logiciels.pages.in2p3.fr/handbook/) +- [Documentation de la forge logicielle GitLab du CIRAD](https://gitlab.cirad.fr/cirad/documentation) +- « [gtdonnees-gitlab2023](https://gtdonnees-gitlab2023.sciencesconf.org/) : Gitlab, le compagnon pour votre production scientifique : logiciels, données, publications… » + - [Introduction générale aux forges logicielles. Gitlab : tour d'horizon et prise en main](https://gtdonnees-gitlab2023.gricad-pages.univ-grenoble-alpes.fr/intro-gitlab/) + - [Software Heritage, l'archive universelle à la croisée des forges](https://gtdonnees-gitlab2023.sciencesconf.org/data/pages/2023_06_29_MITI_SoftwareHeritage.pdf) + - [Principes et exemples de mise en place de l'intégration continue sur Gitlab](https://gtdonnees-gitlab2023.gricad-pages.univ-grenoble-alpes.fr/intro-gitlab/) +- [Chapître *Pipeline CI/CD*](https://docs.sk8.inrae.fr/021-pipeline.html) de la *Documentation SK8 INRAE* + +## Ressources complémentaires − Git + +- Conventions d'écriture pour les commit : [Conventional Commits](https://www.conventionalcommits.org/fr/v1.0.0/) + +## Ressources complémentaires − Bonnes pratiques + +- [UMR ISPA UMR ISPA / Formation numérique 2024 / Bonnes pratiques en développement](https://forgemia.inra.fr/umr-ispa/formation-numerique-2024/dev-best-practices/) +- [GitHub − Best practices for a collaborative software development culture](https://resources.github.com/innersource/best-practices-collaborative-software-dev/) +- Choix du nom des versions : [Semantic Versioning](https://semver.org/) +- Format des notes de version : [Keep a Changelog](https://keepachangelog.com/) diff --git a/04_avance_bonnes_pratiques/images/.keep b/04_avance_bonnes_pratiques/images/.keep new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/04_avance_bonnes_pratiques/index.qmd b/04_avance_bonnes_pratiques/index.qmd new file mode 100644 index 0000000000000000000000000000000000000000..e12afd29906f5866f7e9aaf2bc0008555e7ee05b --- /dev/null +++ b/04_avance_bonnes_pratiques/index.qmd @@ -0,0 +1,54 @@ +--- +title: "Session 4 : GitLab et Git avancés et bonnes pratiques" +format: + inrae-revealjs: + footer: "Formation Git / GitLab − Session 4 : GitLab et Git avancés et bonnes pratiques" + slide-number: true + show-slide-number: all + mouse-wheel: true + transition: none + menu: + useTextContentForMissingTitles: false + hideMissingTitles: true + fontsize: 22pt + self-contained: true +editor: visual +--- + +{{< include 00_00_introduction.qmd >}} + +{{< include 01_00_gitlab.qmd >}} +{{< include 01_01_gflm.qmd >}} +{{< include 01_02_release.qmd >}} +{{< include 01_03_issue_template.qmd >}} +{{< include 01_04_groupe.qmd >}} +{{< include 01_05_planification.qmd >}} +{{< include 01_06_topic.qmd >}} +{{< include 01_07_organisation_projets.qmd >}} +{{< include 01_08_pipeline.qmd >}} +{{< include 01_09_runner.qmd >}} +{{< include 01_10_mattermost.qmd >}} + +{{< include 02_00_git.qmd >}} +{{< include 02_01_hook.qmd >}} +{{< include 02_02_alias.qmd >}} +{{< include 02_03_cherry-pick.qmd >}} +{{< include 02_04_rebase-i.qmd >}} +{{< include 02_05_bisect.qmd >}} + +{{< include 03_00_bonnes_pratiques.qmd >}} +{{< include 03_01_pourquoi.qmd >}} +{{< include 03_02_processus.qmd >}} +{{< include 03_03_structuration.qmd >}} +{{< include 03_04_test.qmd >}} +{{< include 03_05_environnement_virtuel.qmd >}} +{{< include 03_06_dependances.qmd >}} +{{< include 03_07_documentation.qmd >}} + +{{< include 04_00_ouverture.qmd >}} +{{< include 04_01_publication.qmd >}} +{{< include 04_02_choix_licence_gitlab.qmd >}} +{{< include 04_03_software_heritage.qmd >}} +{{< include 04_04_oscar.qmd >}} + +{{< include 05_00_plus_loin.qmd >}} diff --git a/Makefile b/Makefile index 8deec96ce481584328a51bcb91bdfcab1bc3e49e..71b470850819db7e6fb38aee558684c440c89ac7 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ SHELL := /usr/bin/env bash BUILD_DIR := public -SESSIONS := 01_initiation 02_gitlab_depot_distant 03_branches +SESSIONS := 01_initiation 02_gitlab_depot_distant 03_branches 04_avance_bonnes_pratiques SESSION_DIRS := $(SESSIONS:%=$(BUILD_DIR)/%) INDEXES := $(SESSIONS:%=$(BUILD_DIR)/%/index.html) diff --git a/_quarto.yml b/_quarto.yml index 2a9d1dcba32e40636da88c5849c4cd305c011d70..43dd470b0e68108ac736b1637476c45fcb95a8b6 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -3,4 +3,5 @@ project: render: - "01_initiation/index.qmd" - "02_gitlab_depot_distant/index.qmd" - - "03_branches/index.qmd" \ No newline at end of file + - "03_branches/index.qmd" + - "04_avance_bonnes_pratiques/index.qmd" diff --git a/public/index.html b/public/index.html index d18270a4d153056d3ccdf100d3fd51c92139eb41..d12a38be12bc285b2e968650319d725eb21875c9 100644 --- a/public/index.html +++ b/public/index.html @@ -1,7 +1,8 @@ <!DOCTYPE html> -<html> +<html lang="fr"> <head> <meta charset="utf-8"> +<title>Formation Git & Gitlab</title> <style> .flex-container { display: flex; @@ -45,9 +46,10 @@ table img { <img src="images/logo_gitlab.png" alt="logo GitLab" /> <div class="flex-container"> - <div><a href="01_initiation/index.html">Session 1 : initiation Git</a></div> - <div><a href="02_gitlab_depot_distant/index.html">Session 2 : GitLab et dépôt distant</a></div> - <div><a href="03_branches/index.html">Session 3 : les branches</a></div> + <div><a href="01_initiation/">Session 1 : initiation Git</a></div> + <div><a href="02_gitlab_depot_distant/">Session 2 : GitLab et dépôt distant</a></div> + <div><a href="03_branches/">Session 3 : les branches</a></div> + <div><a href="04_avance_bonnes_pratiques/">Session 4 : GitLab et Git avancés et bonnes pratiques</a></div> </div> <div>