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 du processus d'intégration technique afin qu'ils puissent se lancer facilement avec une assistance minimale 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 : - Articles désorganisés des instructions du guide de configuration local, ce qui complique la tâche pour un nouveau contributeur. - Plusieurs référentiels de FLINT manquent 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. - L'installation de Windows est bien documentée, mais la documentation d'installation basée sur Linux peut être améliorée. - Le workflow Git ne fait actuellement pas partie de la documentation

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 une assistance minimale de la part des responsables. Pour ce faire, vous pouvez refactoriser la documentation actuelle pour la rendre adaptée aux débutants et conserver un dépôt central autonome pour toute la documentation disponible. Le projet est divisé 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 adaptée aux débutants en ajoutant des badges, des emoji et des informations sur les problèmes signalés par des tags indiquant qu'ils sont réservés aux nouveaux utilisateurs ou qu'ils sont fiables. - Créer un référentiel de documentation central et autonome: l'objectif de cette phase est de relier toute la documentation disponible dans un ordre séquentiel logique à un référentiel autonome. Cela implique de commander les directives de contribution, les instructions de configuration du projet et les guides par étapes. - Ajout du flux de travail du développeur et du site Web de la communauté pour les nouveaux développeurs: l'objectif de cette phase est d'ajouter le workflow du développeur, qui contient les consignes de contribution Git, l'architecture technique du projet, ainsi que les directives de test et de contrôle qualité. Le site Web de la communauté proposé sera une application monopage affichant le workflow, les problèmes concernant les nouveaux contributeurs qui peuvent être revendiqués par les nouveaux contributeurs, ainsi qu'une liste de tous les contributeurs. Phase 1 : Examiner la documentation existante et la refactorisation

Modifiez la documentation actuelle des 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 étape par étape sont divisés en plusieurs PDF, mais peuvent être regroupé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 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 la configuration 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 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 Docker 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 la configuration de ce dépôt, qui consiste à fournir un exemple d'utilisation de FLINT. Les différents exemples d'exécution peuvent être mieux séparés par des instructions spécifiques. Nous devons également lier ce dépôt à notre dépôt principal FLINT, ce qui permet aux utilisateurs de naviguer ici pour voir 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 façon de dupliquer, de cloner, puis de configurer le flux distant en amont pour le dépôt. Il fournit également des informations sur la redéfinition par rapport au dernier maître et sur la gestion des conflits de fusion. - Badges et emoji: la documentation actuelle ne comporte pas de badges ni d'emoji, ce qui permet aux nouveaux contributeurs de se sentir les bienvenus et de résoudre les problèmes plus facilement. - Informations sur les problèmes pour débutants et débutants: cela aidera à 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 rapidement 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, ainsi que la procédure permettant de le choisir comme modèle pour la création d'un nouveau dépôt. Les développeurs doivent également mettre en place un processus établi pour suggérer des fonctionnalités supplémentaires pour le dépôt Import-me.

Phase 2 : Créer 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é par les différentes plates-formes d'hébergement - Mise à jour automatique lors du transfert de validation - Assistance facile à configurer et assistance de dépannage, grâce à sa vaste communauté d'utilisateurs - 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 logique dans l'ordre:

Les contenus sont proposés dans l'ordre suivant:- - Présentation de la documentation pour les développeurs: cette section présente une présentation de Moja Global et de FLINT. - Contribution: cette section comprendra les sous-sections "Comment contribuer" (en termes de code/signalement de bugs/traduction/documentation/organisation d'événements, etc.) et "Code de conduite". - Configuration du développement: cette section comprendra les sous-sections "Workflow Git et GitHub", "Installation Windows" et "Installation Linux". - Processus de développement: cette section comprendra une discussion sur les outils et le prochain manuel de test et sur la manière de demander l'extraction des outils pour les tests et la procédure à suivre dans la phase de test. - Rejoignez-nous: cette section fournit les différents forums sociaux tels que les chaînes Slack pour entrer en contact et travailler avec Moja Global.

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

Documentation sur le workflow pour les développeurs:

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

• Pile technologique/architecture utilisée et différents modules du code: documentation permettant de familiariser les nouveaux contributeurs avec la pile technologique implémentée, ainsi que les différents modules et bibliothèques 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. Elle leur fournit également des directives sur les personnes à aborder en cas d'échec des tests.
• Bots utilisés pour faciliter le flux de travail.Par exemple : Zulipbot : conception de modèles de contenu à afficher pour les bots et de la documentation disponible afin de 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 sur la manière de tester manuellement les demandes d'extraction par rapport à certaines normes et sur l'importation des résultats en termes de captures d'écran/GIF lors de l'envoi de demandes d'extraction.
• Consignes concernant l'examen des demandes d'extraction à suivre par les contributeurs: consignes sur l'ajout de libellés à certaines équipes pour examen et ajout de libellés tels que "Examen nécessaire" à la demande d'extraction pour permettre aux responsables de répondre.

Site Web de la communauté:

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

• Informations sur notre workflow: le workflow comprend une série d'actions qu'un nouveau contributeur peut effectuer.Il peut s'agir, par exemple, de revendiquer un nouveau problème, puis de créer un problème pour une autre personne, puis d'aider les autres utilisateurs en leur 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 primoacheteurs ou aux nouveaux contributeurs.
• Liste des problèmes obsolètes: liste des problèmes qui n'ont pas fait l'objet d'une recherche prolongée et qui peuvent donc ê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.
• Contributeurs récents: liste des contributeurs qui ont récemment contribué aux référentiels de Moja Global.
• Liens pour rejoindre les forums de chat: informations et liens permettant de rejoindre la communauté Slack afin de résoudre ses questions et d'avoir d'autres discussions sur les projets.