projet global moja

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

Résumé du projet

Organisation Open Source:

moja international

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, qui guide les nouveaux contributeurs dans leur intégration technique afin qu'ils puissent facilement se lancer avec un minimum d'aide de la part des responsables.

Problèmes liés au projet

Voici la liste des problèmes les plus cruciaux liés à la documentation actuelle : - Des parties désorganisées des instructions du guide de configuration locale, ce qui rend difficile la prise en main par un nouveau contributeur. - Les nombreux dépôts de FLINT manquent de documentation sur leur objectif et ne sont pas liés les uns aux autres, ce qui rend difficile l'identification du dépôt à installer. - L'installation sous Windows est bien documentée, mais la documentation d'installation sous Linux peut être améliorée. - Le workflow Git ne fait pas actuellement partie de la documentation

Solution proposée

Cette proposition présente une solution permettant d'accompagner les nouveaux contributeurs lors de leur intégration technique afin qu'ils puissent se lancer facilement avec un minimum d'aide de la part des mainteneurs. Pour ce faire, vous pouvez refactoriser la documentation actuelle pour la rendre adaptée aux débutants et disposer d'un dépôt autonome central pour toute la documentation disponible. Le projet est divisé en trois phases:- - Examen de la documentation existante et refactoring: l'objectif de cette phase est d'examiner 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 adaptée aux débutants en ajoutant des badges, des emoji et des informations sur les problèmes signalés par des tags pour les nouveaux utilisateurs ou de bons tags de premier problème. - Créer un dépôt de documentation central autonome: l'objectif de cette phase est de lier toute la documentation disponible dans un ordre séquentiel logique dans un dépôt autonome. Cela implique de classer les consignes de contribution, les instructions de configuration du projet et les guides par étapes. - Ajoutez le workflow de développement et le site Web de la communauté pour les nouveaux développeurs: l'objectif de cette phase est d'ajouter le workflow de développement, qui contient les consignes de contribution Git et l'architecture technique du projet, ainsi que les consignes de test et de contrôle qualité. Le site Web de la communauté proposée sera une application monopage affichant le workflow, les problèmes que les nouveaux contributeurs peuvent signaler et la liste de tous les contributeurs. Phase 1: Examiner la documentation existante et effectuer un refactoring:

Modifier la documentation actuelle des dépôts suivants : - FLINT: la documentation actuelle n'est pas très détaillée et ne fournit pas d'ordre séquentiel des bibliothèques requises. Les guides d'instructions détaillés sont divisés en différents fichiers PDF, mais peuvent être regroupés dans un seul et même document plus concis. En outre, les guides d'installation sont spécifiques à Windows, mais pour l'installation Linux, il peut être utile de rediriger vers le dépôt FLINT.docker. - FLINT.docker: la documentation actuelle n'indique pas l'objectif de la configuration de ce dépôt, qui est de fournir l'installation Linux de FLINT via Docker. La prise en charge via Docker n'est limitée qu'à Ubuntu 18.04 (Bionic Beaver), mais 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, ainsi que sur les informations suffisantes pour créer à partir du fichier makefile. - FLINT.example: la documentation actuelle n'indique pas l'objectif de la configuration de ce dépôt, qui est de fournir un exemple d'utilisation de FLINT. Les différentes exécutions d'exemples peuvent être mieux séparées par des instructions spécifiques à exécuter. Nous devons également associer ce dépôt à notre dépôt FLINT principal, afin de permettre aux utilisateurs d'y accéder pour voir l'exemple en action.

