API:Client code/Règles d'or

Les bibliothèques clientes de l'API action disponibles dans API:code client 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 et 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 à se décider sur la manière de focaliser leurs efforts pour que le code qu'ils écrivent 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é les exigences voulues par les 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çue : elle 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ée :
  • 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

• Elle possède des exemples fonctionnels de code, simples, et bien écrits pour les tâches communes
  • Elle explique les requêtes
  • Elle explique les modifications
• Elle gère les difficultés et les particularités de l'API afin que l'utilisateur n'ait pas à traiter les :
  • Connexion/Déconnexion
  • Cookies
  • Jetons
  • Les requêtes subséquentes utilisent le nouveau continue et non plus le query-continue
  • Elle fait les demandes https, avec la validation du certificat
• L'Utilisation courtoise de l'API est promue via les exemples de code et les valeurs par défaut judicieusement choisies.
  • 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 : elle génère une chaîne unique pour l'agent utilisateur en fonction des nom, courriel et emplacement du dépôt
  • Elle utilise efficacement les appels à l'API
• Elle peut être utilisée avec la dernière version la plus stable du langage dans lequel elle est écrite (par exemple compatible Python 3)

Facile à déboguer

• Elle 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

• Les mainteneurs de la bibliothèque sont réactifs et courtois, et développent une communauté réfléchie et inclusive de développeurs et d'utilisateurs
• 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
  • Fournir des exemples de comportement et de harcèlement non souhaités
  • Indiquer 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