mise à jour de quelques consignes

Author: linogaliana

content/git/exogit.qmd

@@ -34,11 +34,11 @@ print_badges("content/git/exogit.qmd")
 ```
 :::
 
-Les exercices suivants sont inspirés d'un cours de Git que j'ai construit
+Les exercices suivants sont inspirés d'un cours de Git que j'ai
+participé à construire
 à l'Insee et dont les ressources sont disponibles
 [ici](https://inseefrlab.github.io/formation-bonnes-pratiques-git-R/). L'idée
-du cadavre exquis, qui m'a été soufflée par
-[Romain Lesur](https://github.com/RLesur) est inspirée de
+du cadavre exquis est inspirée de
 [cette ressource](https://github.com/corent01/03-Swartz/blob/master/Parcours/01-La-prairie/git/exercice-git-cadavre-exquis.md) et de [celle-ci](https://github.com/simplonco/cadavre-request).
 
 Cette partie part du principe que les concepts généraux de `Git` sont
@@ -50,9 +50,7 @@ disponible. Un exemple de tel environnement est le `JupyterLab` ou l'environneme
 <a href="https://datalab.sspcloud.fr/launcher/ide/jupyter-python?autoLaunch=true&amp;onyxia.friendlyName=%C2%ABpython-datascience%C2%BB&amp;init.personalInit=%C2%ABhttps%3A%2F%2Fraw.githubusercontent.com%2Flinogaliana%2Fpython-datascientist%2Fmaster%2Fsspcloud%2Finit-jupyter.sh%C2%BB&amp;init.personalInitArgs=%C2%ABgit%20exogit%C2%BB&amp;security.allowlist.enabled=false" target="_blank" rel="noopener"><img src="https://img.shields.io/badge/SSPcloud-Tester%20via%20SSP--cloud-informational&amp;color=yellow?logo=Python" alt="Onyxia"></a>
 
 
-<!-- KA : Lien vers le chapitre précédent le fonctionne pas -->
-
-Outre le [chapitre précédent](#introgit), il existe de
+Outre le [chapitre précédent](/content/course/git/introgit.qmd), il existe de
 nombreuses ressources sur internet sur le sujet,
 notamment une série de ressources construites
 pour l'Insee [sur ce site](https://inseefrlab.github.io/formation-bonnes-pratiques-git-R/)
@@ -62,16 +60,16 @@ et [pratique sur RStudio](https://www.book.utilitr.org/03_fiches_thematiques/fic
 les ressources ne sont donc pas du `Python` car `Git` est un outil transversal
 qui doit servir quel que soit le langage de prédilection.
 
-de pratiques collaboratives devenues standards dans le domaine de l'_open-source_
+`Git` fait parti des pratiques collaboratives
+devenues standards dans le domaine de l'_open-source_
 mais également de plus en plus communes dans les administrations et entreprises
 de la _data science_. 
 
-Ce chapitre propose d'utiliser l' extension `Git` de `JupyterLab` ou de `VSCode`.
+Ce chapitre propose, pour simplifier l'apprentissage,
+d'utiliser l' extension `Git` de `JupyterLab` ou de `VSCode`.
 Un tutoriel présentant l'extension `JupyterLab` est disponible
 [ici](https://annefou.github.io/jupyter_publish/02-git/index.html). 
-Les principaux autres IDE disponibles (PyCharm, RStudio) présentent
-des fonctionalités similaires. Il est
-tout à fait possible d'en utiliser un autre. `VisualStudio` propose
+`VSCode` propose
 probablement, à l'heure actuelle, l'ensemble le plus complet. 
 
 Certains passages de ce TD nécessitent d'utiliser la ligne de commande.
@@ -84,13 +82,12 @@ pour les routines quotidiennes et ne les utiliser que
 pour certaines opérations où elles s'avèrent fort pratiques
 (notamment la comparaison de deux fichiers avant de devoir fusionner).
 
-
-
 # Configuration du compte Github
 
 ## Rappels sur la notion de dépôt distant
 
-Pour rappel, comme expliqué précédemment, il convient de distinguer
+Comme expliqué dans le chapitre précédent,
+il convient de distinguer
 le dépôt distant (*remote*) et la copie ou les copies locales (les *clones*)
 d'un dépôt. Le dépôt distant est généralement stocké sur une forge 
 logicielle (`Github` ou `Gitlab`) et sert à centraliser la version
@@ -111,24 +108,16 @@ d'offrir une manière robuste et efficace d'interagir avec un
 dépôt distant facilitant ainsi la collaboration en équipe ou en
 solitaire. 
 
-Pour ces exercices, je propose d'utiliser `Github` dont les fonctionalités
-nous suffiront amplement[^1]. Si, 
-dans le futur, les fonctionnalités ne vous conviennent pas (sans l'apport de fonctionnalités
-externes, `Github` propose moins de fonctionalités que `Gitlab`) ou si vous êtes
-mal à l'aise concernant le possesseur de `Github` (Microsoft), vous pourrez utiliser
-`Gitlab` <i class="fab fa-gitlab"></i>, son concurrent.
-L'avantage de `Github` par rapport à `Gitlab` est que le premier est plus visible, car
+Pour ces exercices, il est proposé
+d'utiliser `Github`, la forge la plus visible. 
+L'avantage de `Github` par rapport à son principal concurrent, `Gitlab`,
+est que le premier est plus visible, car
 mieux indexé par `Google` et concentre, en partie pour des raisons historiques, plus
 de développeurs `Python` et `R` (ce qui est important dans des domaines comme
-le code où les externalités de réseau jouent). Le débat `Github` vs `Gitlab` n'a
-plus beaucoup de sens aujourd'hui car les fonctionnalités ont convergé (`Github` 
-a rattrapé une partie de son retard sur l'intégration continue) et, de toute
-manière, on peut tout à fait connecter des dépôts `Gitlab` et `Github`. 
+le code où les externalités de réseau jouent). 
 
 
-[^1]: Dans sa version en ligne, `Github` (<https://github.com>)
-dispose de plus de visibilité que `Gitlab` (<https://gitlab.com>). 
-L'avantage que comportait `Gitlab` par rapport à `Github` 
+[^1]: L'avantage que comportait `Gitlab` par rapport à `Github` 
 à une époque, à savoir la possibilité de disposer gratuitement de ressources
 pour faire de l'intégration continue, n'existe plus depuis que `Github`
 a lancé son service `Github Actions`. Cependant, être familiarisé à 
@@ -140,18 +129,22 @@ les fonctionalités coeur de ces deux interfaces qui sont en fait quasi-identiqu
 
 ## Première étape: créer un compte `Github`
 
-Les deux premières étapes se font sur [Github](https://github.com).
+Les deux premières étapes se font sur [`Github`](https://github.com).
 
 ::: {.cell .markdown}
 ```{=html}
 <div class="alert alert-success" role="alert">
