|
| 1 | +# Lignes de bonne conduite du contributeur (WIP) |
| 2 | + |
| 3 | + |
| 4 | +## Le JSON c'est quoi ? |
| 5 | + |
| 6 | +Documentation sur le JSON : https://developer.mozilla.org/fr/docs/Learn/JavaScript/Objects/JSON |
| 7 | + |
| 8 | +Outil en ligne pour valider le format de votre json : https://jsonformatter.curiousconcept.com \ |
| 9 | +Pour les utilisateurs de Notepad++ : https://github.com/molsonkiko/JsonToolsNppPlugin |
| 10 | + |
| 11 | + |
| 12 | +## Les fichiers de traduction |
| 13 | + |
| 14 | +Chaque language possède son propre fichier de traduction : |
| 15 | +- `mods.json` est la version référence |
| 16 | +- `mods_xx.json` est la version utilisée par la langue de code `xx` |
| 17 | + |
| 18 | +### Le contenu source |
| 19 | + |
| 20 | +Chaque champ non rempli dans `mods_xx.json` sera remplacé par le contenu du fichier `mods_en.json`.\ |
| 21 | +Après cette étape, si certains champs demeurent non renseignés, ils seront remplacés par le contenu du fichier `mods.json`.\ |
| 22 | +Ce contenu est appelé contenu `source`. |
| 23 | + |
| 24 | +### Les champs meta |
| 25 | + |
| 26 | +Les fichiers de traduction possèdent des champs supplémentaires suffixés par `_meta`.\ |
| 27 | +Comme `description_meta`. Qui est associé au champ `description`.\ |
| 28 | +Il contient des informations supplémentaires utiles à la traduction pour le champ associé.\ |
| 29 | +Son contenu est généré **automatiquement** et sera donc écrasé si nécessaire. |
| 30 | + |
| 31 | +#### Statuts |
| 32 | + |
| 33 | +Le champ `status` des champs `_meta` peut contenir trois valeurs : |
| 34 | +- `"done"` : la traduction a été relue ou aucune traduction n'est nécessaire |
| 35 | +- `"needs_review"` : la traduction a été réalisée mais nécessite une relecture |
| 36 | +- `"todo"` : la traduction n'a pas été réalisée |
| 37 | + |
| 38 | +#### Source |
| 39 | + |
| 40 | +Le champ `source` des champs `_meta` contient la dernière version connue de la source.\ |
| 41 | +Si le contenu de la source venait à être modifié, alors une différence entre les deux champs sera détectée.\ |
| 42 | +Une traduction réalisée de statut `"done"`, et dont la source change passera au statut `"needs_review"`.\ |
| 43 | +Une traduction vide de statut `"done"`, et dont la source change passera au statut `"todo"`. |
| 44 | + |
| 45 | + |
| 46 | +### urls_extra |
| 47 | + |
| 48 | +Si ce champ est renseigné, son contenu est ajouté au champ `urls` du mod pour la langue concernée.\ |
| 49 | +Cela permet d'ajouter des liens non officiels, comme une traduction pas encore acceptée par l'auteur par exemple.\ |
| 50 | +Cela, sans surcharger les urls de toutes les langues. |
| 51 | + |
| 52 | + |
| 53 | +### notes_extra |
| 54 | + |
| 55 | +Dans la même veine que `urls_extra`, une note spécifique à la langue est ajoutée aux notes du mod. |
| 56 | + |
| 57 | + |
| 58 | +## Le fichier .ini |
| 59 | + |
| 60 | +Parfois, les mods possèdent un fichier `.ini`. Plus d'informations [ici](https://www.gibberlings3.net/forums/topic/32516-tutorial-what-is-label-why-you-should-create-it-and-how-to-do-it-properly/).\ |
| 61 | +Les données contenues dans ce fichier sont considérées comme les plus fiables, on y trouve entre autre : |
| 62 | +- `Name` : le nom du mod |
| 63 | +- `Author` : le nom de l'auteur |
| 64 | +- `Description` : la description (succinte) du mod |
| 65 | +- `HomePage` : url de présentation du mod |
| 66 | + |
| 67 | +En tant que contributeur, il est conseillé de l'utiliser autant que possible.\ |
| 68 | +En tant que moddeur, il est encouragé de le remplir. |
| 69 | + |
| 70 | + |
| 71 | +## name |
| 72 | + |
| 73 | +Le nom du mod.\ |
| 74 | +Cette donnée n'est pas aussi simple qu'elle n'y paraît : le nom est variable selon la source.\ |
| 75 | +Souvent le nom du post diffère de celui du repo.\ |
| 76 | +En cas de fichier `.ini`, on prend celui qui est renseigné dedans.\ |
| 77 | +Sinon, on peut se baser sur le nom du sujet de présentation du mod ou du titre dans le readme du mod.\ |
| 78 | +On préviligiera les noms courts. En évitant les rallonges qui indiquent les compatibilités du mod (le champ `games` permet déjà de renseigner cette information).\ |
| 79 | +Deux mods ne peuvent avoir le même nom. Cependant, il peut exister deux versions d'un même mod pour deux jeux. Dans ce cas, on peut préciser le nom du jeu entre parenthèse pour les différencier.\ |
| 80 | +Exemple : `Dragonspear UI++` et `Dragonspear UI++ (IWDEE)`. |
| 81 | + |
| 82 | + |
| 83 | +## description |
| 84 | + |
| 85 | +La description du mod.\ |
| 86 | +C'est un "teaser", la description ne doit pas être complète mais donner envie au lecteur de cliquer sur le lien pour en savoir plus.\ |
| 87 | +Conseils : |
| 88 | +- Les informations doivent être stables, on évite : |
| 89 | + - les commentaires personnels : `cet auteur est génial` |
| 90 | + - les dates fixes : `ce mod existe depuis 3 ans` |
| 91 | + - toute information périssable : `ce mod activement maintenu` |
| 92 | +- Si des informations sont à la fois à éviter et pertinentes, elles peuvent être renseignées dans le champ `notes`. |
| 93 | +- Les balises html sont fonctionnelles dans la description, cela n'est pas cependant pas conseillé. |
| 94 | + |
| 95 | + |
| 96 | +### Aides pour se simplifier la vie |
| 97 | +- `|` : le pipe, il permet de revenir à la ligne (le saut de ligne n'étant pas autorisé dans le json) |
| 98 | +- \`\` : le backtick (l'accent grave), il permet de mettre en `surbrillance un bout de phrase` |
| 99 | +- `[[ ]]` : le lien interne, il n'est pas rare qu'un mod parle d'un autre mod, on rajoute un lien : [[id du mod]] |
| 100 | +- `[]()` : le lien externe, comme avec les fichiers .md, `[description du lien](url)` |
| 101 | + |
| 102 | +## notes |
| 103 | + |
| 104 | +Les notes du mod écrites par les contributeurs pour compléter la description du mod.\ |
| 105 | +- On y met : |
| 106 | + - Des conseils sur l'installation |
| 107 | + - Les incompatibilités éventuelles |
| 108 | + - Les points d'attention variés |
| 109 | +- On évite : |
| 110 | + - Les jugements de valeur : `le travail de cet auteur laisse à désirer` |
| 111 | +- On remplacera : |
| 112 | + - `ce mod existe depuis 3 ans` → `ce mod existe depuis 2017` |
| 113 | + - `Attention le troisième composant n'est pas compatible avec YY` → `Attention le composant XX n'est pas compatible avec YY` |
| 114 | + |
| 115 | + |
| 116 | +⚠️ Certaines notes sont automatiques.\ |
| 117 | +On trouvera le code dans `Mod.get_auto_notes` dans `models/mods.py`.\ |
| 118 | +En voici un résumé des notes automatiques qui ne sont donc **PAS** à ajouter : |
| 119 | +- Noms des traducteurs |
| 120 | +- `Ce mod n'est disponible qu'en {langue}.` |
| 121 | +- Mods EE qui datent d'avant la version 2.0 : `⚠️ EE : La dernière mise à jour date de {year}. Ce mod pourrait ne pas fonctionner avec la dernière version du jeu.` |
| 122 | +- Mod non WeiDU (tp2="non-weidu") : `⚠️ WeiDU : Ce mod écrase les fichiers et ne peut être désinstallé. Installez-le à vos risques et périls.` |
| 123 | +- Mod archivé (status="archived") : `Ce mod a été archivé par son auteur/mainteneur qui ne semble pas vouloir lui donner suite.` |
| 124 | +- Mod disparu (status="missing") : `Ce mod a disparu.` |
| 125 | + |
| 126 | +Les `aides` du champ `description` sont fonctionnelles dans les notes. |
| 127 | + |
| 128 | + |
| 129 | +## safe |
| 130 | + |
| 131 | +Ce champ renseigne sur la qualité du mod en général. Les valeurs possibles vont de 0 à 2. |
| 132 | + |
| 133 | + 2 : 🟢 Mod de qualité |
| 134 | + 1 : ⚠️ Mod pouvant poser des problèmes |
| 135 | + 0 : 🟥 Mod à éviter ou obsolète |
| 136 | + |
| 137 | +À titre informatif, voici quelques règles utilisées : |
| 138 | +* Ce qui met automatiquement la note à **0** |
| 139 | + * Le mod est intégré dans un autre mod plus à jour : `status="embed"` |
| 140 | + * Le mod est considéré comme obsolète : `status="obsolete"` |
| 141 | +* Ce qui diminue la note de **1** point : |
| 142 | + * Le mod est compatible EE mais pas mis à jour depuis la version 2.0 (Avril 2016) |
| 143 | + * Le mod est compatible EE, de la catégorie `Interface` mais pas mis à jour depuis Avril 2021 |
| 144 | + * Le mod n'est pas weidu : `tp2="non-weidu"` |
| 145 | + * Le mod est archivé (et donc plus maintenu) : `status="archived"` |
| 146 | +* Ce qui **limite** la note à 1 point (c'est-à-dire qu'ils valent 0 ou 1) |
| 147 | + * Le mod est en cours de création : `status="wip"` |
| 148 | + * Le mod a disparu : `status="missing"` |
| 149 | + |
| 150 | + |
| 151 | +Les effets sont cumulatifs.\ |
| 152 | +Un mod dont le lien a disparu et qui n'est pas WeiDU vaut 0. |
| 153 | + |
| 154 | +## urls |
| 155 | +Les urls permettent de renvoyer le lecteur vers un complément d'information mais aussi vers le mod.\ |
| 156 | +Idéalement, deux liens sont présents : |
| 157 | +1. Le premier vers la description officielle du mod faite par l'auteur, souvent il s'agit d'une discussion de forum où l'on peut également trouver les retours des utilisateurs, des bugs éventuels… tout un tas d'informations utiles. |
| 158 | +2. Le second pointe vers le mod a proprement parlé, on privilégiera ici les liens vers des repo git |
| 159 | + |
| 160 | + |
| 161 | +### Fiabilité de la donnée |
| 162 | + |
| 163 | +Si le mod contient un fichier .ini, on préviligie la `HomePage` comme lien n°1. |
| 164 | + |
| 165 | +### Sécurité |
| 166 | + |
| 167 | +La totalité des liens sont des liens **externes**, cela implique que l'on ne sait **pas** ce qu'il y a derrière.\ |
| 168 | +Ainsi, la facilité ne doit **PAS** primer sur la sécurité. |
| 169 | + |
| 170 | +#### https |
| 171 | + |
| 172 | +Dans la mesure du possible, le **https** doit être proposé.\ |
| 173 | +Si un lien est en **http**, essayez d'accéder à la page en **https**. Si cela fonctionne, renseignez le lien https.\ |
| 174 | +Certains sites n'acceptent pas ce protocole, dans ce cas c'est toléré. |
| 175 | + |
| 176 | + |
| 177 | +#### Pas de téléchargement direct |
| 178 | + |
| 179 | +Comme on ne peut pas assurer du contenu de l'objet téléchargé, le mieux c'est encore de ne rien télécharger. On redirige le lecteur vers la page qui permet le téléchargement, mais la charge lui revient de cliquer (ou pas) sur le lien au sein de la page. |
| 180 | + |
| 181 | + |
| 182 | +#### Viser un message spécifique dans une discussion |
| 183 | + |
| 184 | +Parfois, un mod se situe au beau milieu d'une discussion. Dans la mesure du possible, ciblez le message en question dans l'url. |
| 185 | + |
| 186 | +#### Viser la page d'accueil plutôt que le blob/plop/release/ |
| 187 | + |
| 188 | +Cela concerne notamment les liens github.\ |
| 189 | +La description du mod ne sera jamais suffisante et ne sera peut-être pas à jour. Il faut autant que possible, rediriger vers la page d'accueil avec le README, le code et la visualisation sur les releases etc… Cela donne un contexte bien plus pertinent que la page avec juste un lien de téléchargement. |
| 190 | + |
| 191 | +Cas particulier pour le forum **beamdog** : on retirera la fin de l'url qui n'est pas maintenable et complique les comparaisons, par exemple :\ |
| 192 | +https://forums.beamdog.com/discussion/63741/ \ |
| 193 | +plutôt que\ |
| 194 | +https://forums.beamdog.com/discussion/63741/plip-plop-plup/ |
| 195 | + |
| 196 | + |
| 197 | + |
| 198 | + |
| 199 | +## categories |
| 200 | + |
| 201 | +Les catégories d'appartenance du mod.\ |
| 202 | +Plusieurs catégories peuvent être choisies. |
| 203 | + |
| 204 | + |
| 205 | +`PNJ One Day` est une catégorie qui répond à des spécifités particulières. Les One Day n'ont plus la côte. Le choix a été fait de lever ces restrictions. Dans cette catégorie, on trouvera les "vrais" One Day mais aussi les personnages avec peu de contenu, notamment en terme de banters. |
| 206 | + |
| 207 | + |
| 208 | + |
| 209 | +Certaines catégories s'entrecroisent, on évitera de toutes les renseigner.\ |
| 210 | +Quelques exemples : |
| 211 | +- Un mod d'`Interface` est souvent également `Cosmétique`. `Cosmétique` étant plus générique, on ne précisera que `Interface`. |
| 212 | +- Un mod peut ajouter un `PNJ recrutable` et rendre le `Kit` du personnage disponible pour le PJ. On garde `PNJ recutable` car c'est l'objectif du mod. De plus, on ne veut pas de description d'un personnage dans la catégorie `Kit`. |
| 213 | +- Un pack de `Sort et objet` peut être vendu chez des `Forgeron et marchand`. Pas de solution miracle. La description présente-t-elle les objets ou le marchand ? Si la réponse n'est pas évidente, il n'est pas interdit de mettre les deux catégories. |
| 214 | + |
| 215 | + |
| 216 | +## last_update |
| 217 | +Cette date au format `YYYY-MM` (ou `%Y-%m`) contient la date de la dernière mise à jour du mod.\ |
| 218 | +La date doit être comprise entre le 1er Janvier 1999 et la date d'aujourd'hui. |
| 219 | + |
| 220 | + |
| 221 | +## compatibilities |
| 222 | + |
| 223 | +Renseigne les dépendances fortes entre les mods.\ |
| 224 | +Deux champs sont actuellement disponibles : |
| 225 | +1. `incompatible_with` : les mods dont l'incompatibilité est connue |
| 226 | +1. `requires` : les mods requis pour l'installation du mod concerné |
| 227 | + |
| 228 | +Les champs attendent une liste : `[]`.\ |
| 229 | +Soit on renseigne l'`ID` (un entier) du mod, le nom du mod sera affiché avec un lien pour y accéder.\ |
| 230 | +Soit on renseigne une chaîne de caractère, elle sera affichée telle quelle. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments