Git et Github - Versionner son code

Git (prononcer Guitt) a été écrit par Linus Torvalds, le créateur de Linux, pour versionner du code c'est-à-dire l'enregistrer étape par étape afin de pouvoir travailler dessus sur plusieurs machines et/ou à plusieurs codeurs. Git permet également de revenir à une version antérieure du code, qui fonctionnait avant que l'on en fasse une infâme bouillie emplie de bugs.

Github (prononcer Guitteub) est un service qui permet d'enregistrer sur un serveur distant les différentes versions de son code, à l'aide de commandes Git. Il est gratuit pour du code public, payant pour du code privé. Il permet aussi de partager des bouts de code (des gists) qui simplifient la vie de tous les autres codeurs, ou bien de participer à un projet existant.

Vous pouvez soit installer Git tout seul :

apt install git

… soit installer les outils de développement de Mint, avec tous les paquets recommandés (si vous êtes sous LinuxMint) :

sudo apt-get install --install-recommends mint-dev-tools

Après cela, votre menu 'Programmation' sera bien rempli !

Personnellement, j'y ajoute l'indispensable éditeur Geany et ses plugins :

apt install geany geany-plugins

Les Spices de Cinnamon sont les applets, les desklets, les extensions et les thèmes. La présentation des Spices existantes est ici.

Faire un fork (fourche), c'est placer dans son propre espace Github du code déjà existant afin de pouvoir le modifier à sa guise, le tester, ajouter des fichiers, etc.

Dans Github, rien de plus simple. Une fois connecté sur github.com, se rendre sur https://github.com/linuxmint/cinnamon-spices-applets et cliquer sur le bouton Fork.

Ensuite créez une branch (branche), en lui donnant un nom approprié, pour chacune des applets que vous voulez créer ou modifier. Si, dans la même branche, plusieurs applets sont modifiées, votre code ne sera pas accepté.

Par exemple, je veux créer une applet nommée vpnLookOut@claudiux (ceci est l'UUID de l'applet ; UUID signifiant Universal Unique IDentifier) je vais donc créer la branche vpnLookOut.

Il est temps de faire une copie de ce code sur votre ordinateur, afin de pouvoir y travailler.

Commencez par créer le dossier de travail et placez-vous dedans :

mkdir ~/git
cd ~/git

Lancez la copie :

git clone https://github.com/claudiux/cinnamon-spices-applets.git

(Remplacez claudiux par votre identifiant Github.)

Le dossier ~/git/cinnamon-spices-applets a été créé et contient le code de toutes les applets de Cinnamon. Placez-vous dedans :

cd ~/git/cinnamon-spices-applets

Configurez git :

git config --global user.name "votre_id_github"
git config --global user.email "votre@email"

Si vous voulez que votre applet ait des chances d'être acceptée parmi les Spices de Cinnamon, il faut créer ce type d'arborescence dans ~/git/cinnamon-spices-applets :

vpnLookOut@claudiux
└── files
    └── vpnLookOut@claudiux
        ├── icons
        ├── po
        └── scripts

Pour ce faire :

cd ~/git/cinnamon-spices-applets
mkdir -p vpnLookOut@claudiux/files/vpnLookOut@claudiux/{icons,po,scripts}

Il doit contenir, en plus du dossier files, les fichiers suivants :

• info.json
• CHANGELOG.md
• README.md
• icon.png
• screenshot.png

Le fichier info.json contient uniquement l'id de l'auteur :

{
    "author": "claudiux"
}

Les fichiers CHANGELOG.md et README.md sont au format Markdown et leur contenu doit être écrit en anglais. Le premier contient l'historique des changements au fil des versions ; le second contient la présentation et l'aide à l'utilisateur.

Le fichier image icon.png (48×48 px) est l'icône qui apparaîtra notamment dans la liste des applets installées ou que l'on peut installer (Centre de Contrôle → Applets, ou bien clic-droit sur un panel et “Ajouter des applet au tableau de bord”).

Le fichier image screenshot.png est une capture d'écran qui montre l'applet en situation (avec éventuellement un menu apparent).

Tous ces fichiers servent à la conception automatique de la page de présentation de l'applet.

Il ne contient que le second dossier vpnLookOut@claudiux.