-<h3 class="alert-heading"><i class="fa-solid fa-pencil"></i> Exercice 1 : Créer un compte Github</h3>
+<h3 class="alert-heading"><i class="fa-solid fa-pencil"></i> Exercice 1 : Créer un compte <code>Github</code></h3>
 ```
 
 1. Si vous n'en avez pas déjà un, créer un compte sur <a href="https://github.com">https://github.com</a>
-2. Créer un dépôt vide. Créez ce dépôt **privé**, cela permettra
+2. Créer un dépôt en suivant les consignes ci-dessous.
+
+* Créez ce dépôt **privé**, cela permettra
 dans l'exercice 2 d'activer notre jeton. Vous pourrez le rendre public
 après l'exercice 2, c'est comme vous le souhaitez.
+* Créer ce dépôt avec un `README.md` en cliquant sur la case `Add a README file`
+* Ajouter un `.gitignore` en sélectionnant le modèle `Python`
 
 *Connexion sur <a href="https://github.com">https://github.com</a> > + (en haut de la page) > New repository > Renseigner le "Repository name" > Cocher "private" > "Create repository"*
 
@@ -177,13 +170,20 @@ il est nécessaire de s’authentifier (un dépôt distant, même public, ne peu
 
 Plus précisément, il existe deux modalités pour faire connaître son identité à `Github` :
 
-* une authentification HTTPS (décrite ici) : l’authentification se fait avec un login et un mot de passe (qu’il faut renseigner à chaque interaction avec le dépôt), ou avec un token (méthode à privilégier).
-* une authentification SSH : l’authentification se fait par une clé cryptée disponible sur le poste de travail et que GitHub ou GitLab connaît. Une fois configurée, cette méthode ne nécessite plus de faire connaître son identité : l’empreinte digitale que constitue la clé suffit à reconnaître un utilisateur.
+* une __authentification HTTPS__ (décrite ici) : l’authentification se fait avec un login et un mot de passe ou avec un _token_ (un mot de passe compliqué généré automatiquement par `Github` et connu exclusivement du détenteur du compte `Github`)  ;
+* une __authentification SSH__ : l’authentification se fait par une clé cryptée disponible sur le poste de travail et que `GitHub` ou `GitLab` connaît. Une fois configurée, cette méthode ne nécessite plus de faire connaître son identité : l’empreinte digitale que constitue la clé suffit à reconnaître un utilisateur.
 
 La [documentation collaborative `utilitR`](https://www.book.utilitr.org/03_fiches_thematiques/fiche_configurer_git.html#interaction-avec-un-d%C3%A9p%C3%B4t-distant-principe) présente les raisons pour lesquelles il convient de favoriser
 la méthode HTTPS sur la méthode SSH. 
 
-Depuis août 2021, `Github` n'autorise plus l'authentification par mot de passe
+::: {.cell .markdown}
+```{=html}
+<div class="alert alert-info" role="alert">
+<h3 class="alert-heading"><i class="fa-solid fa-comment"></i> Note</h3>
+```
+
+
+Depuis Août 2021, `Github` n'autorise plus l'authentification par mot de passe
 lorsqu'on interagit (`pull`/`push`) avec un dépôt distant
 ([raisons ici](https://github.blog/changelog/2021-08-12-git-password-authentication-is-shutting-down/)).
 Il est nécessaire d'utiliser un *token* (jeton d'accès) qui présente l'avantage
@@ -202,6 +202,12 @@ d'un dépôt).
 Pour choisir entre ces différentes options, vous pouvez vous rendre sur *Settings > Password and authentication > Enable two-factor authentication*.
 
 
+```{=html}
+</div>
+```
+:::
+
+
 ::: {.cell .markdown}
 ```{=html}
 <div class="alert alert-info" role="alert">
