En esta página, se incluyen 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
- 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 integración técnica para que puedan comenzar fácilmente con la asistencia mínima de los responsables de mantenimiento.
Problemas del proyecto
La siguiente es una lista de los problemas más importantes relacionados con la documentación actual: - Secciones desorganizadas de instrucciones de la guía de configuración local que dificultan el inicio de un colaborador nuevo. - Varios repositorios de FLINT carecen de documentación sobre su propósito y no están vinculados entre sí, lo que dificulta que los recién llegados identifiquen qué repositorio se debe instalar. - La instalación de Windows está bien documentada, pero la documentación de instalación basada en Linux tiene margen de mejora. - 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 para que puedan comenzar fácilmente con la asistencia mínima de los responsables de mantenimiento. Esto se puede lograr refactorizando la documentación actual para que sea apta para principiantes y también manteniendo un repositorio independiente central para toda la documentación disponible. El proyecto se divide en tres fases:- Revisión de la documentación existente y refactorización: El objetivo de esta fase es revisar la guía actual y refactorizarla de una manera que la haga concisa y fácil de comprender para los colaboradores nuevos. La documentación también debe modificarse para que sea más fácil para principiantes. Para ello, se deben agregar insignias, emojis y datos sobre los problemas etiquetados como solo para principiantes o como un buen primer problema. - Crea un repositorio de documentación central independiente: El objetivo de esta fase es vincular toda la documentación disponible en un orden secuencial lógico en un repositorio independiente. Esto incluye ordenar los lineamientos de contribución, las instrucciones de configuración del proyecto y las guías paso a paso. - Agrega el flujo de trabajo de los desarrolladores y el sitio web de la comunidad para desarrolladores nuevos: El objetivo de esta fase es agregar el flujo de trabajo de los desarrolladores, que contiene los lineamientos de contribución de git y la arquitectura tecnológica del proyecto, junto con los lineamientos de pruebas y QA. El sitio web de la comunidad propuesto será una aplicación de una sola página en la que se mostrará el flujo de trabajo, los problemas nuevos que pueden reclamar los colaboradores nuevos y una lista de todos los colaboradores. Fase 1: Revisa la documentación existente y realiza la 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 de requisitos previos necesarias. Las guías de instrucciones paso a paso están divididas en diferentes archivos PDF, pero se pueden unificar en un solo lugar de forma más concisa. Además, las guías de instalación están orientadas a Windows, pero para la instalación de Linux, podría ser beneficioso redireccionar al repositorio FLINT.docker. - FLINT.docker: La documentación actual no proporciona el propósito de configurar 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 poner énfasis en la forma secuencial de configurar los dockerfiles, con información suficiente sobre cómo compilar 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 se pueden separar mejor con instrucciones específicas para que se ejecuten. También necesitamos vincular este repositorio a nuestro repositorio principal de FLINT para proporcionarles a los usuarios una forma de navegar 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 flujo ascendente remoto para el repositorio. También te proporcionará información para volver a establecer la base en la versión maestra más reciente y controlar los conflictos de combinación. - Insignias y emojis: La documentación actual no incluye insignias ni emojis que puedan ayudar a que los colaboradores nuevos se sientan bienvenidos y que los problemas sean menos abrumadores. - Información sobre los problemas para principiantes o usuarios nuevos: Esto ayudará a redireccionar a los colaboradores nuevos a los problemas 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. En la documentación actual, no se menciona la importancia de estos elementos. Es necesario actualizar para mencionar el repositorio Import-me y los pasos para elegirlo como plantilla para crear un repositorio nuevo también deben agregarse. También debe haber un proceso establecido para que los programadores sugieran funciones adicionales para el repositorio de Import-me.
Fase 2: Crea un repositorio de documentación independiente y central :
Herramienta que se usará para la plataforma de hosting:
Las herramientas propuestas para esta plataforma de alojamiento son Read The Docs por los siguientes motivos:- - Tiene una clasificación alta entre las diferentes plataformas de alojamiento. - Actualización automática cuando se envía la confirmación - Es fácil de configurar y la asistencia para solucionar problemas está disponible fácilmente debido a la gran comunidad que la usa - La documentación tiene formato reStructuredText y Sphinx compila el resultado.
Organiza todo el contenido de forma secuencial y lógica:
El orden de contenido propuesto es el siguiente:- - Introducción a la documentación para desarrolladores: En esta sección, se hará una introducción a Moja Global y FLINT. - Contribución: Esta sección constará de las sub secciones "Formas de contribuir" (en términos de código, informar errores, traducción, documentación, organización de eventos, etcétera) y "Código de conducta". - Configuración de desarrollo: Esta sección constará de las sub secciones "Flujo de trabajo de Git y GitHub", "Instalación de Windows", "Instalación de Linux". - Flujo de trabajo del desarrollador: Esta sección constará de un análisis de las herramientas integradas para las pruebas y cómo realizar pruebas manuales en tu solicitud de extracción, y mucho más, como se documenta en la siguiente fase. - Únete a nosotros: En esta sección, se proporcionarán los diversos foros sociales, como los canales de Slack, para conectarse y trabajar con Moja Global.
Fase 3: Agrega el flujo de trabajo de los desarrolladores y el sitio web de la comunidad para los colaboradores nuevos:
Documentación del flujo de trabajo del desarrollador:
La documentación del flujo de trabajo del desarrollador constará de las siguientes sub secciones:
- La pila de tecnología o la arquitectura que se usó y los diversos módulos del código: Documentación para familiarizar a los colaboradores nuevos con la pila de tecnología implementada, las diversas bibliotecas y módulos de la base de código.
- Las herramientas de prueba y cobertura integradas: Presenta a los colaboradores nuevos 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 proporciona lineamientos sobre a quién recurrir si las pruebas fallan.
- Bots que se utilizan para facilitar el flujo de trabajo; p. ej., Zulipbot: Diseñar plantillas de contenido para que los bots se muestren y que la documentación esté disponible para permitir que los usuarios comprendan a los bots y hasta mejoren su configuración mediante contribuciones.
- Pruebas y envíos manuales de solicitudes de extracción: Se proporcionará documentación sobre cómo probar manualmente 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.
- Los colaboradores deben seguir los lineamientos de revisión de las solicitudes de extracción: Lineamientos para etiquetar a determinados equipos para su revisión y agregar etiquetas como “requiere revisión” a la solicitud de extracción para que los encargados de mantenimiento puedan responder.
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 consistirá en la serie de acciones con las que puede comenzar un colaborador nuevo, es decir, reclamar un problema para principiantes, crear un problema para principiantes para otra persona y ayudar a otros proporcionando comentarios y revisando sus solicitudes de extracción.
- Lista de problemas solo para usuarios nuevos: Es la lista de problemas específicamente destinados a usuarios nuevos o colaboradores nuevos.
- Lista de problemas inactivos: Es la lista de problemas en los que no se trabajó durante un período prolongado y, 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: Es la 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 unirse a la comunidad de Slack y resolver sus consultas y tener más conversaciones sobre los proyectos.