Il contient l'applet elle-même et reproduit ce qui se trouve dans ~/.local/share/cinnamon/applets/vpnLookOut@claudiux où doit être placé le code de l'applet pour pouvoir l'utiliser.

Les dossiers icons, po et scripts ne sont pas obligatoires mais fortement conseillés pour une bonne structuration du code.

• icons contient les différentes icônes (22×22 ou 24×24 px) que l'applet est susceptible d'afficher, si l'icône apparaissant sur le panel doit changer en fonction des événements.
• po contient tous les fichiers nécessaires aux traductions des messages dans différentes langues ; il est conseillé d'utiliser le logiciel poedit pour les gérer.
• scripts contient, si nécessaire, des scripts (en bash, en python…) appelés par l'applet pour interagir avec le système.

Comme fichiers, ce second dossier vpnLookOut@claudiux doit contenir, au minimum :

• Une copie des fichiers icon.png, CHANGELOG.md et README.md du premier dossier vpnLookOut@claudiux ; ne pas faire de lien symbolique.
• Deux fichiers indispensables :
  • metadata.json qui contient les méta-données concernant l'applet. (Voir ci-dessous.)
  • applet.js qui contient le code javascript de l'applet.
• Si l'applet doit proposer à l'utilisateur de la configurer, il faut rajouter un fichier settings-schema.json.
• Si nécessaire, on peut rajouter tout autre fichier ; par exemple une feuille de style : stylesheet.css.

Vous pouvez prendre des exemples de ces fichiers dans le Github de l'applet vpnLookOut@claudiux.

{
    "description": "A Cinnamon applet that watches over the VPN link, displays its status, allows to connect at start-up to the last VPN used, allows to reconnect the VPN link if it incidentally drops, and can stop or restart Transmission according to the state of the VPN.", 
    "max-instances": "1", 
    "dangerous": false, 
    "hide-configuration": false,
    "uuid": "vpnLookOut@claudiux", 
    "name": "VPN Look-Out Applet", 
    "version": "2.0.0", 
    "last-edited": 1514652300
}

Votre arborescence est créée, les fichiers sont placés correctement à l'intérieur.

Vérifiez d'abord que votre applet est prête a être envoyée sur Github:

cd ~/git/cinnamon-spices-applets
./validate-spice vpnLookOut@claudiux

(Remplacez vpnLookOut@claudiux par le nom du dossier contenant votre applet.)

La réponse doit être:

✔ ✔ ✔ ✔ ✔ vpnLookOut@claudiux is valid!

Il est temps d'enregistrer les changements dans Github. Il vous faut :

1. vous placer dans votre branch (ici : vpnLookOut),
2. y ajouter le dossier vpnLookOut@claudiux,
3. et effectuer un commit.

git checkout vpnLookOut
git add vpnLookOut@claudiux
git commit -m "vpnLookOut@claudiux: (ici une brève description en anglais)"

Il ne vous reste plus qu'à faire un push de votre applet sur Github. (Le code est compressé, puis envoyé sur Github où il est décompressé.)

git push origin vpnLookOut

Pour vérifier que tout s'est bien passé :

git status

La réponse doit être :

Sur la branche vpnLookOut
Votre branche est à jour avec 'origin/vpnLookOut'.
rien à valider, la copie de travail est propre

Rendez-vous alors sur la page de votre branch https://github.com/claudiux/cinnamon-spices-applets/tree/vpnLookOut ; vous y verrez votre applet apparaître dans la liste. Une bonne chose de faite !

Mais ce n'est pas tout, il vous faut maintenant…

Les mainteneurs (maintainers) de Cinnamon doivent vérifier le code de votre applet et la tester avant d'accepter son intégration dans la liste des applets disponibles aux utilisateurs.

Pour cela, vous devez faire une Pull Request (souvent abrégé en PR dans les discussions).

Sur la page de votre branch https://github.com/claudiux/cinnamon-spices-applets/tree/vpnLookOut, cliquez sur New Pull Request. Renseignez (en anglais) la raison de votre demande, en décrivant ce que fait votre applet. Une page s'ouvre, pour laquelle il est conseillé de créer un signet (ou favori) dans votre navigateur. Cette page permet de discuter avec les maintainers, qui vous demanderont éventuellement d'apporter quelques modifications. Il vous faudra alors effectuer les modifications demandées, effectuer pour chacune d'elles un git add et un git commit ; une fois tout cela fait, refaire un git push et signaler dans la discussion que tout est OK.

