Entendiendo codeowners

Source: Dev.to

¿Qué es el Archivo CODEOWNERS?

El archivo CODEOWNERS es un fichero especial en los repositorios de GitHub que define automáticamente a los individuos o equipos responsables de directorios, archivos o patrones específicos dentro de un repositorio.
Cuando un Pull Request modifica código cubierto por una regla de CODEOWNERS, los propietarios especificados se añaden automáticamente como revisores requeridos para ese Pull Request.

📍 Ubicación

Este archivo debe residir en una de las siguientes ubicaciones para que GitHub lo reconozca:

.github/CODEOWNERS   # ubicación recomendada
CODEOWNERS           # en la raíz del repositorio
docs/CODEOWNERS

Nota: La ubicación en .github/CODEOWNERS es preferida ya que mantiene los archivos de configuración del repositorio centralizados.

⚙️ Sintaxis y Funcionamiento

Estructura Básica

Cada línea contiene un patrón de ruta seguido de uno o más propietarios separados por espacios.

# Ejemplo de archivo CODEOWNERS

# 1. Todo el código en el repositorio, por defecto
* @octocat @github/support

# 2. Archivos en la raíz con extensión .md
*.md    @docs-team

# 3. Directorio 'src/frontend/' y todo lo que contiene
src/frontend/    @frontend-lead

# 4. Un archivo específico
config/database.yml    @backend-admin

# 5. Sobreescribiendo la propiedad para un subdirectorio
src/backend/users/ @user-management-team

Tipos de Propietarios

• Usuarios individuales: se especifican con su handle de GitHub, por ejemplo, @octocat.
• Equipos: se especifican usando la sintaxis de equipo de GitHub, por ejemplo, @organizacion/nombre-del-equipo. Esta es la opción más recomendada ya que simplifica la gestión de la propiedad cuando los miembros del equipo cambian.

Reglas de Precedencia

El archivo se procesa de arriba abajo; el último patrón coincidente para una ruta específica es el que se aplica.

• Menos específico: reglas que aparecen primero o usan patrones amplios.
• Más específico: reglas que aparecen al final y usan rutas más concretas, anulando las anteriores.

Ejemplo de precedencia:

# CODEOWNERS
# Línea 10 (Menos específica):
src/models/* @data-team

# Línea 50 (Más específica): ANULA la línea 10 para este archivo
src/models/user.js    @auth-squad

En este caso, un Pull Request que modifica src/models/user.js solo requerirá la revisión de @auth-squad, ignorando a @data-team.

🛡️ Integración con Ramas Protegidas

La verdadera potencia de CODEOWNERS se desbloquea al integrarlo con las Reglas de Protección de Ramas de GitHub. Al proteger una rama (por ejemplo, main o master), puedes habilitar la opción “Require review from Code Owners” (Requerir revisión de los Propietarios del Código).

Flujo de Trabajo con CODEOWNERS

1. Creación de la Pull Request: un desarrollador crea una PR que modifica archivos como src/billing/service.go y src/docs/README.md.
2. Asignación automática: GitHub analiza la PR:
   • src/billing/service.go coincide con src/billing/* @billing-team.
   • src/docs/README.md coincide con docs/*.md @documentation-team.
3. Revisores requeridos: GitHub añade automáticamente a @billing-team y @documentation-team como revisores obligatorios.
4. Fusión: la PR no puede fusionarse hasta que al menos un miembro de cada equipo propietario haya aprobado los cambios.

💡 Mejores Prácticas Esenciales

1. Usar Equipos, No Individuos

Asignar la propiedad a equipos (@org/team-name) en lugar de usuarios individuales (@user-handle) garantiza que:

• La revisión no se detenga si un individuo está de vacaciones o abandona la empresa.
• La propiedad y el conocimiento se distribuyan mejor dentro de un grupo funcional.

2. Definir una Regla de Fallback (Propietario por Defecto)

Incluye siempre una regla de ámbito amplio, por ejemplo:

# Propietarios por defecto para todo lo que no tiene una asignación específica
* @organizacion/core-team

Esto asegura que ningún cambio quede sin revisión y proporciona una capa de seguridad para archivos o rutas olvidadas.

3. Mantener el Archivo Actualizado

El archivo CODEOWNERS debe reflejar la estructura actual de tu equipo y código. Las reestructuraciones del proyecto o los cambios en el equipo deben ir acompañados de una actualización del archivo. Idealmente, los cambios en este archivo deberían ser revisados por un arquitecto o un líder técnico.

4. Ser Específico con Directorios

Evita reglas de coincidencia demasiado amplias. Utiliza la barra diagonal (/) para indicar la propiedad de todo el directorio y su contenido.

# MAL: Solo aplica a archivos en la raíz del directorio, no a subdirectorios
src/backend/*.js @js-team

# BIEN: Aplica a todo lo que esté dentro de 'src/backend/' (archivos y subdirectorios)
src/backend/ @backend-team

⚠️ Limitación crítica de CODEOWNERS: La rigidez basada en rutas

El sistema nativo de CODEOWNERS de GitHub está limitado a responder a la pregunta: “¿Qué archivo se modificó?” Esto genera tres desafíos importantes:

1. Ausencia de contexto de fusión
   CODEOWNERS es ciego al destino del cambio (rama de destino). No puedes requerir una revisión de un Arquitecto solo si la PR apunta a main, ni relajar reglas para un hotfix que solo apunta a staging. En resumen, no puedes asignar revisores basándote en la rama de destino.

2. Imposibilidad de requerimientos cruzados (Condiciones AND/OR)
   El sistema no puede combinar criterios. Una regla solo se aplica si se cumple una ruta, lo que impide establecer lógicas como:

   • AND: “Asigna al equipo de Seguridad SOLO SI la PR toca archivos en src/auth/ Y lleva la etiqueta security-review.”
   • OR: “Asigna al L…* (texto truncado en la fuente original).