{{tag>Git Github Cinnamon Applet Code}} ====== Git et Github - Versionner son code ====== **Git** (prononcer //Guitt//) a été écrit par [[https://fr.wikipedia.org/wiki/Linus_Torvalds|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. ===== Pré-requis ===== La première chose à faire est donc de [[https://github.com/|créer un compte sur Github]]. N'oubliez pas, dans votre compte, de spécifier un identifiant (un seul mot) ; le mien est claudiux. C'est une longue histoire... 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 ===== Participer à un projet existant: Les Spices de Cinnamon ===== Les //Spices// de Cinnamon sont les //applets//, les //desklets//, les //extensions// et les //thèmes//. La présentation des //Spices// existantes est [[https://cinnamon-spices.linuxmint.com/|ici]]. Nous allons voir comment créer une applet ou en modifier une, et proposer son code à l'équipe de Cinnamon ou aux développeurs de l'applet modifiée. ==== Faire un fork et créer une branche ==== 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''. ==== Faire un clone local du code ==== 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" ==== Créer l'arborescence locale pour l'applet ==== 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} ==== Détails de ce que DOIT contenir cette arborescence ==== === Le premier dossier vpnLookOut@claudiux === 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 [[https://guides.github.com/features/mastering-markdown/|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 (48x48 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 [[https://cinnamon-spices.linuxmint.com/applets/view/305|page de présentation de l'applet]]. === Le dossier files === Il ne contient que le second dossier vpnLookOut@claudiux. === 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 (22x22 ou 24x24 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 [[https://github.com/claudiux/cinnamon-spices-applets/tree/vpnLookOut/vpnLookOut%40claudiux|le Github de l'applet vpnLookOut@claudiux]]. Le fichier ''metadata.json'' ressemble à ceci. { "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 } Attention, la ligne contenant "dangerous" ne doit pas apparaître dans le fichier ''metadata.json'' proposé à l'équipe de Cinnamon. Dans le champ "last-edited" vous devez indiquer la date de dernière édition de l'applet, au format Unix Epoch, qui est le nombre de secondes écoulées depuis le 1er janvier 1970. Le site [[https://www.epochconverter.com/|EpochConverter]] vous y aidera. ==== Votre premier commit ==== 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 : - vous placer dans votre //branch// (ici : ''vpnLookOut''), - y ajouter le dossier ''vpnLookOut@claudiux'', - 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... ==== Demander l'intégration de votre applet ==== 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... {{:linuxaddict:coder:screenshot_20171216-100959.png?nolink&400|}} ([[https://github.com/linuxmint/cinnamon-spices-applets/pull/1564|Discussion complète]]) ==== Garder votre fork à jour ==== 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. Sauvegardez dans un autre dossier ou fichier compressé local (hors de ''~/git/'') toutes les modifications que vous auriez pu effectuer depuis le dernier //pull request// ! Tout sera écrasé lors de la mise à jour du //fork//. 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 ! ==== Refork (2) ==== git remote add upstream 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 ===== Liens ===== * [[https://openclassrooms.com/courses/gerer-son-code-avec-git-et-github|Gérer son code avec Git et Github, sur OpenClassRooms]] * [[https://doc.ubuntu-fr.org/git|Les commandes git]] * [[https://www.grafikart.fr/formations/git|Comprendre Git]] * Le livre [[https://git-scm.com/book/fr/v2|Pro Git]] en ligne et en français ! * [[https://blog.lesieur.name/comprendre-et-utiliser-git-avec-vos-projets/|Comprendre et utiliser Git avec vos projets]] * [[https://delicious-insights.com/fr/articles/bien-utiliser-git-merge-et-rebase/|Bien utiliser merge et rebase]] * [[https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request|How to rebase a Pull Request]] * [[https://www.ekino.fr/publications/comment-squasher-efficacement-ses-commits-avec-git/|Comment squasher efficacement ses commits avec Git]] * [[https://christophe.hurpeau.com/billet/062-GitHub-fork-d-un-depot-faire-des-pulls-requests-d-uniquement-quelques-commits.html|GitHub : fork d'un dépot : faire des pulls requests d'uniquement quelques commits]] * [[https://github.com/|Github]] * [[https://help.github.com/categories/managing-your-work-on-github/|Managing your work on GitHub]] * [[https://help.github.com/categories/searching-for-information-on-github/|Searching for information on GitHub]] * [[https://guides.github.com/activities/forking/|Forking project]] * [[https://www.christopheducamp.com/2013/12/16/forker-un-repo-github/|Forker un repo Github]] * [[https://help.github.com/articles/syncing-a-fork/|Syncing a fork]] * [[https://help.github.com/articles/pushing-to-a-remote/|Pushing to a remote]] * [[https://stackoverflow.com/questions/2432579/git-your-branch-is-ahead-by-x-commits|Message Github: Your branch is ahead by x commits - Solutions]] * [[https://github.com/claudiux/cinnamon-spices-applets/tree/vpnLookOut/vpnLookOut%40claudiux|Le dernier code en date de l'applet vpnLookOut@claudiux, sur Github]] * [[https://cinnamon-spices.linuxmint.com/applets/view/305|Page de présentation de l'applet vpnLookOut@claudiux, sur Cinnamon Spices]] * [[https://github.com/linuxmint/cinnamon-spices-applets|Le Github des Cinnamon Spices Applets]] * [[https://github.com/linuxmint|Le Github de LinuxMint]] ---- {{counter|today| personne a visité cette page aujourd'hui| personnes ont visité cette page aujourd'hui}} et {{counter}} en tout.