====== Collaborer à la création du client de jeu 3D Godot ======

{{ :fr:godot:godot_logo_big.png?nolink&200 |}}

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

<WRAP center round important 60%>
La mise en place des submodules est en cours, mais non encore mise en place. Si la question vous intéresse, on en parle dans [[https://port.numenaute.org/khaganat/mmorpg_khanat/khanat-client/-/issues/7|ce ticket]]  --- //[[wiki:user:yannk|YannK]] 2021/10/11 10:58//
</WRAP>

===== 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 [[https://semver.org/lang/fr/|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 : [[https://git.khaganat.net/groups/khaganat/mmorpg_khanat/-/milestones/1|Khanat Client - Release Candidate 0.1 ]]

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

<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 **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 [[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 compile les clients ([[https://git.khaganat.net/khaganat/mmorpg_khanat/khanat-client/-/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|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/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 =====

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.

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 :
<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  brouillon obsolète}}