proyecto global de Moja

Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google Season of Docs.

Resumen del proyecto

Organización de código abierto:

moja global

Redactor técnico:

Tlazypanda

Nombre del proyecto:

Documentación de la guía de integración técnica para FLINT

Duración del proyecto:

Duración estándar (3 meses)

Project description

Documentación de la Guía de integración técnica para FLINT para guiar a los colaboradores nuevos a través de una incorporación técnica, de modo que los nuevos colaboradores puedan comenzar fácilmente con la asistencia mínima de los encargados de mantenimiento.

Problemas del proyecto

La siguiente es una lista de los problemas más importantes relacionados con la documentación actual: - Las instrucciones de la guía de configuración local están desorganizadas, lo que dificulta que un nuevo colaborador pueda dar sus primeros pasos. - Varios repositorios de FLINT no tienen documentación sobre su propósito y no están vinculados entre sí, lo que dificulta al principiante identificar qué repositorio debe instalarse. - La instalación de Windows está bien documentada, pero la documentación de instalación basada en Linux puede mejorarse. - El flujo de trabajo de Git no forma parte actualmente de la documentación

Solución propuesta

Esta propuesta presenta una solución para guiar a los nuevos colaboradores durante una incorporación técnica para que puedan comenzar fácilmente con la asistencia mínima de los encargados de mantenimiento. Esto se puede lograr refactorizando la documentación actual para que sea fácil de usar para principiantes y manteniendo un repositorio central independiente para toda la documentación disponible. El proyecto se divide en tres fases:- Revisar la documentación existente y refactorización: El objetivo de esta fase es revisar la guía actual y refactorizarla de manera que sea concisa y fácil de comprender para los nuevos colaboradores. La documentación también se debe modificar para que sea más fácil de usar para los principiantes. Para ello, se deben agregar insignias, emojis e información sobre problemas etiquetados con etiquetas de primer problema o solo para usuarios nuevos. - Crear un repositorio central de documentación independiente: El objetivo de esta fase es vincular toda la documentación disponible en un orden secuencial lógico en un repositorio independiente. Esto implica ordenar los lineamientos de la contribución, las instrucciones de configuración del proyecto y las guías paso a paso. - Agregar flujo de trabajo del desarrollador y sitio web de la comunidad para desarrolladores nuevos: El objetivo de esta fase es agregar el flujo de trabajo para desarrolladores que contiene las pautas de contribución de Git y la arquitectura tecnológica del proyecto junto con las pautas de prueba y control de calidad. El sitio web de la comunidad propuesto será una aplicación de una sola página que mostrará el flujo de trabajo, los problemas de los nuevos colaboradores que pueden reclamar los nuevos colaboradores y una lista de todos los colaboradores. Fase 1: Revisar la documentación existente y refactorizar:

Modifica la documentación actual de los siguientes repositorios: - FLINT: La documentación actual no es muy detallada y no proporciona un orden secuencial de bibliotecas de requisitos previos. Las guías paso a paso se dividen en diferentes archivos PDF, pero se pueden unificar en un solo lugar de manera más concisa. Además, las guías de instalación están destinadas a Windows, pero para la instalación en Linux, el redireccionamiento al repositorio FLINT.docker puede ser beneficioso. - FLINT.docker: La documentación actual no proporciona el propósito de configurar este repositorio, que es proporcionar la instalación de FLINT en Linux a través de Docker. La compatibilidad a través de Docker solo se limita a Ubuntu 18.04 (Bionic Beaver), pero se puede extender a otras distribuciones basadas en Linux. En la documentación actual, también se debe hacer énfasis en la forma secuencial de configurar los dockerfiles y en suficiente información sobre cómo realizar compilaciones a partir del archivo makefile. - FLINT.example: La documentación actual no proporciona el propósito de configurar este repositorio, que es proporcionar un ejemplo de cómo usar FLINT. Las diferentes ejecuciones de muestra pueden separarse mejor con instrucciones específicas para que se ejecuten. También necesitamos vincular este repositorio a nuestro repositorio FLINT principal proporcionando a los usuarios una manera de navegar hasta aquí para ver el ejemplo en acción.

Se debe agregar la siguiente información a la documentación actual: - Uso de Git y GitHub: Se incluirán instrucciones paso a paso sobre cómo bifurcar, clonar y, luego, configurar el repositorio remoto ascendente para el repositorio. También proporcionará información sobre cómo reubicar la versión principal más reciente y abordar los conflictos de combinación. - Insignias y emojis: La documentación actual carece de insignias y emojis, lo que puede ayudar a que los nuevos colaboradores se sientan bienvenidos y que los problemas sean menos abrumadores. - Información sobre los problemas para principiantes y principiantes: Esta información ayudará a redireccionar a los colaboradores nuevos a problemas aptos para principiantes y al sitio web de la comunidad. - Información sobre el repositorio Import-me: el repositorio Import-me actúa como una plantilla de referencia para poner en marcha cualquier repositorio de Moja Global. La documentación actual no menciona la importancia de esto. Se debe actualizar para mencionar el repositorio Import-me y también se deben agregar los pasos para elegirlo como plantilla para crear un nuevo repositorio. También debería haber un proceso establecido para que los codificadores sugieran funciones adicionales para el repositorio Import-me.

