proyecto global de Moja

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.

Resumen del proyecto

Organización de código abierto:

moja global

Escritor 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, con la que se puede guiar a los colaboradores nuevos en una incorporación técnica, de modo que 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: - El desorganizado de las instrucciones de la guía de configuración local hace que resulte difícil para un nuevo colaborador comenzar. - Varios repositorios de FLINT no tienen documentación sobre su propósito y no están vinculados entre sí, lo que dificulta al usuario nuevo 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. - Por el momento, el flujo de trabajo de Git no forma parte de la documentación

Solución propuesta

Esta propuesta presenta una solución para guiar a los colaboradores nuevos a través de una integración técnica, de modo que los colaboradores nuevos 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 apta 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 refactorizar: 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. También es necesario modificar la documentación a fin de 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 las pautas de contribución, las instrucciones de configuración del proyecto y las guías paso a paso. - Flujo de trabajo de desarrollo 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 para contribuir a Git y la arquitectura tecnológica del proyecto junto con los lineamientos de pruebas y QA. El sitio web propuesto para la comunidad será una aplicación de una sola página que mostrará el flujo de trabajo, los problemas de los nuevos colaboradores que los nuevos colaboradores pueden reclamar y una lista de todos los colaboradores. Fase 1: Revisión de la documentación existente y refactorización:

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 las bibliotecas requeridas. 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 se adaptan a Windows, pero en la instalación de Linux, el redireccionamiento al repositorio FLINT.docker puede ser beneficioso. - FLINT.docker: La documentación actual no proporciona el propósito detrás de la configuración de este repositorio, que es proporcionar la instalación de Linux de FLINT 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 información suficiente sobre cómo compilar a partir del archivo makefile. - FLINT.example: La documentación actual no proporciona el propósito detrás de la configuración de este repositorio, que es proporcionar un ejemplo de cómo usar FLINT. Las diferentes ejecuciones de muestra se pueden segregar mejor con instrucciones específicas para que se ejecuten. También necesitamos vincular este repositorio a nuestro repositorio principal de FLINT para que los usuarios puedan navegar hasta aquí con el fin de 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 en sentido ascendente para el repositorio. También proporcionará información sobre cómo reajustarse en función de la instancia principal más reciente y manejar los conflictos de combinación. - Insignias y emojis: En la documentación actual, no hay insignias ni emojis que ayuden 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 redirigir 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 iniciar cualquier repositorio de Moja Global. La documentación actual no menciona la importancia para lo mismo. 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 debe existir 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á en la plataforma de hosting:

Las herramientas propuestas para esta plataforma de hosting son "Leer los documentos" debido a las siguientes razones:- Se encuentran en una posición alta entre las diferentes plataformas de hosting. - Actualización automática en la confirmación del envío - Es fácil de configurar y ofrece asistencia para la solución de problemas fácilmente debido a que la gran comunidad la usa. - La documentación se formatea con reStructuredText y el resultado se compila con Sphinx.

Organiza todo el contenido de forma lógica secuencial:

El orden de contenido propuesto es el siguiente:- - Introducción a la documentación para desarrolladores: En esta sección, se presenta una introducción a Moja Global y FLINT. - Contribución: Esta sección constará de subsecciones de “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 de desarrollo: Esta sección constará de subsecciones de “Flujo de trabajo de Git y GitHub”, “Instalación de Windows”, “Instalación de Linux”. - Flujo de trabajo del desarrollador: Esta sección consiste en un debate sobre las herramientas integradas para las pruebas y cómo realizar la siguiente solicitud manual. - Únete a nosotros: en esta sección encontrarás los diferentes foros sociales, como los canales de Slack, para conectarte y trabajar con Moja Global.

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

Documentación del flujo de trabajo para desarrolladores:

La documentación sobre los flujos de trabajo para desarrolladores constará de las siguientes subsecciones:

• Pila tecnológica/arquitectura usadas 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.
• Las herramientas integradas de prueba y cobertura: se presentan nuevos colaboradores en las herramientas de canalización de CI/CD utilizadas para las pruebas, los bots de cobertura y las verificaciones de calidad automatizadas se ejecutan en su código. También proporcionarles lineamientos sobre a quién debes acudir si las pruebas fallan.
• Bots utilizados para facilitar el flujo de trabajo, p. ej., Zulipbot: Diseño de plantillas de contenido para que los bots se muestren y documentación disponible para permitir que los usuarios comprendan los bots y, además, realicen contribuciones para mejorar la configuración del bot.
• Pruebas y envíos manuales de una solicitud de extracción: Es la documentación que se proporcionará para probar de forma manual las solicitudes de extracción en función de ciertos estándares y subir los resultados en términos de capturas de pantalla o GIFs cuando se envíen solicitudes de extracción.
• Lineamientos de revisión de las solicitudes de extracción que deben seguir los colaboradores: Son lineamientos para etiquetar ciertos equipos para su revisión y agregar etiquetas como “requiere revisión” a la solicitud de extracción a fin de 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 puede comenzar un nuevo colaborador, p. ej., reclamar un problema relacionado con los tiempos de espera iniciales y, luego, crear un problema de tiempo de espera para otra persona y ayudar a otros, ya que proporciona comentarios y revisa sus solicitudes de extracción.
• Lista de problemas exclusivos para el primer temporizador: La lista de problemas específicamente pensados para los usuarios nuevos o los colaboradores nuevos.
• Lista de problemas inactivos: Se refiere a la lista de problemas en los que no se trabajó durante un período prolongado 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: La lista de colaboradores que contribuyeron recientemente a los repositorios de Moja Global.
• Vínculos para unirte a foros de chat: información y vínculos para unirte a la comunidad de Slack a fin de resolver sus consultas y conversar más sobre los proyectos.