diff --git a/.Rprofile b/.Rprofile index e9da59b2b..ace310ab3 100644 --- a/.Rprofile +++ b/.Rprofile @@ -8,7 +8,7 @@ options(blogdown.new_bundle = TRUE) reminder_jupyter <- function(file = "./content/getting-started/06_rappels_classes.Rmd", out = "ipynb"){ - + sprintf( "jupytext --to %s %s", out, @@ -64,3 +64,31 @@ reminder_badges <- function(notebook = ""){ } + + + +reminder_box <- function(boxtype = "warning", type = c("html","markdown")){ + type <- match.arg(type) + icon <- switch(boxtype, + warning = "fa fa-exclamation-triangle", + hint = "fa fa-lightbulb", + tip = "fa fa-lightbulb", + note = "fa fa-comment", + exercise = "fas fa-pencil-alt") + box <- c( + sprintf( + '{{< panel status="%s" title="%s" icon="%s" >}}', + boxtype, + Hmisc::capitalize(boxtype), + icon + ), + "Example", + "{{< /panel >}}" + ) + if (type == "html") cat(box, sep = "\n") + + box <- gsub("<","%", box) + box <- gsub(">","%", box) + + cat(box, sep = "\n") +} diff --git a/config.toml b/config.toml index 2b148de6a..88d5593a8 100644 --- a/config.toml +++ b/config.toml @@ -36,26 +36,32 @@ unsafe= true name = "Visualiser des données" url = "/visualisation" weight = 3 + + [[menu.main]] + name = "Git" + url = "/git" + weight = 4 + [[menu.main]] name = "Evaluation" url = "/evaluation" - weight = 4 + weight = 5 [[menu.main]] name = "Travaux dirigés" url = "/listeTP" - weight = 5 + weight = 6 [[menu.main]] name = "References" url = "/references" - weight = 6 + weight = 7 [[menu.main]] name = "Github" url = "https://github.com/linogaliana/python-datascientist" - weight = 7 + weight = 8 [params] # Source Code repository section diff --git a/content/git/_index.md b/content/git/_index.md new file mode 100644 index 000000000..5d8c1397b --- /dev/null +++ b/content/git/_index.md @@ -0,0 +1,12 @@ +--- +title: "Git: un élément essentiel au quotidien" +date: 2020-07-16T13:00:00Z +draft: false +weight: 80 +slug: git +--- + +Cette partie du site présente un élément qui n'est pas propre à +`Python` mais qui est néanmoins indispensable: la pratique de `Git` + +TO DO \ No newline at end of file diff --git a/content/git/exogit/_index.Rmd b/content/git/exogit/_index.Rmd new file mode 100644 index 000000000..e6a9bbd82 --- /dev/null +++ b/content/git/exogit/_index.Rmd @@ -0,0 +1,236 @@ +--- +title: "Un cadavre exquis pour découvrir Git" +date: 2020-09-30T13:00:00Z +draft: false +weight: 20 +output: + html_document: + keep_md: true + self_contained: true +slug: exogit +--- + + + +## Git tout seul + +### Première étape: avoir un compte `Github` + +Les deux premières étapes se font sur `Github` + +{{% panel status="exercise" title="Exercise 1: créer un compte Github" icon="fab fa-github" %}} + +1. Si vous n'en avez pas déjà un, créer un compte sur `github.com` +2. Créer un dépôt vide. Ce dépôt sera personnel, vous pouvez le rendre public +ou non, comme vous le souhaitez. +{{% /panel %}} + +Pour ces exercices, je propose d'utiliser `Github` dont les fonctionalités +nous suffiront amplement. Si, +dans le futur, les fonctionalités ne vous conviennent pas (sans l'apport de fonctionalités +externes, `Github` propose moins de fonctionalités que `Gitlab`) ou vous êtes +mal à l'aise avec le possesseur de `Github` (Microsoft), vous pourrez utiliser +`Gitlab` , le concurrent. +L'avantage de `Github` par rapport à `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 fonctionalité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 (c'est le cas +du dépôt source et de ce cours). + +### Pratique en local + +Maintenant, en local. Il faut ouvrir une invite de commande `git bash` (ou une +interface graphique connectée à `git bash`) + +{{% panel status="exercise" title="Exercise 2: découvrir l'invite de commande" icon="fas fa-pencil-alt" %}} + +1. Sur les postes ENSAE. Aller dans `Scientific Apps/Git`. Vous devriez voir +un raccourci `bash.exe`. Vous pouvez lancer l'application ; elle ouvre une +invite de commande +2. Créer un dossier de travail, par exemple `Desktop/gitexo`. Dans `git bash`, +faire + +~~~shell +# remplacer par le dossier qui vous intéresse +cd 'Desktop/gitexo' +~~~ + +3. Initialiser le contrôle de version en tapant dans l'invite de commande + +~~~shell +git init +~~~ + +{{% /panel %}} + +Pour le moment, on a uniquement initialisé le contrôle de version avec `Git`. +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 +faire une erreur pénible à réparer. + +{{% panel status="exercise" title="Exercise 3: le fichier .gitignore" icon="fas fa-pencil-alt" %}} + +Lorsqu'on utilise `Git`, il y a des fichiers qu'on ne veut pas partager +ou dont on ne veut pas suivre les modifications. C'est le fichier `.gitignore` +qui gère les fichiers exclus du contrôle de version. + +1. Maintenant, créer un fichier nommé `.gitignore` (:warning: ne pas changer +ce nom) via le bloc note ou votre IDE. +1. Aller sur le site . Vous pouvez +dans la barre de recherche taper `Python`, `Pycharm`, `JupyterNotebooks`. +Copier-coller dans votre `.gitignore` le contenu de la page. +1. Quand on crée de la documentation, on veut exclure les extensions `.pdf` +et `.html` qui sont des résultats à partager et non des fichiers source à +suivre. Pour cela, ajouter au début du fichier `.gitignore`, les extensions: + +~~~markdown +.pdf +.html +~~~ + + +{{% /panel %}} + + +On a créé un fichier `.gitignore` mais on n'a encore rien fait jusqu'à présent. +Il faut dire à `Git` de contrôler les évolutions de chaque fichier +(passage dans l'index). On appelle cette étape `git add`. **** + +{{% panel status="exercise" title="Exercise 4: pratique de git. Enfin..." icon="fas fa-pencil-alt" %}} + +1. De temps en temps, il est bon de vérifier l'état d'un dépôt. Pour cela, faire + +~~~shell +git status +~~~ + +1. Dans l'invite de commande, taper + +~~~shell +git add .gitignore +~~~ + +2. Retaper `git status`. Observer le changement. Les nouvelles modifications (en +l'occurrence la création du fichier et la validation de son contenu actuel) +ne sont pas encore archivées. Pour cela, il faut faire + +~~~shell +git commit -m "Initial commit" +~~~ + +{{% /panel %}} + +L'option `m` permet de créer un message, qui sera disponible à l'ensemble +des contributeurs du projet. Avec la ligne de commande, ce n'est pas toujours +très pratique. Les interfaces graphiques permettent des messages plus +développés (la bonne pratique veut qu'on écrive un message de commit comme un +mail succinct: un titre et un peu d'explications, si besoin). + +Le fait de nommer le premier commit *"Initial commit"* est une +habitude, vous +n'êtes pas obligé de suivre cette convention si elle ne vous plaît pas. + +### Premières interactions avec `Github` + + +{{% panel status="exercise" title="Exercise 5: interagir avec Github" icon="fas fa-pencil-alt" %}} + +1. Maintenant, créer un fichier nommé `README.md` (:warning: ne pas changer +ce nom) via le bloc note ou votre IDE. +2. Y écrire une phrase au format, sujet-verbe-complément mais sans majuscule ni ponctuation. +Observer le statut du fichier avec `git status`. +3. Valider cette création avec le message *"j'écris comme un surréaliste* + +Il convient maintenant d'envoyer les fichiers sur le dépôt distant. +1. Récupérer l'url du dépôt. Dans `Github`, il faut cliquer sur +le bouton `Code`, comme ci-dessous + +![](gitclone.png) + +2. Créer la connexion avec le dépôt distant (`remote`), qu'on va nommer `origin`, +en utilisant la commande suivante: + +~~~~shell +git remote add origin **** +~~~~ +Remplacer les astérisques par l'url du dépôt. + +3. Envoyez vos modifications vers `origin` en tapant + +~~~~shell +git push origin master +~~~~ + +`Git` va vous demander vos identifiants de connexion pour vérifier que vous +êtes bien autorisés à intéragir avec ce dépôt. Il faut les taper (:warning: +comme le créateur de `Git` était un peu paranoiaque, c'est normal +de ne pas voir le curseur avancer quand on tape des caractères pour le mot de passe, +si quelqu'un regarde votre écran il ne pourra ainsi pas savoir combien de +caractères comporte votre mot de passe) + + +{{% /panel %}} + + +Retournez voir le dépôt sur `Github`, vous devriez maintenant voir le fichier +`.gitignore` et le `README` devrait s'afficher en page d'accueil. + +{{% panel status="exercise" title="Exercise 6: rapatrier des modifs en local" icon="fas fa-pencil-alt" %}} + +Pour le moment, vous êtes tout seul sur le dépôt. Il n'y a donc pas de +partenaire pour modifier un fichier dans le dépôt distant. Nous verrons cela +lors de l'exercice suivant. Néanmoins, nous allons + +1. Modifier le `README` par l'interface de `Github` en cliquant +sur le crayon en haut à droite de l'affichage du `README`. +L'objectif est de lui +donner un titre suivant, en ajoutant, au début du document, la ligne suivante : + +~~~text +# Mon oeuvre d'art surréaliste +~~~ + +Ajouter à ce titre le mot `:penc il2:`, ce qui +affichera :pencil2: dans `Github`. +Rédiger un titre et un message complémentaire pour faire le `commit`. Conserver +l'option par défaut `Commit directly to the master branch` + +3. Editer à nouveau le `README`. Ajouter une deuxième phrase et corrigez la +ponctuation de la première. Ecrire un message de commit et valider. + +4. Au dessus de l'aborescence des fichiers, vous devriez voir s'afficher le +titre du dernier commit. Vous pouvez cliquer dessus pour voir la modification +que vous avez faite. + +5. Les résultats sont sur le dépôt distant mais ne sont pas sur votre ordinateur +Pour les rapatrier en local, faire + +~~~shell +git pull origin master +~~~ + + +{{% /panel %}} + + +{{% panel status="hint" title="Hint" icon="fa fa-lightbulb" %}} +`:XXXXXX:` permet, dans des systèmes qui reposent sur `Markdown`, d'afficher +des emojis. Vous pouvez [trouver une liste ici](https://gist.github.com/rxaviers/7360908) +{{% /panel %}} + +L'opération `pull` permet: + +1. A votre système local de vérifier les modifications sur le dépôt distant +que vous n'auriez pas faites +2. De les fusionner s'il n'y a pas de conflit de version ou si les conflits de +version sont automatiquement fusionnable (deux modifications d'un fichier mais +qui ne portent pas sur le même emplacement) + +## Cadavre exquis: découvrir le travail collaboratif + diff --git a/content/git/exogit/_index.md b/content/git/exogit/_index.md new file mode 100644 index 000000000..e6a9bbd82 --- /dev/null +++ b/content/git/exogit/_index.md @@ -0,0 +1,236 @@ +--- +title: "Un cadavre exquis pour découvrir Git" +date: 2020-09-30T13:00:00Z +draft: false +weight: 20 +output: + html_document: + keep_md: true + self_contained: true +slug: exogit +--- + + + +## Git tout seul + +### Première étape: avoir un compte `Github` + +Les deux premières étapes se font sur `Github` + +{{% panel status="exercise" title="Exercise 1: créer un compte Github" icon="fab fa-github" %}} + +1. Si vous n'en avez pas déjà un, créer un compte sur `github.com` +2. Créer un dépôt vide. Ce dépôt sera personnel, vous pouvez le rendre public +ou non, comme vous le souhaitez. +{{% /panel %}} + +Pour ces exercices, je propose d'utiliser `Github` dont les fonctionalités +nous suffiront amplement. Si, +dans le futur, les fonctionalités ne vous conviennent pas (sans l'apport de fonctionalités +externes, `Github` propose moins de fonctionalités que `Gitlab`) ou vous êtes +mal à l'aise avec le possesseur de `Github` (Microsoft), vous pourrez utiliser +`Gitlab` , le concurrent. +L'avantage de `Github` par rapport à `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 fonctionalité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 (c'est le cas +du dépôt source et de ce cours). + +### Pratique en local + +Maintenant, en local. Il faut ouvrir une invite de commande `git bash` (ou une +interface graphique connectée à `git bash`) + +{{% panel status="exercise" title="Exercise 2: découvrir l'invite de commande" icon="fas fa-pencil-alt" %}} + +1. Sur les postes ENSAE. Aller dans `Scientific Apps/Git`. Vous devriez voir +un raccourci `bash.exe`. Vous pouvez lancer l'application ; elle ouvre une +invite de commande +2. Créer un dossier de travail, par exemple `Desktop/gitexo`. Dans `git bash`, +faire + +~~~shell +# remplacer par le dossier qui vous intéresse +cd 'Desktop/gitexo' +~~~ + +3. Initialiser le contrôle de version en tapant dans l'invite de commande + +~~~shell +git init +~~~ + +{{% /panel %}} + +Pour le moment, on a uniquement initialisé le contrôle de version avec `Git`. +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 +faire une erreur pénible à réparer. + +{{% panel status="exercise" title="Exercise 3: le fichier .gitignore" icon="fas fa-pencil-alt" %}} + +Lorsqu'on utilise `Git`, il y a des fichiers qu'on ne veut pas partager +ou dont on ne veut pas suivre les modifications. C'est le fichier `.gitignore` +qui gère les fichiers exclus du contrôle de version. + +1. Maintenant, créer un fichier nommé `.gitignore` (:warning: ne pas changer +ce nom) via le bloc note ou votre IDE. +1. Aller sur le site . Vous pouvez +dans la barre de recherche taper `Python`, `Pycharm`, `JupyterNotebooks`. +Copier-coller dans votre `.gitignore` le contenu de la page. +1. Quand on crée de la documentation, on veut exclure les extensions `.pdf` +et `.html` qui sont des résultats à partager et non des fichiers source à +suivre. Pour cela, ajouter au début du fichier `.gitignore`, les extensions: + +~~~markdown +.pdf +.html +~~~ + + +{{% /panel %}} + + +On a créé un fichier `.gitignore` mais on n'a encore rien fait jusqu'à présent. +Il faut dire à `Git` de contrôler les évolutions de chaque fichier +(passage dans l'index). On appelle cette étape `git add`. **** + +{{% panel status="exercise" title="Exercise 4: pratique de git. Enfin..." icon="fas fa-pencil-alt" %}} + +1. De temps en temps, il est bon de vérifier l'état d'un dépôt. Pour cela, faire + +~~~shell +git status +~~~ + +1. Dans l'invite de commande, taper + +~~~shell +git add .gitignore +~~~ + +2. Retaper `git status`. Observer le changement. Les nouvelles modifications (en +l'occurrence la création du fichier et la validation de son contenu actuel) +ne sont pas encore archivées. Pour cela, il faut faire + +~~~shell +git commit -m "Initial commit" +~~~ + +{{% /panel %}} + +L'option `m` permet de créer un message, qui sera disponible à l'ensemble +des contributeurs du projet. Avec la ligne de commande, ce n'est pas toujours +très pratique. Les interfaces graphiques permettent des messages plus +développés (la bonne pratique veut qu'on écrive un message de commit comme un +mail succinct: un titre et un peu d'explications, si besoin). + +Le fait de nommer le premier commit *"Initial commit"* est une +habitude, vous +n'êtes pas obligé de suivre cette convention si elle ne vous plaît pas. + +### Premières interactions avec `Github` + + +{{% panel status="exercise" title="Exercise 5: interagir avec Github" icon="fas fa-pencil-alt" %}} + +1. Maintenant, créer un fichier nommé `README.md` (:warning: ne pas changer +ce nom) via le bloc note ou votre IDE. +2. Y écrire une phrase au format, sujet-verbe-complément mais sans majuscule ni ponctuation. +Observer le statut du fichier avec `git status`. +3. Valider cette création avec le message *"j'écris comme un surréaliste* + +Il convient maintenant d'envoyer les fichiers sur le dépôt distant. +1. Récupérer l'url du dépôt. Dans `Github`, il faut cliquer sur +le bouton `Code`, comme ci-dessous + +![](gitclone.png) + +2. Créer la connexion avec le dépôt distant (`remote`), qu'on va nommer `origin`, +en utilisant la commande suivante: + +~~~~shell +git remote add origin **** +~~~~ +Remplacer les astérisques par l'url du dépôt. + +3. Envoyez vos modifications vers `origin` en tapant + +~~~~shell +git push origin master +~~~~ + +`Git` va vous demander vos identifiants de connexion pour vérifier que vous +êtes bien autorisés à intéragir avec ce dépôt. Il faut les taper (:warning: +comme le créateur de `Git` était un peu paranoiaque, c'est normal +de ne pas voir le curseur avancer quand on tape des caractères pour le mot de passe, +si quelqu'un regarde votre écran il ne pourra ainsi pas savoir combien de +caractères comporte votre mot de passe) + + +{{% /panel %}} + + +Retournez voir le dépôt sur `Github`, vous devriez maintenant voir le fichier +`.gitignore` et le `README` devrait s'afficher en page d'accueil. + +{{% panel status="exercise" title="Exercise 6: rapatrier des modifs en local" icon="fas fa-pencil-alt" %}} + +Pour le moment, vous êtes tout seul sur le dépôt. Il n'y a donc pas de +partenaire pour modifier un fichier dans le dépôt distant. Nous verrons cela +lors de l'exercice suivant. Néanmoins, nous allons + +1. Modifier le `README` par l'interface de `Github` en cliquant +sur le crayon en haut à droite de l'affichage du `README`. +L'objectif est de lui +donner un titre suivant, en ajoutant, au début du document, la ligne suivante : + +~~~text +# Mon oeuvre d'art surréaliste +~~~ + +Ajouter à ce titre le mot `:penc il2:`, ce qui +affichera :pencil2: dans `Github`. +Rédiger un titre et un message complémentaire pour faire le `commit`. Conserver +l'option par défaut `Commit directly to the master branch` + +3. Editer à nouveau le `README`. Ajouter une deuxième phrase et corrigez la +ponctuation de la première. Ecrire un message de commit et valider. + +4. Au dessus de l'aborescence des fichiers, vous devriez voir s'afficher le +titre du dernier commit. Vous pouvez cliquer dessus pour voir la modification +que vous avez faite. + +5. Les résultats sont sur le dépôt distant mais ne sont pas sur votre ordinateur +Pour les rapatrier en local, faire + +~~~shell +git pull origin master +~~~ + + +{{% /panel %}} + + +{{% panel status="hint" title="Hint" icon="fa fa-lightbulb" %}} +`:XXXXXX:` permet, dans des systèmes qui reposent sur `Markdown`, d'afficher +des emojis. Vous pouvez [trouver une liste ici](https://gist.github.com/rxaviers/7360908) +{{% /panel %}} + +L'opération `pull` permet: + +1. A votre système local de vérifier les modifications sur le dépôt distant +que vous n'auriez pas faites +2. De les fusionner s'il n'y a pas de conflit de version ou si les conflits de +version sont automatiquement fusionnable (deux modifications d'un fichier mais +qui ne portent pas sur le même emplacement) + +## Cadavre exquis: découvrir le travail collaboratif + diff --git a/content/git/introgit/_index.Rmd b/content/git/introgit/_index.Rmd new file mode 100644 index 000000000..609a298a8 --- /dev/null +++ b/content/git/introgit/_index.Rmd @@ -0,0 +1,130 @@ +--- +title: "Git: un élément essentiel au quotidien" +date: 2020-09-30T13:00:00Z +draft: false +weight: 10 +output: + html_document: + keep_md: true + self_contained: true +slug: introgit +--- + +Une grande partie du contenu de ce chapitre provient du cours +[Travail collaboratif avec `R`](https://linogaliana.gitlab.io/collaboratif/git.html). + +## Pourquoi faire du `Git` ? + +Tous les statisticiens se sont déjà demandé (ou à leurs collègues) : + +* quelle était la bonne version d'un programme +* qui était l'auteur d'un bout de code en particulier +* si un changement était important ou juste un essai +* comment fusionner des programmes +* etc. + +Il existe un outil informatique puissant afin de répondre à tous ces besoins : la gestion de version (*version control system* (VCS) en anglais). Ses avantages sont incontestables et permettent de facilement : + +* enregistrer l'historique des modifications d'un ensemble de fichiers +* revenir à des versions précédentes d'un ou plusieurs fichiers +* rechercher les modifications qui ont pu créer des erreurs +* partager ses modifications et récupérer celles des autres +* proposer des modifications, les discuter, sans pour autant modifier la dernière version existante +* identifier les auteurs et la date des modifications + +En outre, ces outils fonctionnent avec tous les langages informatiques (texte, R, Python, SAS, $\LaTeX$, Java, etc.) car reposent sur la comparaison des lignes et des caractères des programmes. + + +On peut ainsi résumé les principaux avantages du contrôle de version +de la manière suivante : + +1. Conserver et archiver l'ensemble des versions d'un code ou d'une documentation +2. Travailler efficacement en équipe +3. Améliorer la qualité des codes +4. Simplifier la communication autour d'un projet + + +### Conserver et archiver du code + +Une des principales fonctionnalités de la gestion de version est conserver l'ensemble des fichiers de façon sécurisée et de proposer un archivage structuré des codes. Les fichiers sont stockés dans un **dépôt**, qui constitue le projet + +Tout repose dans la gestion et la présentation de l'historique des modifications. Chaque modification (ajout, suppression ou changement) sur un ou plusieurs fichiers est identifiée par son auteur, sa date et un bref descriptif^[Plus précisément, chaque modification est identifiée de manière unique par un code `SHA` auquel est associé l'auteur, l'horodatage et des méta-données (par exemple le message descriptif associé)]. Chaque changement est donc unique et aisément identifiable quand ils sont classés par ordre chronologique. Les modifications transmises au dépôt sont appelées **commit**. + +Avec des outils graphiques, on peut vérifier l' +[ensemble des évolutions d'un fichier (`history`)](https://github.com/linogaliana/python-datascientist/commits/master/README.md), +ou [l'histoire d'un dépôt](https://github.com/linogaliana/python-datascientist/commits/master). +On peut aussi +[se concentrer sur une modification particulière d'un fichier](https://github.com/linogaliana/python-datascientist/commit/7e5d30ae0e260f9485453b42f195b0181a53e32e#diff-04c6e90faac2675aa89e2176d2eec7d8) ou vérifier, pour un fichier, la +[modification qui a entraîné l'apparition de telle ou telle ligne (`blame`)](https://github.com/linogaliana/python-datascientist/blame/master/README.md) + +Sur son poste de travail, les dizaines (centaines ?) de programmes organisés à la main n'existent plus. Tout est regroupé dans un seul dossier, rassemblant les éléments du dépôt. Au sein du dépôt, tout l'historique est stocké et accessible rapidement. Si on souhaite travailler sur la dernière version des programmes (ou sur une ancienne version spécifique), il n'y a plus besoin de conserver les autres fichiers car ils sont dans l'historique du projet. Il est alors possible de choisir sur quelle version on veut travailler (la dernière commune à tout le monde, la sienne en train d'être développée, celle de l'année dernière, etc.). + + +### Travailler efficacement en équipe + +Le deuxième avantage de la gestion de version représente une amélioration notable du travail en équipe sur des codes en commun. + + La gestion de version permet de collaborer simplement et avec méthode. De façon organisée, elle permet de: + +* travailler en parallèle et fusionner facilement du code +* partager une documentation des programmes grâce : + + aux commentaires des modifications + + à la possibilité d'une documentation commune et collaborative +* trouver rapidement des erreurs et en diffuser rapidement la +correction + +A ces avantages s'ajoutent les fonctionalités collaboratives des sites de dépôt +(les principaux étant `Github` et `Gitlab`), qui permettent d'intéragir via +des *issues*, faire des suggestions de modifications, etc. + + +L'usage individuel, c'est-à-dire seul sur son projet, permet aussi de "travailler en équipe avec soi même" car il permet de retrouver des mois plus tard le contenu et le contexte des modifications. Cela est notamment précieux lors des changements de poste ou des travaux réguliers mais espacés dans le temps (par exemple, un mois par an chaque année). Même lorsqu'on travaille tout seul, on collabore avec un *moi* futur qui peut ne plus se souvenir de la modification des fichiers. + + +### Améliorer la qualité des codes + +Le fonctionnement de la gestion de version, reposant sur l'archivage structuré des modifications et les commentaires les accompagnant, renforce la qualité des programmes informatiques. Ils sont plus documentés, plus riches et mieux structurés. C'est pour cette raison que le contrôle de version ne doit pas être considéré comme un outil réservé à des développeurs : toute personne travaillant sur des programmes informatiques, gagne à utiliser du contrôle de version. + +Les services d'intégration continue permettent de faire des tests automatiques +de programmes informatiques, notamment de packages, qui renforcent la +replicabilité des programmes. Mettre en place des méthodes de travail fondées +sur l'intégration continue rend les programmes plus robustes en forçant +ceux-ci à tourner sur des machines autres que celles du développeur du code. + + +### Simplifier la communication autour d'un projet + +Les sites de dépôts `Github` et `Gitlab` permettent de faire beaucoup plus +que seulement archiver des codes. Les fonctionalités de déploiement +en continu permettent ainsi de: + +* créer des sites web pour valoriser des projets (par exemple les sites +`pkgdown` en `R`) +* déployer de la documentation en continu +* rendre visible la qualité d'un projet avec des services de *code coverage*, +de tests automatiques ou d'environnements intégrés de travail (binder, etc.) +qu'on rend généralement visible au moyen de badges +(exemple ici ) + + +### Comment faire du contrôle de version ? + +Il existe plusieurs manières d'utiliser le contrôle de version : + +* en ligne de commande, via [git bash](https://gitforwindows.org/), par exemple ; +* avec une interface graphique spécialisée, par exemple [tortoise git](https://tortoisegit.org/) ou [GitHub Desktop](https://desktop.github.com/) ; +* avec un logiciel de développement : la plupart des logiciels de développement ([RStudio](https://rstudio.com/) pour `R`, [PyCharm](https://www.jetbrains.com/fr-fr/pycharm/) ou [jupyter](https://jupyter.org/) pour `python`, [atom](https://atom.io/), etc.) proposent tous des modules graphiques facilitant l'usage de `git` dont les fonctionnalités sont très proches. + + +{{% panel status="tip" title="Tip" icon="fa fa-lightbulb" %}} +`Git` a été conçu, initialement pour la ligne de commande. Il existe +néanmoins des interfaces graphiques performantes +et pratiques, notamment lorsqu'on désire comparer deux versions d'un même +fichier côte à côte. Ces interfaces graphiques couvrent la majorité des +besoins quotidiens. Néanmoins, pour certaines tâches, il faut nécessairement +passer par la ligne de commande. +{{% /panel %}} + + +## Git: le B.A-BA + diff --git a/content/git/introgit/_index.md b/content/git/introgit/_index.md new file mode 100644 index 000000000..609a298a8 --- /dev/null +++ b/content/git/introgit/_index.md @@ -0,0 +1,130 @@ +--- +title: "Git: un élément essentiel au quotidien" +date: 2020-09-30T13:00:00Z +draft: false +weight: 10 +output: + html_document: + keep_md: true + self_contained: true +slug: introgit +--- + +Une grande partie du contenu de ce chapitre provient du cours +[Travail collaboratif avec `R`](https://linogaliana.gitlab.io/collaboratif/git.html). + +## Pourquoi faire du `Git` ? + +Tous les statisticiens se sont déjà demandé (ou à leurs collègues) : + +* quelle était la bonne version d'un programme +* qui était l'auteur d'un bout de code en particulier +* si un changement était important ou juste un essai +* comment fusionner des programmes +* etc. + +Il existe un outil informatique puissant afin de répondre à tous ces besoins : la gestion de version (*version control system* (VCS) en anglais). Ses avantages sont incontestables et permettent de facilement : + +* enregistrer l'historique des modifications d'un ensemble de fichiers +* revenir à des versions précédentes d'un ou plusieurs fichiers +* rechercher les modifications qui ont pu créer des erreurs +* partager ses modifications et récupérer celles des autres +* proposer des modifications, les discuter, sans pour autant modifier la dernière version existante +* identifier les auteurs et la date des modifications + +En outre, ces outils fonctionnent avec tous les langages informatiques (texte, R, Python, SAS, $\LaTeX$, Java, etc.) car reposent sur la comparaison des lignes et des caractères des programmes. + + +On peut ainsi résumé les principaux avantages du contrôle de version +de la manière suivante : + +1. Conserver et archiver l'ensemble des versions d'un code ou d'une documentation +2. Travailler efficacement en équipe +3. Améliorer la qualité des codes +4. Simplifier la communication autour d'un projet + + +### Conserver et archiver du code + +Une des principales fonctionnalités de la gestion de version est conserver l'ensemble des fichiers de façon sécurisée et de proposer un archivage structuré des codes. Les fichiers sont stockés dans un **dépôt**, qui constitue le projet + +Tout repose dans la gestion et la présentation de l'historique des modifications. Chaque modification (ajout, suppression ou changement) sur un ou plusieurs fichiers est identifiée par son auteur, sa date et un bref descriptif^[Plus précisément, chaque modification est identifiée de manière unique par un code `SHA` auquel est associé l'auteur, l'horodatage et des méta-données (par exemple le message descriptif associé)]. Chaque changement est donc unique et aisément identifiable quand ils sont classés par ordre chronologique. Les modifications transmises au dépôt sont appelées **commit**. + +Avec des outils graphiques, on peut vérifier l' +[ensemble des évolutions d'un fichier (`history`)](https://github.com/linogaliana/python-datascientist/commits/master/README.md), +ou [l'histoire d'un dépôt](https://github.com/linogaliana/python-datascientist/commits/master). +On peut aussi +[se concentrer sur une modification particulière d'un fichier](https://github.com/linogaliana/python-datascientist/commit/7e5d30ae0e260f9485453b42f195b0181a53e32e#diff-04c6e90faac2675aa89e2176d2eec7d8) ou vérifier, pour un fichier, la +[modification qui a entraîné l'apparition de telle ou telle ligne (`blame`)](https://github.com/linogaliana/python-datascientist/blame/master/README.md) + +Sur son poste de travail, les dizaines (centaines ?) de programmes organisés à la main n'existent plus. Tout est regroupé dans un seul dossier, rassemblant les éléments du dépôt. Au sein du dépôt, tout l'historique est stocké et accessible rapidement. Si on souhaite travailler sur la dernière version des programmes (ou sur une ancienne version spécifique), il n'y a plus besoin de conserver les autres fichiers car ils sont dans l'historique du projet. Il est alors possible de choisir sur quelle version on veut travailler (la dernière commune à tout le monde, la sienne en train d'être développée, celle de l'année dernière, etc.). + + +### Travailler efficacement en équipe + +Le deuxième avantage de la gestion de version représente une amélioration notable du travail en équipe sur des codes en commun. + + La gestion de version permet de collaborer simplement et avec méthode. De façon organisée, elle permet de: + +* travailler en parallèle et fusionner facilement du code +* partager une documentation des programmes grâce : + + aux commentaires des modifications + + à la possibilité d'une documentation commune et collaborative +* trouver rapidement des erreurs et en diffuser rapidement la +correction + +A ces avantages s'ajoutent les fonctionalités collaboratives des sites de dépôt +(les principaux étant `Github` et `Gitlab`), qui permettent d'intéragir via +des *issues*, faire des suggestions de modifications, etc. + + +L'usage individuel, c'est-à-dire seul sur son projet, permet aussi de "travailler en équipe avec soi même" car il permet de retrouver des mois plus tard le contenu et le contexte des modifications. Cela est notamment précieux lors des changements de poste ou des travaux réguliers mais espacés dans le temps (par exemple, un mois par an chaque année). Même lorsqu'on travaille tout seul, on collabore avec un *moi* futur qui peut ne plus se souvenir de la modification des fichiers. + + +### Améliorer la qualité des codes + +Le fonctionnement de la gestion de version, reposant sur l'archivage structuré des modifications et les commentaires les accompagnant, renforce la qualité des programmes informatiques. Ils sont plus documentés, plus riches et mieux structurés. C'est pour cette raison que le contrôle de version ne doit pas être considéré comme un outil réservé à des développeurs : toute personne travaillant sur des programmes informatiques, gagne à utiliser du contrôle de version. + +Les services d'intégration continue permettent de faire des tests automatiques +de programmes informatiques, notamment de packages, qui renforcent la +replicabilité des programmes. Mettre en place des méthodes de travail fondées +sur l'intégration continue rend les programmes plus robustes en forçant +ceux-ci à tourner sur des machines autres que celles du développeur du code. + + +### Simplifier la communication autour d'un projet + +Les sites de dépôts `Github` et `Gitlab` permettent de faire beaucoup plus +que seulement archiver des codes. Les fonctionalités de déploiement +en continu permettent ainsi de: + +* créer des sites web pour valoriser des projets (par exemple les sites +`pkgdown` en `R`) +* déployer de la documentation en continu +* rendre visible la qualité d'un projet avec des services de *code coverage*, +de tests automatiques ou d'environnements intégrés de travail (binder, etc.) +qu'on rend généralement visible au moyen de badges +(exemple ici ) + + +### Comment faire du contrôle de version ? + +Il existe plusieurs manières d'utiliser le contrôle de version : + +* en ligne de commande, via [git bash](https://gitforwindows.org/), par exemple ; +* avec une interface graphique spécialisée, par exemple [tortoise git](https://tortoisegit.org/) ou [GitHub Desktop](https://desktop.github.com/) ; +* avec un logiciel de développement : la plupart des logiciels de développement ([RStudio](https://rstudio.com/) pour `R`, [PyCharm](https://www.jetbrains.com/fr-fr/pycharm/) ou [jupyter](https://jupyter.org/) pour `python`, [atom](https://atom.io/), etc.) proposent tous des modules graphiques facilitant l'usage de `git` dont les fonctionnalités sont très proches. + + +{{% panel status="tip" title="Tip" icon="fa fa-lightbulb" %}} +`Git` a été conçu, initialement pour la ligne de commande. Il existe +néanmoins des interfaces graphiques performantes +et pratiques, notamment lorsqu'on désire comparer deux versions d'un même +fichier côte à côte. Ces interfaces graphiques couvrent la majorité des +besoins quotidiens. Néanmoins, pour certaines tâches, il faut nécessairement +passer par la ligne de commande. +{{% /panel %}} + + +## Git: le B.A-BA +