@@ -235,23 +241,26 @@ connu de vous seuls.
 La [documentation officielle](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) comporte un certain nombre de captures d'écran expliquant
 comment procéder.
 
-Nous allons utiliser le `credential helper` associé à Git pour stocker
+Nous allons utiliser le `credential helper` associé à `Git` pour stocker
 ce jeton. Ce `credential helper` permet de conserver de manière pérenne
 un jeton (on peut aussi faire en sorte que le mot de passe soit automatiquement
 supprimé de la mémoire de l'ordinateur au bout, par 
 exemple, d'une heure). 
+
 L'inconvénient de cette méthode est que `Git` écrit en clair le jeton dans
 un fichier de configuration. C'est pour cette raison qu'on utilise des jetons
 puisque, si ces derniers sont révélés, on peut toujours les révoquer et éviter
 les problèmes (pour ne pas stocker en clair un jeton il faudrait utiliser
 une librairie supplémentaire comme `libsecrets` qui est au-delà du programme
 de ce cours).
 
-Ma recommandation,
-si vous désirez conserver de manière plus durable ou plus sécurisée votre jeton
+Si vous désirez conserver de manière plus durable ou plus sécurisée votre jeton
 (en ne conservant pas le jeton en clair mais de manière hashée),
 est d'utiliser un gestionnaire de mot de passe comme 
-[Keepass](https://keepass.fr/) (recommandé par l'Anssi). 
+[Keepass](https://keepass.fr/) (recommandé par l'Anssi). Néanmoins,
+il est recommandé de tout de même fixer une date d'expéritation
+aux jetons pour limiter les risques de sécurité d'un _token_ qui fuite
+sans s'en rendre compte.
 
 ::: {.cell .markdown}
 ```{=html}
@@ -263,7 +272,7 @@ est d'utiliser un gestionnaire de mot de passe comme
 1️⃣ Suivre la
 [documentation officielle](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) en ne donnant que les droits `repo` au jeton (ajouter les droits
 `workflow` si vous désirez que votre jeton soit utilisable pour des projets
-où l'intégration continue est nécessaire)
+où l'intégration continue est nécessaire).
 
 Pour résumer les étapes devraient être les suivantes :
 
@@ -307,7 +316,9 @@ vous avez un message de `Git`:
 
 > warning: You appear to have cloned an empty repository.
 
-Ceci est normal, ce n'est pas une erreur. Le dossier de votre projet a bien
+Ce n'est pas une erreur mais il est préférable de suivre la
+consigne de l'exercice 1 et de créer un projet non vide.
+Le dossier de votre projet a bien
 été créé.
 
 Si vous avez une erreur, suivez la consigne présentée ci-après
@@ -351,8 +362,8 @@ A ce stade, nous avons configuré `Git` pour être en mesure
 de s'authentifier automatiquement et nous avons cloné le dépôt pour avoir une
 copie locale de travail. 
 
-On n'a encore ajouté aucun fichier à `Git`. D'ailleurs, la première 
-chose à faire est d'exclure un certain nombre de fichiers, afin de ne pas
+On n'a encore ajouté aucun fichier à `Git`. L'une des premières 
+choses à faire est d'exclure un certain nombre de fichiers, afin de ne pas
 faire une erreur pénible à réparer.