Collaborer aux sources des assets 3D du client de jeu 3D Godot
Ce dépôt Khanat client 3D assets source sert aux modélisations 3D réalisées sous Blender, incluant les animations et les textures personnalisées des assets. Pour les textures génériques (atlas, trim sheets, decals…), un autre dépôt est utilisé.
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
Le dépôt git utilise le module Git Large File Storage pour améliorer la gestion de tous ces gros fichiers binaires. Il faut veiller à le mettre en place sur son ordinateur pour que cela fonctionne.
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-3d-assets-source. 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 : Khanat client 3D assets source.
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 main : c’est la branche qui contient les assets prêts à être intégrés au client de jeu.
- 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 les ajouts récents se trouvent, 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 exporte vers le dépôt où seront les assets sous le format utilisé par le moteur de jeu Godot (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
Veillez à utiliser les bonnes versions des logiciels, indiquées dans le README du dépôt.
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.
Pour chaque fichier d’assets, 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
