Ce document est un guide simple et dépouillé qui vous permettra de passer le plus rapidement possible de "Qu'est-ce que Git ?" à "Tout le monde devrait utiliser ma toute nouvelle feuille de personnage", sans essayer de vous enseigner toutes les subtilités du système. Git est un logiciel de contrôle de version, mais ce guide ignorera totalement comment vous pouvez l'utiliser pour suivre vos changements, et se concentrera uniquement sur le transfert de vos mises à jour vers le dépôt principal Roll20. La section "Plus d'informations" contient des liens vers des guides généraux sur le fonctionnement de Git/GitHub.
Qu'est-ce que Git/GitHub ?
Gitest un logiciel que vous installez localement sur votre ordinateur et qui gère le contrôle de version pour vous. GitHubest un service d'hébergement pour les dépôtsGit. Il ne s'agit donc pas de la même chose :Gitest l'outil,GitHubest le service pour les projets qui utilisentGit. Brève comparaison.
Il existe plusieurs façons d'utiliser Git. Git est très puissant, mais pour en tirer le meilleur parti, vous devez apprendre à utiliser l'interpréteur de commandes (xkcd comic). La section "Plus d'infos" au bas de la page contient des informations complémentaires sur l'interpréteur de commandes pour les personnes intéressées. Cependant, tout ce que ce document va vous expliquer peut être fait en utilisant seulement l'interface graphique GitHub Desktop (très bon pour garder le disque dur de votre ordinateur synchronisé avec votre dépôt - voir "Cloner votre dépôt" ci-dessous) et les outils web GitHub qui sont tous deux des outils simplifiés pour utiliser le système Git sous-jacent.
Configuration de GitHub
Créez votre compte
Pour utiliser GitHub, vous devez disposer d'un compte sur leur site web. Vous pouvez créer un compte payant ou un compte gratuit. À moins que vous ne prévoyiez de créer un grand nombre de projets que vous ne souhaitez pas partager avec le reste du monde, il n'y a aucune raison de créer un compte payant : la seule différence entre les différents niveaux de prix est le nombre de dépôts privés que vous êtes autorisé à avoir. Tout le monde, y compris les comptes gratuits, peut disposer d'un nombre illimité de dépôts publics.
Vous aurez affaire aux dépôts principaux de Roll20 pour roll20-character-sheets et/ou roll20-api-scripts qui sont des dépôts publics. Vous allez également créer un fork de ces dépôts, qui pourraient aussi bien être publics, donc pour vos utilisations de Roll20, un compte gratuit est tout ce dont vous avez besoin.
FORK le dépôt officiel de Roll20
Un forkest une copie d'un dépôt. Le forçage d'un dépôt vous permet d'expérimenter librement des modifications sans affecter le projet d'origine.
Le forçage est facile à réaliser à l'aide des outils web de GitHub. Cliquez sur le bouton "Fork" du dépôt officiel situé à l'adressehttps://github.com/Roll20/roll20-character-sheetsouhttps://github.com/Roll20/roll20-api-scriptsselon le cas. Cela créera une copie de ce référentiel dans votre compte, que vous aurez le droit de modifier à votre guise. Vouspouvezforker le dépôt autant de fois que vous le souhaitez, mais vousn'avez besoinde le forker qu'une seule fois. Ce nouveau dépôt aura une adresse identique à l'original, sauf qu'au lieu d'avoir la racine "Roll20", il aura la racine de votre nom de compte roll20.
Si vous travaillez avec un autre utilisateur sur la même feuille ou le même script, il peut être judicieux d'aller dans les paramètres de votre nouveau dépôt et de l'ajouter en tant que collaborateur. Les détails concernant l'ajout d'un collaborateur ou le travail avec un collaborateur dépassent toutefois le cadre de ce tutoriel.
Si vous êtes familier avec le système de contrôle de version Git, vous ne devriez pas avoir besoin d'autres informations pour compléter votre feuille de personnage. Pour tous les autres, lisez la suite !
CLONEz votre référentiel
Clonageun référentiel fait également une copie, mais un référentiel cloné est utilisé comme une copie de travail et se trouve sur le disque dur de votre ordinateur local comme des dossiers et des fichiers normaux. Git maintient un lien - nommé par défaut "origin" - entre les dossiers et le dépôt à partir duquel ils ont été clonés.
Pour les utilisateurs débutants de Git, il est fortement recommandé de télécharger et d'installerGitHub pour WindowsouGitHub pour Macen fonction de votre système d'exploitation. Elles seront ci-après désignées dans ce document par "GitHub Desktop" ou "l'application de bureau". En plus d'être un moyen simple d'installer et de configurer le contrôle de version Git sur votre ordinateur, les applications de bureau GitHub permettent de se connecter facilement à votre compte utilisateur GitHub. Il vous indiquera si vos fichiers sur votre ordinateur ne sont pas à jour par rapport à votre dépôt sur GitHub et vous permettra de synchroniser facilement les deux.
Lorsque vous lancez l'application GitHub pour la première fois, vous êtes invité à vous connecter à votre compte GitHub. Ensuite, cliquez sur le grand signe plus en haut à gauche pour Cloner votre référentiel. Lorsque vous clonez le référentiel, vous êtes invité à sélectionner un emplacement où placer les fichiers. Veillez à choisir un lieu facile d'accès, vous aurez besoin de savoir où il se trouve ! Si vous changez d'ordinateur, l'installation du bureau GitHub et le clonage de votre dépôt sont les seules étapes à répéter.
L'application de bureau dispose également de l'interface la plus simple pour gérer les succursales. Lorsque vous changez de branche dans l'application de bureau, celle-ci ajoutera, supprimera ou modifiera les fichiers de manière à ce qu'ils correspondent au dernier commit effectué à partir de la branche vers laquelle vous avez basculé.
Si vous n'utilisez pas l'application GitHub, vous pouvez trouver l'url de clonage de votre dépôt sur la page de votre dépôt. GitHub propose des urls de clonage SSH et HTTPS, ainsi qu'une url d'extraction Subversion. Les détails du clonage manuel de votre répertoire dépassent toutefois le cadre de ce guide.
Flux de travail GitHub Forking
La configuration ci-dessus n'est effectuée qu'une seule fois. La section suivante décrit les procédures qu'il est recommandé de suivre chaque fois que vous souhaitez soumettre une mise à jour à Roll20.
Synchronisez vos fichiers avec Roll20
Si vous venez de forker et de cloner votre dépôt il y a quelques minutes, il est toujours synchronisé. Mais si tu reviens sur ton référentiel après plusieurs semaines ou mois, certaines des fiches de personnage ou des scripts Mod (API) auront été mis à jour. Il est possible que celui que vous souhaitez modifier en fasse partie. Dans ce cas, vous devez vous assurer que vous travaillez avec la toute dernière version des fichiers que vous allez modifier. Tu n'as pas besoin de créer un autre fork, ni de cloner à nouveau ton référentiel. Vous devrez mettre à jour votre fork avec le master. Lisez le guide ci-dessous sur la synchronisation.
Plutôt que d'effectuer une synchronisation qu'elle soit nécessaire ou non, vous pouvez d'abord vérifier si vous avez besoin de synchroniser le(s) projet(s) sur lequel(s) vous allez travailler. Une vérification facile consiste à examiner les fichiers dans le référentiel Roll20 et à voir la date de la dernière modification. Une autre solution consiste à ouvrir les fichiers et à lancer un utilitaire "diff" surà partir de ces fichiers et de votre version la plus récente. Vérifiez s'il y a des Pull requests en cours pour les fichiers que vous allez mettre à jour. Si les fichiers spécifiques que vous allez modifier sont inchangés depuis la dernière synchronisation, il est facultatif d'effectuer une synchronisation complète de tous les fichiers.
Une autre option consiste à extraire toutes les mises à jour du dépôt principal Roll20. Cela te permettra de récupérer toutes les mises à jour effectuées par d'autres personnes sur les référentiels roll20 depuis la dernière synchronisation (y compris toute une série de fiches de personnage ou de scripts Mod (API) qui pourraient ne pas t'intéresser). Ce lien contient un guide pour synchroniser ton référentiel avec l'Original. Lorsque vous avez terminé, les fichiers du dépôt principal de Roll20, de votre propre dépôt et de votre disque dur doivent tous être identiques. Veillez également à mettre à jour votre campagne roll20.
Faire une branche
Il est recommandé de créer une nouvelle branche pour chaque projet séparé (fiche de personnage ou script Mod (API)) et pour chaque mise à jour séparée. Par exemple, si tu vas mettre à jour deux scripts Mod (API) différents en même temps, crée une branche pour chaque script. Si, quelques semaines plus tard, vous décidez d'apporter des modifications supplémentaires au même script, créez une nouvelle branche pour la nouvelle mise à jour. En règle générale, créez une nouvelle branche pour chaque demande d'extraction.
L'application de bureau dispose également de l'interface la plus simple pour gérer les succursales. Dans le menu du haut, choisissez "Branche / Nouvelle branche". Lorsque vous changez de branche dans l'application de bureau (la 2ème ligne vous permet de changer le dépôt sur lequel vous travaillez, et de changer la branche courante), cela ajoutera / supprimera / modifiera les fichiers sur votre disque dur afin qu'ils correspondent au dernier commit effectué à partir de la branche vers laquelle vous avez basculé.
COMMIT vos changements et PUSH vos commits
Lorsque vous effectuez des modifications sur, vous stockez un enregistrement de tout ce que vous avez modifié ainsi qu'une description lisible par l'homme de ce que vous avez fait sur votre ordinateur local.
Vous pouvez ensuitepushvos modifications dans votre dépôt.
Une fois que vous avez cloné une copie fonctionnelle de votre référentiel, vous pouvez y apporter des modifications. Cela inclut la création d'un nouveau dossier pour ta fiche de personnage ou ton script Mod (API) et l'ajout du code source, ou la modification des fichiers déjà présents.
De nombreuses personnes, lorsqu'elles développent des scripts Roll20 ou des feuilles de personnage, effectuent toutes les modifications dans un éditeur de texte (par exemple notepad++). Vous pouvez simplement ouvrir les fichiers de votre disque dur (ceux créés lors de l'étape "cloner") dans n'importe quel éditeur de texte et effectuer les modifications dans l'éditeur. Chaque fois que vous souhaitez exécuter le code sur Roll20, appuyez sur ctrl/a et ctrl/c pour sélectionner tout le texte et le copier dans le presse-papiers. Collez-la ensuite dans le champ de campagne Roll20 approprié. Si des modifications supplémentaires sont nécessaires (par exemple pour le débogage), il est souvent plus facile d'effectuer un cycle continu d'édition, de copie, de collage et de test.
Lorsque vous commandez à l'éditeur de texte d'enregistrer vos modifications, il écrit finalement vos modifications dans le fichier que vous avez édité, et GitHub Desktop détecte que le fichier que vous avez édité a changé et affiche le nom du fichier qui a changé dans son volet gauche, et dans le volet droit affiche un résumé de ce qu'il détecte comme étant différent entre l'enregistrement actuel et le dernier commit qui a été fait. Cependant, ces changements ont seulement été détectés, GitHub ne les enregistre pas tant qu'ils n'ont pas été validés. Les experts de Git recommandent d'effectuer des livraisons fréquentes, car cela permet de disposer d'une sauvegarde hors site de votre travail et d'un enregistrement de chaque livraison.
Aucune modification ne peut être engagée sans un résumé, mais la description est facultative.
L'engagement est très simple. L'application de bureau a déjà fait tout le travail d'identification de ce qui doit être engagé. Saisissez un titre pour les modifications etoptionnellementsaisissez une description plus longue, validez la modification en appuyant sur le bouton "Valider dans (branche)". Assurez-vous de faire vos commits sur votre branche de travail, pas sur votre branche principale. Effectuer des commits fréquents vous offre un historique détaillé des modifications que vous apportez, par opposition à un seul commit avec tout une fois que vous avez terminé. Notez qu'il y a une limite de longueur pour le résumé. Cependant, si vous dépassez la limite, votre message débordera automatiquement dans la description plus longue. Vous pouvez voir cela se produire lorsque le texte dans le champ Résumé devient gris.
Dès que vous effectuez le commit, GitHub Desktop devrait afficher un grand avis indiquant qu'il n'y a pas de changements locaux. Il devrait également suggérer de pousser votre commit vers l'origine. Sinon, il pourrait suggérer de "Publier la branche". La validation de vos modifications les stocke toujours uniquement sur votre ordinateur. Pour mettre ces modifications sur GitHub, vous devez les pousser vers l'origine, le dépôt qui est stocké en ligne. Appuyez simplement sur le bouton "Pousser vers l'origine" ou "Publier la branche". Alternativement, à tout moment où l'origine et le clone ne sont pas à jour, il devrait y avoir un bouton très mal étiqueté en haut à droite avec un numéro et une flèche dessus. Cela devrait, entre autres choses intéressantes, synchroniser tout entre votre dépôt et le clone, vous pouvez donc pousser cela à la place. En haut de l'outil de bureau, l'élément du menu déroulant "Dépôt - Envoyer" fera également l'affaire.
Continuez à modifier et à effectuer des validations jusqu'à ce que vos modifications soient terminées et que vous ayez du code prêt à être soumis pour que le reste de Roll20 puisse en profiter. Vous êtes maintenant prêt à demander aux administrateurs du site Roll20 de "tirer" vos modifications dans le référentiel principal officiel de Roll20.
Créez une demande de PULL
Comme son nom l'indique, une tractionest le contraire d'une poussée. Au lieu que ce soit une copie du référentiel qui envoie des validations à l'original, c'est l'original qui demande des validations à la copie.
Sur la page web de votre référentiel, il y a un bouton vert qui indique "Comparer, examiner, créer une demande de pull request" lorsque vous passez dessus. Ce bouton vous amènera à une page où vous pourrez créer une demande de pull. Si des différences existent entre votre référentiel ("source") et la version de Roll20 du référentiel ("base"), elles seront affichées ici. (Notez que vous pouvez modifier l'élément à utiliser à la fois comme source et comme base en cliquant sur le bouton "Modifier" à proximité.) Puisque vos modifications sont toutes dans votre branche de travail, et non dans votre branche principale, vous voulez que votre demande de pull provienne de votre branche de travail.
Parce que vous n'avez pas les permissions de collaborateur sur le dépôt de Roll20, vous ne pouvez pas effectuer l'action de retrait vous-même, mais vous pouvez demanderà quelqu'un d'autre d'effectuer le retrait. Appuyez sur le gros bouton vert intitulé "Créer une demande de tirage" et une demande de tirage sera ouverte sur le référentiel de base. Les personnes qui en ont l'autorisation (c'est-à-dire les développeurs Roll20) peuvent examiner la demande de tirage ainsi que le contenu des modifications proposées, puis fusionner la demande dans le référentiel officiel.
Pour des raisons de clarté, veuillez inclure le nom de la feuille pour laquelle vous avez apporté des modifications dans la demande de tirage, par exemple. "[Dungeondivers 3rd Edition] a corrigé le jet de Force cassé".
Pour les soumissions de fiches de personnage, n'oublie pas d'inclure sheet.json et une image de prévisualisation – consulte le readme pour plus d'informations. Pour les soumissions de scripts Mod (API), n'oublie pas d'inclure script.json – consulte le readme pour plus d'informations. Si tout est correct, votre feuille ou votre script devrait être ajouté au fichierapproved.yamlet être disponible pour tous les utilisateurs !
Une fois par semaine, Roll20 traite toutes les demandes de feuille disponibles. Lorsque cela se produit, vous recevrez un e-mail de GitHub. Cet e-mail vous informera soit qu'un commentaire a été laissé sur votre demande concernant un problème rencontré avec votre soumission, soit que votre feuille a été fusionnée comme prévu et que votre demande a été close (parce qu'elle a été achevée avec succès).
Apporter des modifications à votre DEMANDE DE TIRAGE
Si vous créez une demande d'extraction et que vous faites ensuite un commit & pour ajouter des modifications à votre dépôt/branche avant que la demande d'extraction ne soit fusionnée, ces nouvelles modifications seront automatiquement mises à jour/incluses dans la demande d'extraction originale ; il n'est pas nécessaire de faire une deuxième demande d'extraction.
Nettoyage
NE SUPPRIMEZ AUCUNE BRANCHE tant que toutes les demandes de tirage (pull requests) de cette branche ne sont pas terminées et closes. En réalité, il n'y a jamais urgence à supprimer une branche. Elles ne nuisent en rien tant que vous vous souvenez de n'utiliser chaque branche qu'une seule fois.
Le logiciel GitHub vous recommandera de fusionner votre branche dans la branche principale. Ceci est une étape nécessaire avec d'autres flux de travail, mais pas dans le flux de travail de Forking que nous utilisons. Nous vous recommandons plutôt de synchroniser votre fork avec le roll20 original comme première étape pour préparer votre prochaine mise à jour. Cela apportera les mises à jour que vous venez de faire (ainsi que toutes les modifications apportées par d'autres personnes) dans votre fork.
Par conséquent, il n'y a pas de nettoyage à faire.
Plus d'informations
- Astuces sur l'utilisation de Github(fil de discussion sur le forum Roll20)
- Le flux de travail GitHub (visualisation)(pas le flux que nous utilisons, mais une bonne visualisation) etForking Workflow(ce que nous utilisons)
- Git - Le guide simple (outil en ligne de commande)par Roger Dudler
Git et Github pour les poètes Tutoriel Youtube
Vidéos de 10 à 20 minutes pour les non-techniciens qui enseignent les bases de Git et Github, montrant comment travailler avec Github dans le navigateur, mais aussi une introduction à l'utilisation de la ligne de commande. Il a été fabriqué en 2016 mais ne semble pas être daté après un rapide coup d'œil (mars 2019).
- 1.2 Branches12 min
Git et Github pour les poètes (au-delà des bases)
- 1.4 Problèmes GitHub 12 min
- 1.10 Git Distants 14 min