API:Client code/Gold standard/fr

Les bibliothèques clientes de l'API action disponibles dans permettent aux développeurs d'interagir facilement et intuitivement avec l'API de MediaWiki. Les bibliothèques listées actuellement varient largement de par leurs possibilités, leur état de maintenance, et la qualité de leur code ou de leur documentation. Pour que les nouveaux utilisateurs puissent trouver plus facilement une bibliothèque qui réponde à leurs besoins, nous introduisons des « règles d'or » qui identifient particulièrement les bibliothèques de haute qualité maintenues régulièrement. Nous espérons également que les règles aideront les développeurs de bibliothèques à décider de la manière de focaliser leurs efforts pour que le code qu'ils écrive soit facilement utilisable par les experts mais aussi par les débutants.

On considère qu'une bonne bibliothèque cliente doit être facile à installer, à comprendre, à utiliser, à déboguer et aussi à améliorer. De même, une documentation accessible est aussi importante qu'un code élégant. Sauf indication contraire, les sujets ci-dessous suivent les règles d'or - du moins ils essaient. Les éléments marqués « règle de platine » indiquent que les développeurs de la bibliothèque - ainsi que ses mainteneurs - ont dépassé l'exigence des règles d'or en fournissant une bibliothèque exceptionnelle.



Facile à installer

 * Les instructions d'installation sont correctes et faciles à trouver
 * La bibliothèque est préparée pour être installée en utilisant une bibliothèque appropriée pour la génération des paquets (PyPI, CPAN, npm, Maven, rubygems, etc.)
 * Règle de platine : la bibliothèque est archivée dans un paquet dédié et disponible pour les distributions Linux



Facile à comprendre

 * Bien conçu : réalise tous les appels attendus à l'API avec le niveau d'abstraction souhaité et sans redondance
 * Règle de platine : rend disponible l' API Wikidata
 * Bien documenté :
 * Le code est commenté et lisible
 * La documentation est assimilable, actuelle et facile à trouver
 * La documentation indique les versions de MediaWiki avec lesquelles la bibliothèque est compatible
 * Les fonctions obsolètes sont clairement marquées en tant que telles
 * Règle de platine : la documentation est compréhensible par un programmeur débutant
 * Le code utilise les termes spécifiques du langage dans lequel la bibliothèque a été écrite



Facile à utiliser

 * Possède des exemples fonctionnels de code, simples, et bien écrits pour les tâches communes
 * Explique les requêtes
 * Explique les modifications
 * Gère les difficultés et les particularités de l'API afin que l'utilisateur n'ait pas à :
 * Connexion/Déconnexion
 * Cookies
 * Jetons
 * Les requêtes subséquentes utilisent le nouveau continue et non plus le query-continue
 * Fait les demandes https, avec la validation du certificat
 * Courteous API usage is promoted through code samples and smart defaults
 * la compression gzip est utilisée par défaut
 * Les exemples montrent comment créer et utiliser un entête significatif d'agent utilisateur (comme dans les règles de l'agent utilisateur)
 * Règle de platine : génère une chaîne unique pour l'agent utilisateur en fonction des nom, courriel et emplacement du dépôt
 * Utiliser efficacement les appels à l'API
 * Peut être utilisé avec la dernière version la plus stable du langage dans lequel elle est écrite (par exemple compatible Python 3)



Facile à déboguer

 * Contient les tests unitaires des fonctions de la bibliothèque les plus longues et les plus souvent modifiées
 * Règle de platine : des tests unitaires maintenus existent pour les différents chemins du code
 * Les attaques terribles ou les possibilités d'une extrême ingéniosité sont clairement indiquées dans les commentaires
 * La documentation pointe vers les sections ou les sous-pages de la documentation de l'API



Facile à améliorer

 * Library maintainers are responsive and courteous, and foster a thoughtful and inclusive community of developers and users
 * Règle de platine : le projet définit clairement la conduite attendue pour les espaces dans lesquels existent des interactions relatives au projet (liste de diffusion, IRC, dépôt, suivi des problèmes). Il doit :
 * Décrire les attitudes et les comportements souhaités
 * Fournit des exemples de comportement et de harcèlement non souhaités
 * Indique comment ces événements seront défendus
 * Les demandes de retrait sont soit acceptées soit rejetées avec un motif dans un délai de 3 semaines (Règle de platine : 3 jours de bureaux)
 * Les problèmes et les bogues sont en général répondus en 3 semaines (Règle de platine : en 3 jours de bureaux) (mais pas forcément corrigés)
 * La bibliothèque est mise à jour avec une nouvelle version en 3 semaines (Règle de platine : en 3 jours de bureaux) lorsque les modifications introduisent des ruptures dans l'API
 * Règle de platine : les mainteneurs des bibliothèques contactent les mainteneurs de l'API MediaWiki en faisant remonter leurs commentaires sur l'architecture et les fonctions de l'API
 * La bibliothèque indique sous quelle licence elle est diffusée