Scénario 3 - Usage avancé de GitHub#

Dans cette dernière activité de la journée, vous découvrirez certains des services proposés par GitHub. Ces services ne sont donc pas spécifiques à git à proprement parler mais sont plutôt des « bonus » proposés par GitHub (qui est une entreprise commerciale, propriété de Microsoft).

L’hébergement de site web via GitHub Pages, que vous avez vu lors du scénario 2, est un exemple de services « bonus » proposés par GitHub. Dans ce scénario, nous allons nous focaliser sur les Pull Requests d’une part et les « GitHub Actions » d’autre part, qui sont deux autres exemples de ces bonus.

Contribuer à un projet open source : les Pull Requests#

Résumé du scénario

Vous souhaitez contribuer à un projet open source hébergé sur GitHub en y apportant vos améliorations.

De nombreux projets open source sont hébergés sur GitHub. Pour bon nombre d’entre eux, les contributions extérieures sont les bienvenues et vous pourrez être amené(e) à proposer vos propres contributions. Pour cela, le fonctionnement est le suivant :

  1. créez une copie (un fork en langage git) du dépôt auquel vous souhaitez contribuer sur votre compte ;

  2. apportez vos modifications sur cette copie ;

  3. envoyez vos modifications au dépôt originel via une proposition, appelée Pull Request (les administrateurs du dépôt originel auront ainsi le choix d’accepter vos modifications, de vous demander des améliorations, etc).

Vous allez travailler sur le projet demo_kmeans hébergé à l’adresse rtavenar/demo_kmeans.

  • Créez un fork de ce projet sur votre compte GitHub, puis clonez ce dépôt sur votre machine.

  • Éditez le script Python contenu dans ce projet pour implémenter l’un (ou plusieurs) des TODO proposés

  • Créez un point de sauvegarde (commit) et envoyez vos modifications vers le dépôt origin (votre copie, hébergée sur votre compte GitHub)

  • Ajoutez un nouveau dépôt distant que vous nommerez origin-rtavenar et pointant vers le dépôt https://github.com/rtavenar/demo_kmeans.git

  • Tentez de pousser vos modifications locales vers ce dépot distant, que remarquez-vous ?

  • Pour contribuer au dépôt rtavenar/demo_kmeans, vous devrez donc passer par une Pull Request. Vérifiez que vos modifications locales ont bien été envoyées vers votre dépôt GitHub. Vous devez voir un bandeau apparaître vous indiquant qu’il vous est possible d’ouvrir une Pull Request pour contribuer au dépôt rtavenar/demo_kmeans. Suivez cette procédure pour proposer vos modifications au dépôt en question.

Présentation des GitHub Actions#

Une GitHub Action est une opération qui pourra être exécutée à chaque fois qu’un événement a lieu sur un dépôt GitHub. L’événement que nous utiliserons dans un premier temps comme déclencheur de nos Actions est l’arrivée d’un nouveau commit, mais sachez que de nombreux autres types d’événements peuvent déclencher des GitHub Actions (par exemple l’ouverture d’une Pull Request). On peut même déclencher les GitHub Actions à intervalle régulier, chaque nuit par exemple. Vous pourrez trouver une longue liste des événements qui peuvent déclencher une GitHub Action ici : https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows

Résumé du scénario

Vous allez récupérer sur GitHub un modèle de rapport de stage en LaTeX. Supposons que vous rédigez ce rapport sur une machine qui ne dispose pas d’une suite LaTeX bien installée. Nous allons donc faire en sorte que, à chaque push vers votre dépôt GitHub, votre rapport de stage soit compilé et un PDF généré automatiquement pour vous permettre de vérifier ce que vous avez fait.

  • Clonez le projet rtavenar/modele_rapport_stage vers votre répertoire tutoriel_git sous le nom rapport_de_stage.

  • Modifiez le fichier main.tex pour qu’il contienne vos noms et prénoms, et créez un commit pour valider ces modifications.

  • Sauvegardez votre projet sur GitHub et vérifiez que votre commit local y est visible.

Les GitHub Actions sont définies dans le répertoire (à créer) .github/workflows par des fichiers .yml.

  • Créez un fichier (vide pour le moment) compile_latex.yml dans le répertoire .github/workflows.

  • Ouvrez ce fichier, et ajoutez-y le code nécessaire pour utiliser l’action xu-cheng/latex-action.

  • Créez un commit local, puis envoyez-le vers votre dépôt GitHub.

  • Dans l’onglet « Actions », vous devez voir un « workflow » qui s’exécute. Vous pouvez cliquer dessus pour vérifier qu’il a bien fonctionné. Toutefois, pour le moment, vous ne pouvez pas récupérer le fichier PDF produit, ce qui limite fortement l’intérêt de la méthode.

  • Dans les steps définies dans votre fichier compile_latex.yml, ajoutez une étape d’upload du fichier généré sur GitHub, grâce à l’action actions/upload-artifact (attention à faire pointer la variable path vers le bon fichier).

  • Envoyez la nouvelle version vers votre dépôt GitHub et vérifiez que, une fois le « workflow » exécuté, vous pouvez télécharger un « artifact » : votre rapport au format PDF.

  • Modifiez votre « workflow » pour qu’il s’exécute non seulement à chaque fois qu’a lieu un push, mais aussi à chaque création d’une nouvelle Pull Request.

  • Créez une nouvelle branche de développement dans laquelle vous modifiez votre fichier main.tex. Créez un commit sur cette branche et effectuez un push de cette branche vers votre dépôt GitHub. Générez une Pull Request à partir de cette branche (oui, vous pouvez générer des Pull Requests sur vos propres dépôts) et vérifiez que le fichier PDF compilé apparaît sur votre Pull Request.