Très inspiré par et basé sur le « [Gamemakin](https://gamemak.in) UE4 Style Guide » disponible sur [GitHub](https://github.com/Allar/ue5-style-guide).
Godot propose quelques conseils sur la façon de travailler pour son propre projet dans une section [Les meilleures pratiques](https://docs.godotengine.org/fr/stable/tutorials/best_practices/index.html) ainsi qu’un [Guide de style](https://docs.godotengine.org/fr/stable/development/editor/editor_style_guide.html#editor-style-guide) et un [Bonnes pratiques pour les contributeurs au moteur](https://docs.godotengine.org/fr/stable/community/contributing/best_practices_for_engine_contributors.html) destinés à celles qui souhaitent contribuer au développement du moteur lui-même.
## Principes de base
### Un manuel vivant
Ce manuel a vocation à rendre la contribution plus efficace, Khaganat est ouvert à la discussion et possède un canal XMPP où on peut échanger sur tout cela : [https://khaganat.net/irc/](https://khaganat.net/irc/).
### Respectez la loi
Khaganat respecte la loi française et vous demande de faire de même, donc merci de ne rien introduire d’illégal dans le projet par vos actions. En particulier :
- ne réemployez pas le travail d’autrui si vous n’en avez pas reçu l’autorisation explicite
- respectez les licences d’usage des éléments que vous souhaitez copier depuis un autre projet, en particulier si l’attribution est demandée (comme avec les licences CC BY)
- avant d’y apporter des éléments externes, vérifiez-en la compatibilité avec les licences du projet Khaganat
## Terminologie
### Identifiants
Un `Identifiant` est ce qu’on appelle communément un « nom » : celui d’un objet 3D, d’un fichier de son, d’un répertoire, d’une variable ou d’un script…
#### Caractères autorisés dans les identifiants
Dans un `Identifiant`, jamais on n’utilise un de ces caractères :
* les espaces
* les barres obliques ou barres obliques inverses `\`, `/`
* des symboles du genre `#!@$%`
* des caractères Unicode
Un `Identifiant` ne doit donc comprendre que les caractères suivants :
* ABCDEFGHIJKLMNOPQRSTUVWXYZ
* abcdefghijklmnopqrstuvwxyz
* 1234567890
* _ (avec parcimonie)
Pour résumer, un `Identifiant` doit pouvoir répondre à l’expression régulière `[A-Za-z0-9_]+`)
Ces règles permettent la plus grande compatibilité entre systèmes et pays.
#### L’usage des casses
Il y a plusieurs façon d’écrire les `Identifiants`, dont voici les plus courants (dénommés par leurs désignation en anglais, conventionnelle).
##### PascalCase
On met une majuscule à chaque mot et on supprime les espaces : `Coffre avec poignees` devient `CoffreAvecPoignees`.
##### camelCase
C’est similaire au PascalCase, sauf que la première lettre du premier mot est en minuscule : `Coffre avec poignees` devient `coffreAvecPoignees`.
Plus de précisions sur [Wikipédia](https://fr.wikipedia.org/wiki/Camel_case).
##### snake_case
Les espaces sont remplacés par des underscores « _ » : `Coffre avec poignees` devient `coffre_avec_poignees`
Bien que par convention, on puisse choisir de mettre ou pas des majuscules aux mots, nous retenons l’idée de tout mettre en minuscule pour nos usages du snake_case. `Coffre avec poignees` devient donc `coffre_avec_poignees`
Plus de précisions sur [Wikipédia](https://fr.wikipedia.org/wiki/Snake_case).
Les espaces sont remplacés par des tirets (le signe moins) « - » : `Coffre avec poignees` devient `coffre-avec-poignees`.
La désignation de cette casse n’est pas définitive, *kebab-case* semblant le plus fréquent, mais lisp l’utilise aussi depuis de très nombreuses années.
Les termes `Variable` et `Propriété` sont généralement interchangeables, mais si ils sont utilisés dans le même contexte, cela signifie plus précisément :
- pour `Propriété` que cela désigne une variable dans une classe.
- pour `Variable`, cela désigne généralement un argument de fonction ou une variable locale dans une fonction. Dans une classe, cela peut indiquer un statut à préciser/ définir.
Indépendamment de leur extension, les fichiers peuvent comporter trois parties, séparées chacune de la précédente par un **underscore** : préfixe, corps et suffixe. Le préfixe et le suffixe sont déterminés par le type de fichier (son extension donc).
Sauf indication contraire, tous les éléments internes aux fichiers Blender doivent être écrits en *kebab-case*. Le recours à un préfixe ou suffixe sera indiqué le cas échéant.
Les *Objects* doivent être rassemblé dans des sous-collections pertinentes, et il faut veiller à ce que l’*Object Data qui y est associé soit nommé de façon identique.*
Les objets à destination du mùoteur de jeu Godot doivent être exportés au format glTF. Il faut pour cela sélectionner tous les objets à exporter puis aller dans `File > Export > glTF`, avec les options suivantes à vérifier particulièrement :
-`Format > glTF Embeddded`.
-`Copyright : Khaganat`.
- On peut cocher `Remember export settings` pour ne pas avoir à revérifier à chaque export de ces modèles.
- **fix** : résoud un bug qui doit être mentionné dans le pied de page avec un hashtag et son numéro de ticket (entraîne un changement de type _patch_ dans le versionnement).
- **feat** : ajoute une fonctionnalité qui doit être mentionnée dans le pied de page avec un hashtag et son numéro de ticket (entraîne un changement de type _mineur_ dans le versionnement).
- **ci** : concerne le fonctionnement de la CI du dépôt.
- **docs** : reprise de la documentation du code sans toucher aux fonctionnalités.
- **refactor** : refactorisation du code sans modifier son comportement, ajouter une fonctionnalité ou réparer un bug.
- **style** : reprise formelle du code sans en modifier le fonctionnement (typos, espacements, tabulations etc.)
Le cas échéant, il est possible d’ajouter de nouveaux types selon les besoins (se référer à [la convention Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type) par exemple).
Le type doit être écrit en minuscule, sans espace.
##### La portée
Indiquée entre parenthèses, en minuscule sans espace, elle permet de préciser éventuellement sur quel partie du code la modification porte.
Elle peut être choisie dans cette liste :
- **core** : concerne le code de base, les systèmes essentiels au fonctionnement du jeu
- **ui** : concerne l’interface utilisateur
- **shading** : concerne les shaders d’affichage
- **ia** : concerne l’intelligence artificielle des créatures en jeu
D’autres portées peuvent être ajoutées à la liste au fur et à mesure des besoins.
##### Rupture de compatibilité
Si le commit entraîne une rupture de compatibilité dans le code, le type doit se voir accoler un point d’exclamation avant les deux points, quel que soit son type (entraîne un changement de type _majeur_ dans le versionnement).Il faut alors également lui ajouter un pied de page avec la mention « BREAKING CHANGE: » suivi de la mention de l’endroit où la rupture s’opère.
##### Le sujet
Laissant une espace après les deux points, il ne comporte pas de majuscule au début ni de point à la fin.
Le sujet doit décrire en peu de mot le changement qu’opère le nouveau code.
Exemples de première ligne correcte :
feat(ui)!: change methods for IG windows, close #18
fix(core): address collision problems for player, close #37
feat: add color wheel for windows background, close #16
##### Corps de description
Facultatif, il permet de décrire de façon détaillée ce qui a motivé les choix opérés et mettre l’emphase sur les améliorations espérées par rapport à l’ancien état.
##### Pied de page
Il peut comporter deux éléments :
- si le commit clôt un ticket, il faut indiquersur une ligne son numéro de la façon suivante : `« Close #58 »`
- si le commit entraîne une rupture de compatibilité, il doit comporter une ligne avec la mention « BREAKING CHANGES » en majuscules.
Il n’est pas utile de versionner le répertoire `.import/` situé à la racine d’un projet car son contenu peut être généré depuis les fichiers originaux et leur fichier de configuration annexe (avec l’extension `.import`, par exemple pour `icone.png` cela donne `icone.png.import`). Il convient donc d’ajouter le répertoire `.import/` dans le `.gitignore` comme c’est proposé dans [la documentation Godot](https://docs.godotengine.org/en/latest/tutorials/assets_pipeline/import_process.html#files-generated).
