Participer à l'amélioration d'une publication via Github

introduction :

Le travail dans l'équipe du groupe Tremplin autour des IoT (Internet of Things type Intel edison) des nano machines (Raspberry Pi, Odroïd, Intel joule) entre dans une phase de déploiement d'outils à destination de nos élèves. Tout le travail effectué étant libre, c'est une opportunité pour fédérer nos efforts et obtenir des solutions adaptables et partagées. La stratégie retenue par Gérard Vidal est de permettre à chacun de travailler sur une branche des "Cahiers de Programmes" afin de pouvoir disposer de tout le travail effectué et librement réaliser un objet correspondant a ses propres besoins avant de le proposer à la communauté.

Comme dans le groupe nous ne sommes pas des usagers de Github, suivre la consigne peut parfois conduire à des maladresses. Voici donc un résumé des étapes à franchir pour pouvoir contribuer et un memo des commandes qui nous permettent de proposer à la communauté nos améliorations/modifications de l'existant.

Pourquoi utiliser GitHub

L'accompagnement et le suivi d'un travail collaboratif en ligne pose de très gros problèmes, même lorsque l'on a à faire à une communauté peu nombreuse. dans le monde logiciel des outils ont été créés spécialement pour cette fonction et fort heureusement ils peuvent s'appliquer à d'autre constructions collaboratives que le code.

En 2005 Linus Torvalds (l'un des deux pères dus ystème d'exploitation gnu-linux) a été confronté au problème de gestion du code source de linux du fait d'un changement de politique du propriétaire de l'outil qui assurait cette fonction. Il a créé le logiciel git pour répondre à ses besoins et a donné à la communauté un extraordinaire outil collaboratif pour créer des ressources. De nombreux dépôts de logiciels et de ressources ont adopté le logiciel git pour proposer des usagescollaboratifs à leurs inscrits. les resources de ce projet sont sur github et framagit pour les plus exigeants sur la nature libre du travail.

Git permet de gérer un espace collaboratif en ligne tout en ayant sur son propre ordinateur la copie intégrale du projet ainsi que son état d'avancement. Le travail se fait donc sur sa machine puis on opère ensuite une synchronisation en ligne en contribuant (ou pas) son travail et récupérant (ou pas) le travail des autres contributeurs. le propriétaire du dépôt régulant ce qui entre ou sort de la version officielle appelée master.

Etape 1 : créer un compte sur github

Il s'agit d'une étape préliminaire, il suffit de suivre les consignes du site github Pensez à remplir votre profil, placez une photo de portrait, cet espace est plein de gens qui cherchent à faire avancer les choses, avoir affaire à un protrait au lieu d'un avatar est plus agréable. Dites aussi un mot de ce que vous êtes et de ce que vous faites.

Etape 2 : Regarder ce que Gérard propose et choisir ses sujets de collaboration.

Nous pouvons contribuer sur les éléments de mutualisation des usages. Il y a donc 3 "repositories" qui peuvent concerner l'équipe Tremplin : * Cahiers de Programmes, * WeatherStation, * iteeXe.

Etape 3 : Utiliser une RaspberryPi 3 et sa dernière image en ligne.

Pour pouvoir travailler de façon efficace il faut disposer d'une raspberryPi3 qui dispose d'un accès à internet et sur laquelle vous pouvez vous connecter aisément en ssh. Tout les éléments nécessaires à la mise en place d'une telle machine sont décrits dans le Blog Tremplin de Gérard, pour créer sa propre image pour RaspberryPi il y a un autre blog et

le lien permet de télécharger la dernière image disponible.

La Raspberry Pi équipée de cette image renferme un outil "Jupyterhub" qui va vous permettre d'éditer les fichiers de la branche que vous gérez, pouvu que vous ayez cloné le "repository" github puis que vous ayez créé votre branche.

Etape 4 : Le clonage du dossier cible sur la raspberryPi

Sur la raspberry une fois loggé vous pouvez dans votre "home" créer un dossier qui pourrait s'appeler "TremplinGithub".

