projet global moja

Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.

Résumé du projet

Organisation Open Source:

moja global

Rédacteur technique:

Tlazypanda

Nom du projet:

Documentation du guide d'intégration technique pour FLINT

Durée du projet:

Durée standard (3 mois)

Project description

Documentation du guide d'intégration technique pour FLINT afin de guider les nouveaux contributeurs tout au long de la procédure d'intégration technique afin que les nouveaux contributeurs puissent facilement commencer avec un soutien minimal de la part des responsables.

Problèmes liés au projet

Voici une liste des problèmes les plus critiques liés à la documentation actuelle : - Informations désorganisées dans les instructions du guide de configuration local, ce qui complique la tâche pour un nouveau contributeur. - Plusieurs dépôts de FLINT n'ont pas de documentation sur leur fonction et ne sont pas liés les uns aux autres, ce qui complique l'identification du dépôt à installer pour le nouvel utilisateur. - L'installation sous Windows est bien documentée, mais la documentation d'installation basée sur Linux peut être améliorée. - Le workflow Git ne fait pas partie de la documentation pour le moment.

Solution proposée

Cette proposition constitue une solution pour guider les nouveaux contributeurs à travers un processus d'intégration technique, afin qu'ils puissent se lancer facilement avec un soutien minimal de la part des responsables. Pour ce faire, vous pouvez refactoriser la documentation actuelle afin qu'elle soit adaptée aux débutants et gérer un dépôt autonome central pour toute la documentation disponible. Le projet se décompose en trois phases:- - Examen de la documentation existante et refactorisation: l'objectif de cette phase est de revoir le guide actuel et de le refactoriser de manière à le rendre concis et facilement compréhensible par les nouveaux contributeurs. La documentation doit également être modifiée afin de la rendre plus accessible aux débutants en y ajoutant des badges, des emoji et des informations sur les problèmes signalés par des tags indiquant un premier problème aux nouveaux joueurs ou des tags indiquant un bon premier problème. - Créer un référentiel central et autonome: l'objectif de cette phase est de relier toute la documentation disponible dans un ordre logique et séquentiel à un référentiel autonome. Cela implique de commander les directives de contribution, les instructions de configuration du projet et les guides par étapes. - Ajouter le flux de travail du développeur et le site Web de la communauté pour les nouveaux développeurs: l'objectif de cette phase est d'ajouter le flux de travail du développeur qui contient les directives de contribution Git, l'architecture technologique du projet, ainsi que les directives de test et de contrôle qualité. Il s'agira d'une application monopage présentant le flux de travail, les nouveaux problèmes qui peuvent être revendiqués par les nouveaux contributeurs et la liste de tous les contributeurs. Phase 1 : Examiner la documentation existante et la refactorisation

Modifiez la documentation actuelle pour les dépôts suivants : - FLINT: la documentation actuelle n'est pas très détaillée et ne fournit pas un ordre séquentiel des bibliothèques préalables requises. Les guides d'instructions détaillés sont divisés en différents fichiers PDF, mais peuvent être unifiés en un seul endroit de manière plus concise. De plus, les guides d'installation sont conçus pour Windows, mais pour une installation de Linux, il peut être utile de rediriger vers le dépôt FLINT.docker. - FLINT.docker: la documentation actuelle ne précise pas l'objectif de ce dépôt, qui consiste à fournir l'installation Linux de FLINT via docker. La prise en charge via Docker est limitée à Ubuntu 18.04 (Bionic Beaver), mais elle peut être étendue à d'autres distributions Linux. La documentation actuelle doit également mettre l'accent sur la manière séquentielle de configurer les fichiers Dockerfile et fournir suffisamment d'informations sur la manière de compiler à partir du fichier makefile. - FLINT.example: la documentation actuelle ne précise pas l'objectif de ce référentiel, car il fournit un exemple d'utilisation de FLINT. Vous pouvez mieux séparer les différents exemples d'exécution à l'aide d'instructions spécifiques à exécuter. Nous devons également lier ce dépôt à notre dépôt FLINT principal pour permettre aux utilisateurs de naviguer ici afin de découvrir l'exemple en action.

