Table des matières
Collaborer à la création du client de jeu 3D Godot
Ce dépôt Khanat client sert à développer la partie client 3D du jeu, en se basant sur le logiciel Godot. Il contient des submodules git pour gérer certains apports, comme les assets.
Chronologie
Nous n'obtiendrons pas un client complet au premier jet. Nous proposons donc un succession de versions, chacune ajoutant de nouvelles fonctionnalités itérativement à la précédente.
Chaque version est numérotée x.y.z (voir la gestion sémantique de version).
- x = version majeure. On le change quand les changements ne sont pas rétrocompatibles
- y = version mineure. L’incrémentation se fait lorsqu’un ensemble de nouvelles fonctionnalités défini a été intégré, la compatibilité doit être maintenue, sauf dans le cas où la version majeure est en 0, car de nombreux changements peuvent être nécessaires avant de passer à la version 1.0.
- z = version corrective. Incrémentée lorsque des correctifs de bugs sont ajoutés à une version mineure, sans ajout de nouvelle fonctionnalité.
Versions
Version 0.1
Le but de la 0.1 est d’avoir un client local qui permette de déplacer le personnage dans un environnement minimaliste extérieur statique, avec un résultat visuel sobre mais attrayant, présentant des spécificités du monde du Khanat et simple techniquement afin de tester les outils et processus de collaboration.
Ce sera l’occasion de mettre en place un sous-dépôt pour les assets glTF et de mettre en place une automatisation pour compiler les clients à fournir aux joueuses.
Aucune fonctionnalité via un serveur n’aura à être implémentée.
Lien vers le suivi des Tickets/Issues sur la forge : Khanat Client - Release Candidate 0.1
Le workflow de travail
Créez toujours une Issue/ un Ticket avant de créer une branche qui n'y est pas référencée.
Cela permet de suivre le travail en vérifiant si une branche Git avec ce numéro existe, de façon à éviter de refaire du travail déjà commencé.
Avoir un dépôt sur lequel travailler
Mise en place d'un dépôt personnel (fork)
Pour commencer, il vous faudra forker le dépôt principal : khaganat/mmorpg_khanat/khanat-client. Ainsi, vous aurez votre propre dépôt, sur lequel vous pourrez effectuer vos modification sans interférer avec le dépôt principal.
Pour cela, il vous suffit de clique sur le bouton suivant sur la page d’accueil du projet.
Vous serrez alors redirigé vers votre copie du dépôt.
Travailler directement sur le dépôt principal
Si vous êtes un développeur « officiel » chez nous, vous aurez accès au dépôt principal sur notre GitLab : Client Godot 3D Khanat.
Vous n'aurez pas à créer un dépôt personnel (sauf si vous en avez envie) pour pouvoir contribuer, il vous suffira de travailler sur des branches en interne.
Le dépôt et ses branches
Si vous n’avez pas accès en tant que développeur à notre dépôt officiel et travaillez depuis votre fork, merci de nous confirmer que la procédure fonctionne bien pour vous.
Khanat utilise un workflow simplifié. Les branches principales sont :
- Branche stable : c’est la branche qui contient le code qui est compilé pour fournir le client de jeu en cours.
- Branche XXX_titre_du_ticket : Branche contenant le développement d’un ticket (voir ci-dessous) XXX, en cours de travail.
- Branche develop : Branche par défaut sur laquelle le code récent se trouve, qui est celle qui vise à contenir les tâches des tickets définis pour le Milestone en cours.
Les branches de module, que ce soit sur votre fork ou sur les dépôts officiels, doivent être nommées de la façon suivante :
- Branche Module : Doit être nommée “[numéro_du_ticket]_[titre du ticket en snake case]”
- Exemple : pour travailler sur le ticket numéro 2 titré « Faire une des tâches détaillée de la tâche globale XXX », il faut créer une branche « 2-faire-une-des-taches-detaillee-de-la-tache-globale-xxx »
Si vous êtes développeur officiel chez nous, vous pourrez créer automatiquement la branche et la merge request depuis l’issue en cliquant sur le bouton prévu :
Travail sur un ticket
Si vous travaillez depuis un fork, vous devez créer une Merge Request, à destination de develop sur notre dépôt. Cette requête doit respecter ces impératifs :
- elle doit avoir comme titre « Draft: Resolve “titre du ticket” », donc, dans notre exemple, ce serait « Draft: Resolve “Faire une des tâches détaillée de la tâche globale XXX” »
- elle doit comporter en première ligne de sa description une commande pour fermer le ticket correspondant. Dans notre cas, ce serait « Closes #2 ».
Merge sur la branche « stable »
Une fois que l’ensemble des Tickets/Issues d’un Milestone a été résolu et que le client a atteint le point où il semble suffisamment achevé et stable, on peut le passer sur la branche « stable ».
Il est indispensable de bien vérifier le changelog à ce moment là, selon le modèle de [keepachangelog.com](https://keepachangelog.com/en/1.0.0/). Un changelog permet d'avoir une idée claire de ce qui est possible/implémenté pour les tests du client.
Lors du commit de merge, il faudra passer une commande pour que la CI de Gitlab compile les clients (Ticket correspondant sur la forge).
Gestion des Merge Request
Il ne faut pas hésiter à laisser des commentaires sur la demande de Merge Request, cette page est là pour expliquer les soucis, détailler l’approche etc. Cela permet de s’assurer que les solutions retenues sont pertinentes pour les autres contributrices et de faciliter l’intégration finale.
Lors de la validation de la Merge Request, on efface la branche de travail et on ne squashe pas les commits.
Dans la mesure du possible, on ne merge jamais soi-même directement.
Gestion des Tickets / Issues
Créez les demandes de fonctionnalités ou les erreurs sur le système Gitlab de ce dépôt plutôt que sur la base TAF (qui sert surtout aux aspects non-techniques du projet Khaganat). Il n’y a pas d’impératif d’utiliser l’anglais comme dans les commits et les commentaires du code, mais il est possible de l’utiliser, selon les personnes avec qui vous pensez collaborer. L'idéal serait d'utiliser l'anglais et le français dans vos tickets, mais vu la surcharge de travail que cela entraîne, ce n’est pas du tout obligatoire.
Avant de commencer une tâche qui n’existe pas, créez une Issue que vous vous attribuez, comme ça on sait que quelqu'un a commencé à travailler sur ce sujet.
Les travaux à faire, modifications de fichier, créations, doivent être indiqués en se servant du système d'Issues de ce dépôt : Issue sur Godot 3D client Khanat
Il suffit de cliquer sur : 
Vous renseignez ensuite les différents champs.
Le titre doit être concis et le plus explicite possible.
Par contre, n'hésitez pas à être le plus précis possible dans la zone Description.
Il y a ensuite quelques zones de champs à renseigner :
- Milestone qui désigne la version du projet pour laquelle ce travail devra être fait (voir ci-dessous) ;
- Labels permet de choisir des tags pour déterminer le genre de tâche (voir ci-dessous) ;
Dans le doute, n'indiquez rien dans ces champs. De toute façon, tout est éditable a posteriori donc ce n'est pas grave si vous faites des erreurs ou n'êtes pas assez précis.
Gestion des messages dans les Tickets / Issues
Pour chaque ticket, il est possible de laisser des messages. Chacun d’eux initie un fil de discussion auquel on peut répondre en cliquant sur l’icône de bulle dans son coin supérieur droit. Cela permet de conserver des fils thématiques sur des sujets abordés par le ticket.
Gestion des dossiers et des fichiers
Les noms des dossiers et des fichiers sont écrits en snake_case.
Les commentaires dans le code/les scripts se font en anglais, de façon à ce que le code soit international.
Si vous ajoutez des fichiers d’assets (sons, images, modèle 3D…), il faut impérativement y adjoindre un fichier .json de même nom, qui comportera le suivi des contributions, de façon à permettre de tracer la paternité des contributions. SI il existe déjà et que vous faites une modification au fichier d’asset, ajoutez juste votre nom.
La structure du fichier est la suivante :
- myasset.svg.json
{ "contributors": [{ "name" : "John Smith", "email" : "john@johnsmith.com", "url" : "http://johnsmith.com" }, { "name" : "Jane Smith", "email" : "jane@janesmith.com", "url" : "http://janesmith.com" }], "license" : "CC-BY-SA-4.0" }
Description :
- contributors :
- indiquer le nom/le pseudonyme (obligatoire), le courriel (facultatif) et une url de référence (facultatif) pour chaque contributeur à ce fichier
- licence :
- indiquer la licence appliquée aux fichiers de ce répertoire, pour uniformiser les références, utiliser les codes spdx, ce sera par défaut “CC-BY-SA-4.0” (ou AGPL-3.0-or-later si ce sont des scripts/codes), mais cela peut être une licence plus permissive compatible.
N'oubliez pas de nommer le json du même nom que votre asset, extension comprise ! Cela veut dire que si vous faites un pendo.png, le fichier json associé sera pendo.png.json.
Le nommage des assets devra obéir à une certaine nomenclature sur les dépôts officiels, afin d'éviter les doublons dans les noms. Cette nomenclature reste à définir.
Gestion des Commits
On rédige ses commits en anglais, de façon à ce que le code soit international (même si c’est du franglais, aucune importance). Ne pas hésiter à remettre dans chaque message de Commit le numéro de ticket correspondant, cela peut aider à comprendre certains choix à l’avenir.
Gestion des Milestones
On se servira des milestones définies par le cahier des charges du client : https://git.khaganat.net/groups/khaganat/mmorpg_khanat/-/milestones.
Gestion des Tags
Nous n'utilisons pas de Tags sur ce dépôt Git pour le moment.
Gestion des Labels
La liste des Labels/Étiquettes est gérées au niveau du groupe Gitlab : https://git.khaganat.net/groups/khaganat/mmorpg_khanat/-/labels