====== Collaborer aux sources des assets 3D du client de jeu 3D Godot ======

{{ :fr:khanat_client_3d_assets_source.png?nolink&200 |}}

Ce dépôt [[https://git.khaganat.net/khaganat/mmorpg_khanat/khanat-client-3d-assets-source|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 =====

<WRAP center round info 90%>
Créez toujours [[#gestion_des_issues|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é.
</WRAP>


==== Avoir un dépôt sur lequel travailler ===

Le dépôt git utilise le module [[https://git-lfs.github.com/|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 : [[gitlab>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.

{{:fr:fork.png}}

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 : [[gitlab>khaganat/mmorpg_khanat/khanat-client-3d-assets-source|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 ====

<WRAP center round important 60%>
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.
</WRAP>


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 [[https://fr.wikipedia.org/wiki/Snake_case|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 :

{{ :fr:godot:create_mr_from_issue.jpg?direct&500 |}} 


==== 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 ([[https://git.khaganat.net/khaganat/mmorpg_khanat/khanat-client-3d-assets-source/-/issues/6|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 [[gitlab>khaganat/mmorpg_khanat/khanat-client-3d-assets-source|système Gitlab de ce dépôt]] plutôt que sur [[taf>fr:start|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. 

<WRAP center round info 80%>

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.
</WRAP>


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 : [[gitlab>khaganat/mmorpg_khanat/khanat-client-3d-assets-source/issues|Issue sur Godot 3D client Khanat]]

Il suffit de cliquer sur : {{ :fr:new_issue2.jpg?nolink |}}

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 [[#gestion_des_milestones|ci-dessous]]) ;
  * //Labels// permet de choisir des tags pour déterminer le genre de tâche (voir [[#gestion_des_labels|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.

{{ :fr:godot:commenter.jpg?direct&500 |}}

===== 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 [[https://fr.wikipedia.org/wiki/Snake_case|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 :
<WRAP prewrap 600px>

<code json 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"
}
</code>
</WRAP>

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 [[https://spdx.org/licenses/|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''.

<WRAP center round todo 60%>
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.
</WRAP>

===== 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


{{tag>Données Godot Outils Client Graphisme 3D Blender}}