Et enfin, peut-être…

(Discussion complète)

Au bout de quelques temps, vous vous apercevrez que votre fork ne ressemble plus à l'original ; notamment, il ne contient pas la dernière version de votre applet, celle qui a fait l'objet du dernier pull request et a été intégrée à linuxmint/cinnamon-spices-applets. Cela peut soulever quelques problèmes lors du prochain pull request, notamment obliger les mainteneurs à régler des conflits de versions de fichiers et ils ont bien d'autres chose à faire !

Voici donc comment garder votre fork à jour, sur Github comme localement.

Placez-vous dans votre dépôt local :

cd ~/git/cinnamon-spices-applets/

Entrez la commande :

git remote -v

Vous verrez votre dépôt origin s'afficher :

origin	https://github.com/claudiux/cinnamon-spices-applets.git (fetch)
origin	https://github.com/claudiux/cinnamon-spices-applets.git (push)

On va déclarer le dépôt de linuxmint comme dépôt upstream (dépôt amont). Allez sur le Github du dépôt upstream https://github.com/linuxmint/cinnamon-spices-applets et cliquez sur le bouton “Clone or download”, copiez l'adresse commençant par https qui vous est proposée (utilisez le bouton situé à droite de cette adresse).

Entrez la commande : git remote add upstream suivi de l'adresse que vous collez (bouton droit, Coller) :

git remote add upstream https://github.com/linuxmint/cinnamon-spices-applets.git

Pour vérifier que tout s'est bien passé :

git remote -v

doit afficher quelque chose qui ressemble à cela :

origin	https://github.com/claudiux/cinnamon-spices-applets.git (fetch)
origin	https://github.com/claudiux/cinnamon-spices-applets.git (push)
upstream	https://github.com/linuxmint/cinnamon-spices-applets.git (fetch)
upstream	https://github.com/linuxmint/cinnamon-spices-applets.git (push)

L'upstream étant bien déclaré, on va recopier localement sa branche master. Attention ! C'est l'opération qui détruit tout ce qui n'est pas dans la branche master de l'upstream !

git checkout master
git fetch upstream
git merge upstream/master

Une fenêtre s'ouvre, vous demandant de renseigner un message de validation. Après avoir écrit cette ligne de message, fermez l'éditeur de texte (ctrl-X pour nano, [échap]:x pour vim).

Enfin mettez à jour le fork de votre Github :

git push origin master

C'est fait !

Sur Github, vous constaterez la parfaite correspondance entre le dépôt upstream et votre fork ; détruisez-y votre branche vpnLookOut et recréez-la.

Localement, replacez-vous dans votre branche de développement vpnLookOut :

git checkout vpnLookOut2

Vous pouvez ensuite y placer votre nouveau code, y faire des git add … (et compagnie) et des git commit -m “…” jusqu'au prochain git push … suivi de la prochaine pull request.

Bon codage !

git remote add upstream <original-repo-url> 
git fetch upstream # update local with upstream 
git diff HEAD..upstream/master # see diffs between local and upstream/master (if there is no diff then both are in sync) 
git pull upstream master # pull upstream's master into local branch 
git push -f origin HEAD # push to your forked repo's remote branch 

• Gérer son code avec Git et Github, sur OpenClassRooms
• Les commandes git
• Comprendre Git
• Le livre Pro Git en ligne et en français !
• Comprendre et utiliser Git avec vos projets
• Bien utiliser merge et rebase
• How to rebase a Pull Request
• Comment squasher efficacement ses commits avec Git
• GitHub : fork d'un dépot : faire des pulls requests d'uniquement quelques commits
• Github
• Managing your work on GitHub
• Searching for information on GitHub
• Forking project
• Forker un repo Github
• Syncing a fork
• Pushing to a remote
• Message Github: Your branch is ahead by x commits - Solutions

• Le dernier code en date de l'applet vpnLookOut@claudiux, sur Github
• Page de présentation de l'applet vpnLookOut@claudiux, sur Cinnamon Spices
• Le Github des Cinnamon Spices Applets
• Le Github de LinuxMint

1 personne a visité cette page aujourd'hui et 1055 en tout.