Les informations suivantes doivent être ajoutées à la documentation actuelle : - Utilisation de Git et GitHub: elle comprendra des instructions détaillées sur la création d'une fourchette, le clonage, puis la configuration du flux d'envoi distant pour le dépôt. Il vous indiquera également comment rebaser sur le dernier maître et gérer les conflits de fusion. - Badges et emoji: la documentation actuelle ne comporte pas de badges ni d'emoji, qui pourraient aider les nouveaux contributeurs à se sentir accueillis et à trouver les problèmes moins intimidants. - Informations sur les problèmes adaptés aux débutants: cela permettra de rediriger les nouveaux contributeurs vers les problèmes adaptés aux 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 lancer n'importe quel dépôt Moja Global. La documentation actuelle ne mentionne pas l'importance de ces éléments. Il doit être mis à jour pour mentionner le dépôt Import-me. Vous devez également ajouter les étapes permettant de le choisir comme modèle lors de la création d'un dépôt. Un processus établi doit également permettre aux codeurs de suggérer des fonctionnalités supplémentaires pour le dépôt Import-me.

Phase 2 : Création d’un répertoire de documentation autonome et centralisé

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:- - Classement élevé parmi les différentes plates-formes d'hébergement. - Mise à jour automatique lors de l'envoi d'un commit - Facilité de configuration et assistance de dépannage disponible facilement grâce à la grande communauté qui l'utilise - La documentation est mise en forme à l'aide de reStructuredText et la sortie est compilée par Sphinx.

Organisez tous les contenus de manière séquentielle logique:

L'ordre proposé des contenus est le suivant:- Introductio aux documentations pour les développeurs: cette section présente Moja Global et FLINT. - Contribution: cette section comprendra les sous-sections "Méthodes de contribution" (en termes de code, de signalement de bugs, de traduction, de documentation, d'organisation d'événements, etc.) et "Code de conduite". - Configuration de développement: cette section comprendra les sous-sections "Workflow Git et GitHub", "Installation sous Windows" et "Installation sous Linux". - Workflow du développeur: cette section comprendra une discussion sur les outils intégrés pour les tests, et sur la façon d'effectuer des tests manuels sur votre demande d'extraction, ainsi que d'autres informations, comme indiqué dans la phase suivante. - Rejoignez-nous: cette section fournira les différents forums sociaux tels que les chaînes Slack afin de vous connecter et de travailler avec Moja Global.

Phase 3 : Ajouter le flux de travail des développeurs et le site Web de la communauté pour les nouveaux contributeurs

Documentation sur le flux de travail pour les développeurs:

La documentation du workflow du développeur comprend les sous-sections suivantes:

• La pile technologique/l'architecture utilisée et les différents modules du code: documentation permettant aux nouveaux contributeurs de se familiariser avec la pile technologique implémentée, les différentes bibliothèques et les différents modules du codebase.
• Outils de test et de couverture intégrés: présentation 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. De plus, en lui fournissant des directives sur les personnes à approcher si les tests échouent.
• Bots utilisés pour simplifier le workflow (par exemple, Zulipbot) : conception de modèles de contenu à afficher par les bots et de documentation permettant aux utilisateurs de comprendre les bots et même d'améliorer leur configuration en y contribuant.
• Test manuel et envoi 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 à suivre par les contributeurs pour examiner les demandes d'extraction: consignes concernant le taggage de certaines équipes pour examen et l'ajout de libellés tels que "nécessite un examen" à la demande d'extraction afin de permettre aux responsables de répondre.

Site Web de la communauté:

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

• Informations sur notre workflow: le workflow consiste en la série d'actions qu'un nouveau contributeur peut effectuer, par exemple en revendiquant un problème pour les débutants, puis en créant un problème pour un autre contributeur et en aidant les autres en leur donnant des commentaires et en examinant leurs requêtes pull.
• Liste des problèmes réservés aux nouveaux contributeurs: liste des problèmes spécifiquement destinés aux nouveaux contributeurs.
• Liste des problèmes obsolètes: liste des problèmes sur lesquels aucune action n'a été effectuée depuis longtemps et qui peuvent donc être sélectionnés par les contributeurs.
• Liste des contributeurs: liste des contributeurs qui ont jusqu'à présent contribué aux dépôts Moja Global.
• Contributeurs récents: liste des contributeurs qui ont récemment contribué aux dépôts Moja Global.
• Liens vers les forums de discussion: informations et liens permettant de rejoindre la communauté Slack pour résoudre les requêtes et discuter davantage des projets.