Les informations suivantes doivent être ajoutées à la documentation actuelle : - Utilisation de Git et GitHub: elle comprend des instructions détaillées sur la duplication, le clonage et la configuration du dépôt distant en amont. Il fournit également des informations sur la façon de redéfinir la base du dernier maître et de gérer les conflits de fusion. - Badges et emoji: la documentation actuelle ne comporte pas de badges ni d'emoji. Les nouveaux contributeurs peuvent se sentir les bienvenus et résoudre les problèmes plus facilement. - Informations sur les problèmes pour débutants/primes pour débutants: cela permettra de rediriger les nouveaux contributeurs vers les problèmes pour débutants et vers le site Web de la communauté. - Informations sur le dépôt Import-me: le dépôt Import-me sert de modèle de référence pour démarrer n'importe quel dépôt Moja Global. La documentation actuelle ne mentionne pas leur importance. Il doit être mis à jour pour mentionner le dépôt Import-me et les étapes permettant de le choisir comme modèle lors de la création d'un nouveau référentiel doivent également être ajoutées. Les codeurs devraient également disposer d'un processus établi permettant de suggérer des fonctionnalités supplémentaires pour le dépôt Import-me.

Phase 2 : Créez un dépôt de documentation central et autonome

Outil à utiliser pour la plate-forme d'hébergement:

Les outils proposés pour cette plate-forme d'hébergement sont Read The Docs pour les raisons suivantes:- Très bien classé parmi les différentes plates-formes d'hébergement. - Mise à jour automatique lors de la transmission du commit - Assistance facile à configurer et à résoudre facilement grâce à la grande communauté qui l'utilise - La documentation est formatée à l'aide de reStructuredText et le résultat est compilé par Sphinx.

Organisez l'ensemble du contenu dans un ordre logique et séquentiel:

Les contenus sont organisés dans l'ordre suivant:- - Présentation de la documentation pour les développeurs: cette section présente Moja Global et FLINT. - Contribution: cette section comprend les sous-sections "Comment contribuer" (codes/signalements de bugs/traduction/documentation/organisation d'événements, etc.) et "Code de conduite". - Configuration du développement: cette section comprend les sous-sections "Git & GitHub Workflow", "Windows Installation" et "Linux Installation". - Workflow de développement: Cette section aborde les outils et le manuel de test intégré dans votre document. - Rejoignez-nous: dans cette section, vous trouverez les différents forums sociaux tels que les chaînes Slack où vous pourrez entrer en contact et travailler avec Moja Global.

Phase 3 : Ajoutez le flux de travail du développeur et le site Web de la communauté pour les nouveaux contributeurs

Documentation relative au workflow pour les développeurs:

La documentation relative aux workflows pour les développeurs comprend les sous-sections suivantes:

• Pile technologique/Architecture utilisée et les différents modules du code: documentation permettant de familiariser les nouveaux contributeurs avec la pile technologique implémentée, les différentes bibliothèques et les modules du codebase.
• Outils intégrés de test et de couverture: découvrez de nouveaux contributeurs aux outils de pipeline CI/CD utilisés pour les tests. Les bots de couverture et les contrôles qualité automatisés s'exécutent sur leur code. Il leur fournit également des directives sur les personnes à aborder en cas d'échec des tests.
• Bots utilisés pour faciliter le workflow.Par exemple : Zulipbot : conception de modèles de contenu pour les bots à afficher et documentation disponible pour permettre aux utilisateurs de comprendre les bots et même d'améliorer leur configuration grâce à leur contribution.
• Test et envoi manuels d'une demande d'extraction: documentation à fournir pour expliquer comment tester manuellement les demandes d'extraction par rapport à certaines normes et comment importer les résultats en termes de captures d'écran/GIF lors de l'envoi de demandes d'extraction.
• Consignes que les contributeurs doivent suivre lors de l'examen des demandes d'extraction: consignes sur le taggage de certaines équipes en vue d'un examen et sur l'ajout de libellés (par exemple, "Examen requis") à la demande d'extraction afin que les responsables de la maintenance puissent y répondre.

Site Web de la communauté:

Le site Web de la communauté offrira les fonctionnalités suivantes :

• Informations concernant notre workflow: le workflow comprend une série d'actions qu'un nouveau contributeur peut commencer par effectuer, par exemple revendiquer un problème de type "priorisation", puis créer un problème pour une autre personne, puis aider les autres en envoyant des commentaires et en examinant leurs demandes d'extraction.
• Liste des problèmes "Nouveaux utilisateurs uniquement" : liste des problèmes spécifiquement destinés aux nouveaux utilisateurs ou aux nouveaux contributeurs.
• Liste des problèmes obsolètes: liste des problèmes n'ayant pas fait l'objet d'une longue discussion depuis une longue période et pouvant, par conséquent, être sélectionnés par les contributeurs.
• Liste des contributeurs: liste des contributeurs qui ont jusqu'à présent contribué aux référentiels de Moja Global.
• Récents contributeurs: liste des contributeurs qui ont récemment contribué aux référentiels de Moja Global.
• Liens vers des forums de chat: informations et liens permettant de rejoindre la communauté Slack afin de résoudre ses questions et d'approfondir la discussion sur les projets.