Coloque un archivo COMMUNICATION.md adaptado al proyecto en cada repositorio. Si la propiedad del repositorio del proyecto se transfiere a un equipo diferente en el futuro, necesitarán poder acceder y editar la documentación relacionada con el proyecto. Esto incluye la documentación que describe los procesos de comunicación que los usuarios deben usar para contactar al equipo.
Elimine el párrafo superior cuando esta sección esté completa.
Canal de Slack del equipo:
Canales especiales de Slack: (temas específicos y accesibles para cualquier contribuyente externo)
Correo del equipo:
Los siguientes tipos de acciones pueden moverse a la sección apropiada y se pueden agregar más.
Método de contacto
(correo o canal de Slack)
Reporte de error
Solicitud de función
Preguntas sobre el proceso
Merge Requests después del envío
Agregar más aquí...
Actualizaciones de estado
otro
otro
Agregar más aquí...
Gerentes o roles y situaciones específicas por las que deben ser contactados fuera del canal del equipo.
(está configurado de esta manera para que el documento pueda cambiarse fácilmente si hay nuevos miembros en el equipo)
Cambios importantes (por ejemplo, cambios en nuestra API o contratos de mensajería)
Interrupciones extendidas/planificadas (tiempo de inactividad para mantenimiento)
Interrupciones inesperadas
Cambios específicos de tráfico (por ejemplo, equipo a equipo, etc.)
Implementación de nuevas funciones
Según las pautas del producto
Fin de mes y congelamiento de código en toda la empresa
Equipo interno y otros equipos que contribuyen a los repositorios
Agregar más...
Explique cómo encontrar al propietario, parte responsable o grupo al que las personas deben contactar si tienen preguntas sobre la documentación en el repositorio.
Describa este proceso de comunicación.
Por ejemplo:
Si tiene preguntas sobre una pieza específica de documentación, puede encontrar al miembro del equipo responsable de la información aquí:
Puede contactar a la parte responsable enviando un mensaje en el canal xyz, enviándoles un mensaje directo en chat, correo electrónico, etc. La persona que certificó la documentación por última vez es la parte responsable.
Nombre de la Funcionalidad: (rellénalo con un identificador único, mi_funcionalidad_asombrosa)
Fecha de Inicio: (rellénalo con la fecha de hoy, YYYY-MM-DD)
Propietarios nominados: (Representantes de las áreas técnicas afectadas por el RFC. A menudo serán líderes técnicos, pero pueden delegar. Los RFC no pueden ser aceptados hasta que todos los propietarios nominados hayan dado su aprobación.)
Explicación en un párrafo de la funcionalidad.
Esta sección es esencial para permitirnos aprender de las cosas que estamos implementando.
¿Cuándo es la retrospectiva?
[ ] ¿Retro completada?
(¿dónde/cómo se llevará a cabo, cómo pueden las personas involucrarse, dónde están los resultados?)
¿Por qué estamos haciendo esto? ¿Qué casos de uso soporta? ¿Cuál es el resultado esperado?
Explica la propuesta como si ya existiera y la estuvieras enseñando a otro ingeniero. Eso generalmente significa:
Introducir nuevos conceptos nombrados.
Explicar la funcionalidad en gran medida en términos de ejemplos.
Explicar cómo los ingenieros deben pensar sobre la funcionalidad. Debe explicar el impacto lo más concretamente posible.
Si aplica (por ejemplo, propuesta de código/arquitectura), proporcionar mensajes de error de muestra, advertencias de desaprobación o guía de migración.
Si aplica, describir las diferencias entre enseñar esto a ingenieros existentes y nuevos ingenieros.
Para los RFC orientados a la implementación, esta sección debe centrarse en cómo los contribuyentes deben pensar sobre el cambio y dar ejemplos de su impacto concreto. Para los RFC de políticas/procesos, esta sección debe proporcionar una introducción basada en ejemplos a la política/proceso y explicar su impacto en términos concretos.
Esta es la parte técnica del RFC. Explica el diseño con suficiente detalle para que:
Su interacción con otras funcionalidades sea clara.
Sea razonablemente claro cómo se implementaría la funcionalidad.
Los casos extremos sean disecados por ejemplo.
La sección debe volver a los ejemplos dados en la sección anterior y explicar más completamente cómo la propuesta detallada hace que esos ejemplos funcionen.
¿Por qué no deberíamos hacer esto?
¿Por qué este diseño es el mejor en el espacio de posibles diseños?
¿Qué otros diseños se han considerado y cuál es la razón para no elegirlos?
¿Cuál es el impacto de no hacer esto?
Discute el arte previo, tanto lo bueno como lo malo, en relación con esta propuesta. Algunos ejemplos de lo que esto puede incluir son:
Para lenguaje, librería, herramientas, etc.: ¿Existe esta funcionalidad en otros lugares y qué experiencia ha tenido su comunidad?
Para propuestas comunitarias: ¿Esto lo hace alguna otra comunidad y cuáles fueron sus experiencias con ello?
Para otros equipos: ¿Qué lecciones podemos aprender de lo que otras comunidades han hecho aquí?
Artículos: ¿Hay algún artículo publicado o publicaciones destacadas que discutan esto? Si tienes algunos artículos relevantes a los que referirte, esto puede servir como un trasfondo teórico más detallado.
Esta sección está destinada a alentarte como autor a pensar en las lecciones de otros lugares, proporcionar a los lectores de tu RFC una imagen más completa. Si no hay arte previo, está bien - tus ideas nos interesan ya sean completamente nuevas o una adaptación de otros lugares.
¿Qué partes del diseño esperas resolver a través del proceso de RFC antes de que esto se fusione?
¿Qué partes del diseño esperas resolver a través de la implementación de esta funcionalidad antes de la estabilización?
¿Qué problemas relacionados consideras fuera del alcance de este RFC que podrían abordarse en el futuro independientemente de la solución que surja de este RFC?
Piensa en cuál sería la extensión y evolución natural de tu propuesta y cómo afectaría a los equipos y proyectos en su conjunto de manera holística. Trata de usar esta sección como una herramienta para considerar más plenamente todas las posibles interacciones con el proyecto y los equipos en tu propuesta. También considera cómo encaja todo esto en la hoja de ruta del proyecto y del sub-equipo relevante. Esta también es un buen lugar para "volcar ideas", si están fuera del alcance del RFC que estás escribiendo pero de otro modo relacionadas. Si has intentado y no puedes pensar en ninguna posibilidad futura, simplemente puedes decir que no puedes pensar en nada. Ten en cuenta que tener algo escrito en la sección de posibilidades futuras no es una razón para aceptar el RFC actual o futuro; tales notas deben estar en la sección de motivación o razonamiento en este o en RFCs posteriores. La sección simplemente proporciona información adicional.
Esta sección debe contener una breve descripción (3-5 oraciones) de la misión de su proyecto. El objetivo es indicar en qué planea trabajar y ayudar a los contribuyentes externos a comprender aproximadamente qué tipos de funcionalidades serán probablemente bienvenidas para este proyecto.
Consulte también el capítulo de declaración de misión en Producing Open Source Software.
Esta sección debe contener documentación breve escrita para usuarios principiantes sobre cómo comenzar a usar el proyecto. Se puede vincular a documentación más detallada desde aquí.
Esta sección puede enumerar cualquiera o todos los siguientes elementos:
Lista de funcionalidades, casos de uso que el software aborda.
Información sobre principios de diseño utilizados para resolver compensaciones
Enlaces a documentación adicional a nivel de usuario
Respuestas a preguntas frecuentes (FAQ), preferiblemente en un formato que permita vincular preguntas específicas y sus respuestas para una referencia más fácil.
Esta sección debe contener documentación breve sobre cómo obtener ayuda para el proyecto como usuario. Esto podría ser tan simple como dirigir a los usuarios al gestor de tareas si así es como su proyecto desea responder preguntas. También podría apuntar a un canal de chat archivado y consultable, alguna lista de correo archivada consultable, o algún foro de usuarios en línea.
Esta sección debe incluir información sobre cómo ponerse en contacto con el proyecto:Típicamente contendrá enlaces a canales de comunicación archivados, consultables y vinculables.
Este es un buen lugar para dar crédito a los Trusted Committers del proyecto.
También es un buen lugar para incluir información sobre lo que significa ser un Trusted Committer para este proyecto - aunque idealmente todos los proyectos en una organización utilizan la misma definición que solo se vincula desde aquí. La razón para mantener el enlace aquí es para colegas que tienen poca o ninguna experiencia trabajando y contribuyendo a proyectos InnerSource para tener un enlace directo a la información de toda la empresa desde los proyectos tecnológicos que necesitan para su trabajo diario.
Esta sección debe documentar (o vincular a documentación) sobre todo lo que un contribuyente principiante necesita saber para comenzar. Típicamente no se cubrirán todos los temas a continuación. Concéntrese en lo que difiere en su proyecto de la configuración estándar y lo que los contribuyentes anteriores encontraron difícil de entender.
Encontrar el código fuente.
Encontrar una lista de issues que su proyecto necesita ayuda - estos pueden ser tanto técnicos como no técnicos. Típicamente los mantendrá en un gestor de tareas accesible para los contribuyentes.
Enlaces a documentación adicional, por ejemplo, sobre la arquitectura del proyecto, convenciones de codificación generales, convenciones de prueba...
Para contribuciones técnicas: Realizar cambios, construir el proyecto y probar sus cambios.
Enviar sus cambios de vuelta al proyecto.
Idealmente también incluye información sobre cómo es el proceso preferido de cambios para el proyecto: ¿Deberían los contribuyentes primero abrir un issue y enviar una propuesta, o son bienvenidos a enviar cambios de inmediato? ¿Qué es importante para usted al revisar contribuciones?
Además, debe describir cualquier valor de diseño que desee seguir en el proyecto. Hacer estos explícitos a menudo ayuda a resolver compensaciones más rápida y fácilmente. Además, ayuda a hacer transparentes los cambios en suposiciones que de otro modo serían implícitas.
Con el tiempo notará que esta sección crece sustancialmente. En ese caso, piense en mover la información a archivos separados, por ejemplo, CONTRIBUTING.md y TESTING.md.
Proporcione información aquí sobre qué tipos de contribuciones busca su proyecto. Por ejemplo, pueden ser reportes de errores (bug reports), ayuda para responder preguntas de usuarios, mejoras en la documentación, corrección de errores y también implementación de nuevas funcionalidades.
Por favor, sigue estos pasos para contribuir a este proyecto:
Agregue aquí información sobre cómo enviar reportes de errores. Esto debe incluir sugerencias sobre el tipo de información que el proyecto necesitará para reproducir y corregir problemas. También puede incluir información sobre configuraciones incorrectas comunes que parecen errores.
También incluya información sobre qué pueden esperar los contribuyentes en términos de tiempo de primera respuesta y proceso posterior.
Si tienes preguntas, abre un problema en el gestor de tareas (issue tracker).
Agregue aquí información sobre cómo enviar solicitudes de funcionalidades. También incluya información sobre qué pueden esperar los contribuyentes en términos de tiempo de primera respuesta y proceso posterior.
Incluya información sobre las mejores prácticas de documentación que sigue su proyecto, así como cómo construir la documentación, las verificaciones que debe ejecutar y cómo enviar los cambios realizados al proyecto.
Esta sección debe contener información sobre:
Cómo acceder al código fuente del proyecto,
Estructura general del proyecto,
Requisitos para el entorno de desarrollo,
Pautas de formato de código,
Cómo ejecutar el conjunto de pruebas.
Esta sección debe hacer explícito el proceso para convertirse en Trusted Committer si esa ruta está abierta a los contribuyentes.
Esta sección sirve como recordatorio para los existentes y explicación para nuevos Trusted Committers detallando cómo agregar otros al equipo central. Idealmente, esta información es idéntica para todos los proyectos en la organización, por lo que se puede vincular a la información central desde aquí.