¿Alguna vez has sentido que un Pull Request (PR) se convierte en un campo de batalla? Discusiones interminables sobre si usar tabulaciones o espacios, debates sobre en qué rama debería ir el cambio o, peor aún, código que llega a producción y nadie se hace responsable cuando falla.
En equipos de alto rendimiento y organizaciones de gran escala, como el ecosistema de Bancolombia, la voluntad y el «buen juicio» no son suficientes para escalar. Necesitamos un Contributing Agreement: un contrato social y técnico que define las reglas del juego antes de que se escriba la primera línea de código.
¿Por qué la subjetividad es el enemigo del Senior?
Un error común en niveles Junior/Middle es calificar un PR basándose en «cómo me gusta a mí». Un Senior, en cambio, califica basado en estándares acordados. Si no hay acuerdo, la revisión se vuelve personal, lenta y frustrante. El acuerdo de contribución elimina la fricción porque traslada la discusión de «yo creo que…» a «el estándar dice que…».
Los Pilares de un Acuerdo de Contribución de Élite
Un documento de este tipo debe ser exhaustivo. Basándonos en los estándares de arquitecturas robustas, estos son los puntos innegociables que debe tener tu archivo CONTRIBUTING.md:
1. Acuerdos de Software (El «Cómo»)
No basta con decir «programa bien». El acuerdo debe enlazar directamente a:
- Convenciones de código: Guías de estilo para Flutter, Angular o el stack que manejes.
- Estándar de Commits: ¿Usan Conventional Commits? ¿Prefieren Squash and Merge?
- Manejo de Ramas: Definición clara de GitFlow o Trunk Based Development.
- Documentación: Estándares para documentar nuevas características (ADRs, JSDoc, DartDoc).
2. El Modelo de Garantías (La Responsabilidad)
Este es el punto más crítico y el que separa a los equipos maduros de los improvisados. Contribuir código no es «entregar y olvidar».
- Periodos de Estabilización: Se deben definir tiempos claros (ej. X días en rama principal, Y días en estable). Durante este tiempo, el equipo contribuyente es el único responsable de dar soporte, corregir vulnerabilidades y resolver bugs de esa funcionalidad.
- Deuda Técnica Cero: El acuerdo debe ser tajante: No se aceptan aumentos en la deuda técnica. Si el software entra, entra limpio.
- Garantía de QA: Si un incidente ocurre en el proceso de estabilización, se debe documentar por qué el proceso de QA no lo detectó y ajustar los tests para que no vuelva a ocurrir.
3. Canales de Comunicación y Soporte
Para evitar el caos en Slack o Teams, el acuerdo define canales oficiales para:
- Informar errores (Issues).
- Reportar vulnerabilidades de seguridad (Canal privado).
- Sugerir nuevas funcionalidades (Features).
- Dudas de uso.
4. Programa de Despliegue y «Code Freeze»
La ingeniería profesional respeta los ciclos de estabilidad. Un acuerdo de contribución debe incluir las fechas tentativas de versiones estables.
La Regla de Oro: Si el periodo de estabilización de una tarea es de 2 semanas y falta solo 1 semana para el lanzamiento de la versión LTS, el PR no se acepta. Esto protege la estabilidad del sistema global frente a la urgencia de una sola célula.
Definición de Hecho (Definition of Done – DoD)
El acuerdo debe enlazar a un checklist de DoD. Nadie debería marcar un PR como «Listo para revisión» si no cumple con:
- Tests unitarios y de integración con cobertura acordada.
- Documentación técnica actualizada.
- Análisis estático de código (Linter) aprobado.
- Validación de accesibilidad (a11y) básica.
Conclusión: La Cultura sobre el Ego
El Contributing Agreement no es una herramienta de control, es una herramienta de autonomía. Cuando las reglas son claras y están por escrito, los desarrolladores no necesitan pedir permiso ni temer a las revisiones de código; simplemente siguen el mapa que el equipo trazó para el éxito.
Si quieres que tus contribuciones dejen de ser una fuente de estrés y empiecen a ser un motor de calidad, empieza por formalizar estos acuerdos. Tu «yo» del futuro, atendiendo un incidente a las 3:00 AM, te lo agradecerá.
¿Cómo implementar esto mañana?
- Copia el template que te compartí.
- Adáptalo a la realidad de tu equipo (ajusta los días de estabilización).
- Ponlo en la raíz de tu repositorio como
CONTRIBUTING.md. - Haz que leerlo sea parte del onboarding de cualquier nuevo integrante.
Template del contributing agreement
# Contributing Agreement
Este proyecto sigue la licencia descrita en el LICENSE.md (enlace al documento)
## Acuerdos de software (obligatorio)
Este proyecto esta basado en el siguiente código de conducta(enlace al CODE_OF_CONDUCT.md) y contamos con las siguiente convenciones
de código (enlace a la wiki donde explicamos nuestras convenciones) las pruebas de software deben seguir la siguiente convención
(enlace a la wiki donde explicamos nuestras convenciones). En este proyecto manejamos el siguiente estándar para el manejo de ramas (enlace wiki)
también manejamos el siguiente estándar de commits (enlace). Para realizar un PR exitoso consideramos que debes seguir los siguientes pasos (enlace).
Para escribir documentación de nuevas carácteristicas o cambios en alguna de ellas debemos seguir el siguiente estándar de documentación (enlace estándar).
## Modelo de Garantias (obligatorio)
Como equipo hemos llegado al acuerdo que una nueva contribución a la rama principal tendrá un tiempo de estabilización de X días y en la rama estable de Y días. Durante este tiempo todo equipo contribuyente dará soporte durante ese tiempo acordado, únicamente a la funcionalidad contribuida. Este soporte incluye solución de errores, vulnerabilidades y deuda técnica sobre los mismos. Esto también incluye los comentarios realizados por los maintainers. En caso de que se cumpla el tiempo y aún queden pendientes, se prorroga hasta que no existan comentarios ni pendientes sobre el software. Si para el momento, de realizar el lanzamiento de una versión estable no se ha dado solución, los cambios no saldrán hasta la siguiente versión estable y se reiniciará el periodo de estabilidad de la característica. En caso de encontrar un incidente sobre los cambios en proceso de estabilización se debe documentar por qué el incidente no se pudo detectar en momento de QA. La persona a cargo de QA debe evaluar si es posible una mejoría en el proceso. También se debe revisar los test pues los mismos deben mapear la mayoría de escenarios posibles. No se aceptará aumentos a la deuda técnica de software, por tanto debe ser igual a cero. En caso de que un equipo desee contribuir un cambio sobre una característica que no se ha estabilizado. Se reinicia y se delega al nuevo contribuyente la estabilidad de la misma durante el periodo acordado. No se aceptarán cambios en la rama principal, en caso tal que no se pueda cumplir el tiempo de estabilización por una próxima salida de una versión estable. Por ejemplo, para un equipo que considere que el periodo de estabilización es dos semanas si se propone un PR faltando una semana para la publicación de la rama estable, no se aceptaran hasta que se hay desplegado la versión lts. Se deben incluir datos de contacto del equipo que de soporte a la nueva característica. [Agregar acuerdos adicionales bajo el modelo de garantías).
## Canales de comunicación (obligatorio)
En este proyecto contamos con los siguientes canales de comunicación:
* Canal para informar errores (issues) (enlace al canal de comunicación) el horario de atención es:
* Canal para informar vulnerabilidades de software (enlace al canal) el horario de atención es:
* Canal para resolver dudas o inquietudes referentes al uso del software (enlace al canal) el horario de atención es:
* Canal para sugerir nuevas carácteristicas (features) a la solución (enlace) el horario de atención es:
## Programa de despliegue de versiones estables (opcional pero preferible)
Durante el 2023 y el 2024 tendremos las siguientes fechas tentativas de despliegue de versiones estables:
* Versión 6.x Octubre 23 del 2023
* Versión 7.x Marzo 23 del 2024
* Versión 8.x Septiembre 23 del 2024
Dado lo anterior no se aceptaran cambios sobre la rama principal en las fechas :
* del 8 al 23 de Octubre del 2023
* del 8 al 23 de Marzo del 2024
* del 8 al 23 de Septiembre del 2024
## Definición de hecho (Definition of Done) (opcional preferible)
## Roadmap de la solución (opcional preferible)
Estas son nuestras futuras features:
Para la versión 6.x se planea desplegar las siguientes características :
* Variante Botón
* Fix en ...
* ...
[Esta sección también puede vivir en un enlace externo y se pondrá el enlace a la misma]
## Maintainers (obligatorio)
Este documento fue creado por el equipo de Maintainers de la solución. Los actuales miembros al equipo de manteiners son:
* Nombre Completo A, Usurio de red
* Nombre Completo B, Usurio de red
* Nombre Completo C, Usurio de red
* Nombre Completo D, Usurio de red
* Nombre Completo E, Usurio de red
* Nombre Completo F, Usurio de red