Fase 2: Crear un repositorio central de documentación independiente :

Herramienta que se utilizará como plataforma de hosting:

Las herramientas propuestas para esta plataforma de hosting son Leer los documentos por las siguientes razones:- Están bien clasificadas entre las diferentes plataformas de hosting. - Actualización automática de la confirmación - Fácil de configurar y asistencia para la solución de problemas disponible con facilidad debido a la gran comunidad que la usa - La documentación se formatea con reStructuredText y el resultado se compila con Sphinx.

Organiza todo el contenido de forma secuencial y lógica:

El orden propuesto para el contenido es el siguiente:- - Introducción a la documentación para desarrolladores: En esta sección, se proporciona una introducción a Moja Global y FLINT. - Contribución: Esta sección constará de subsecciones “Formas de contribuir” (en términos de código/informe de errores/traducción/documentación/organización de eventos, etc.) y “Código de conducta”. - Configuración del desarrollo: Esta sección constará de subsecciones “Flujo de trabajo de Git y GitHub”, “Instalación de Windows”, “Instalación de Linux”. - Flujo de trabajo del desarrollador: Esta sección incluirá un análisis más detallado de las herramientas integradas para la fase de pruebas y cómo realizar las pruebas manuales. - Únase a nosotros: En esta sección, encontrará los distintos foros sociales, como los canales de Slack, para conectarse y trabajar con Moja Global.

Fase 3: Agrega el flujo de trabajo del desarrollador y el sitio web de la comunidad para los colaboradores nuevos:

Documentación del flujo de trabajo del desarrollador:

La documentación sobre el flujo de trabajo para desarrolladores constará de las siguientes subsecciones:

• Pila tecnológica/arquitectura utilizada y los diversos módulos en el código: Documentación para familiarizarse con los nuevos colaboradores con la pila tecnológica implementada, las diversas bibliotecas y módulos de la base de código.
• Herramientas integradas de prueba y cobertura: Presentamos nuevos colaboradores en las herramientas de canalización de CI/CD que se usan para las pruebas, los bots de cobertura y las verificaciones de calidad automatizadas que se ejecutan en su código. También proporcionarles lineamientos sobre a quién abordar si las pruebas fallan.
• Bots que se utilizan para facilitar el flujo de trabajo, p. ej., Zulipbot: Diseño de plantillas de contenido para que se muestren los bots y Documentación que esté disponible para permitir que los usuarios comprendan los bots y contribuyan a mejorar la configuración del bot.
• Prueba y envío manuales de solicitudes de extracción: Es la documentación que se proporcionará sobre cómo probar manualmente las solicitudes de extracción en función de ciertos estándares y subir resultados en términos de capturas de pantalla o GIFs tras el envío de las solicitudes de extracción.
• Lineamientos para la revisión de las solicitudes de extracción que deben seguir los colaboradores: Lineamientos sobre cómo etiquetar ciertos equipos para su revisión y agregar etiquetas como “requiere revisión” a la solicitud de extracción para que los encargados de mantenimiento respondan.

Sitio web de la comunidad:

El sitio web de la comunidad tendrá las siguientes funciones:

• Información sobre nuestro flujo de trabajo: El flujo de trabajo constará de una serie de acciones con las que un nuevo colaborador puede comenzar, es decir, reclamar un problema de los primeros temporizadores, seguida de la creación de un problema de los primeros temporizadores para otra persona y ayudar a otros a proporcionar comentarios y revisar sus solicitudes de extracción.
• Lista de problemas solo para usuarios nuevos: Es la lista de problemas específicamente dirigidos a colaboradores nuevos o nuevos.
• Lista de problemas inactivos: Es la lista de problemas en los que no se ha trabajado durante un largo período y que, por lo tanto, están disponibles para que los colaboradores los elijan.
• Lista de colaboradores: Es la lista de colaboradores que hasta el momento contribuyeron a los repositorios de Moja Global.
• Colaboradores recientes: Lista de colaboradores que contribuyeron recientemente a los repositorios de Moja Global.
• Vínculos para unirse a foros de chat: información y vínculos para unirte a la comunidad de Slack para resolver sus consultas y debatir más sobre los proyectos.