Dans ce dossier vous allez cloner le dossier cible, ceci est réalisé grâce à une commande qui pointe vers l'URL du répertoire qui est livrée par le bouton "clone or download" du "directory" choisi.

git clone url_du_dossier 

L'étape suivante requiert une assitance de Gérard Vidal car il faut que vous soyez collaborateur du projet pour être autorisé à créer votre branche. Si vous ne souhaitez pas vous engager il est toujours possible de créer votre propre projet par clonage du projet existant en utilisant le bouton Fork depuis la page de garde du projet.

Sur sa machine on crée la branche avec cette commande :

git checkout -b nomdevotrebranche 

Pour plus d'homogénéité on peut souhaiter que les noms de branches soient stéréotypés mais ce n'est absolument pas une obligation. Ontravaille sur le document sur sa branche sur sa machine. Puis il faut remonter le contenu la branche sur le serveur github (sous réserve de la configuration du compte github).

git push origin nomdevotrebranche

le site vous demande vos identifiants

• Username for 'https://github.com': votrelogin
• Password for 'https://votrelogin@github.com':

Il faut alors que vous soyez collaborateur du dossier cible pour que la branche se construise sur github

Lorsque vous travaillez localement vous pouvez vérifier que êtes bien sur votre branche avec la commande :

git branch -a

et si vous ne l'êtes pas lancer la commande suivante qui vous place dans votre branche en local.

git checkout nomdevotrebranche

Voilà vous pouvez maintenant commencer à produire un contenu, il restera à le proposer à la validation.

Etape 5 : La création de contenu et son dépôt sur Github

Retenir la séquence suivante :

• faire le point : git status /git branch -a /git remote -v
• changer de branche : git checkout nomdelabranche
• prendre en compte (ou pas) les modifications : git stash
• ajouter les fichiers modifiés : git add
• faire un fichier de commit des modifications : git commit
• pousser les modifications dans la branche sur github : git push

Faire le point

La commande "git status" renvoie les noms des fichiers que vous avez modifiés.

La commande "git branch -a" dit sur quel branche vous vous trouvez en local.

La commande "git remote -v" dit sur quel branche vous allez envoyer en distant

Mettre à jour sa branche locale (par exemple proposedCHE)

git checkout master : on passe sur la branche master

git pull : on met à jour la branche master

git checkout proposedCHE : on passe sur la branche proposedCHE

git merge master : on merge sa branche proposedCHE avec la branche master

git push : on pousse sa branche locale sur le dépot distant

Prendre en compte (ou pas) les modifications en cours de la branche locale

la commande git stash met de côté sans les supprimer toutes les modifications en cours que l'on ne souhaite pas partager mais que l'on souhaite conserver

git stash

pour effacer les modifications locales, on utilise "git checkout".

La commande ci-dessous dit d'écraser les modifications apportées en local sur le fichier uneLed.pynb

git checkout -a uneLed.pynb

Ajouter les fichiers

Ajouter les fichiers que vous souhaitez soumettre.

git add copier/collerlepathdufichiermodifiéaffichéprécédemment

Faire le fichier de commit

Il faut faire maintenant le fichier de commit pour le ou les fichiers choisis.

git commit

Dans l'éditeur vous décrivez votre travail ou votre contribution de façon aussi détaillée que possible pour que la validation en soit facilitée.

Dans l'éditeur jed pour sauvegarder "Ctrl+X+S" puis pour sortir de l'éditeur shell "Ctrl+X+C"

Dans l'éditeur nano "Ctrl X", "Ctrl O"

Pousser les contenus

git push

ou la première fois

git push --set-upstream origin nomdevotrebranche

git branch --setupstream-to=origin/proposedCHE proposedCHE

Etape 6 : Faire un "pull Request"

Rendez-vous dans le repository sélectionnez votre branche et cliquez sur "compare and pull request" compléter le commit par un commentaire plus détaillé si nécessaire.

Conclusion :

Voilà, ces étapes peuvent sembler fastidieuses, mais on ne fait en fin de compte que les étapes 5 et 6 de façon routinière dès que le clone est en place.

Compléments sur les commandes git sur le site Github