¿Cómo debe organizarse un repositorio de GitHub en Magento 2?

Cuando se crea una instalación de Magento 2, existen muchas carpetas y archivos en el directorio de la instalación, esta guía es para entender cuáles archivos deben agregarse al repositorio de tu proyecto y cuales no son necesarios o hasta podrían ser problemáticos. 

El desarrollo eficiente en Magento 2 no solo requiere buenas prácticas de programación, sino también una correcta gestión del control de versiones y flujos de trabajo colaborativos. Una de las herramientas más efectivas para lograr esto es GitHub, una plataforma que permite administrar el código, hacer seguimiento de los cambios y mantener el orden en proyectos complejos. Contar con un repositorio bien organizado es fundamental para garantizar la escalabilidad, claridad y productividad del equipo al trabajar con soluciones basadas en Magento.

Los proyectos en Magento 2 suelen incluir múltiples módulos, temas personalizados, extensiones de terceros y archivos de configuración, lo que puede dificultar la gestión si no existe una estructura clara del repositorio. Definir convenciones para ramas, solicitudes de cambio (pull requests) y documentación permite que los equipos de desarrollo trabajen de forma más ordenada y eviten conflictos innecesarios.

Este artículo presenta las mejores prácticas para organizar un repositorio de GitHub en proyectos de Magento 2, abordando la estructura de carpetas, estrategias de ramificación y recomendaciones para documentar. Implementar una organización consistente y escalable del repositorio facilita la colaboración, minimiza errores y asegura una alta calidad del código durante todo el ciclo de vida del proyecto.

También se explicará a grandes rasgos cómo funciona el filesystem de magento y cuales recomendaciones sirven para optimizar tu repositorio de GitHub (o equivalente). Para una  comprensión ideal de este artículo, se recomienda tener un entendimiento básico de Git y GitHub (o alguna herramienta equivalente como GitLab o BitBucket), sin embargo, los conceptos a continuación son útiles para cualquiera que desee aprender acerca de los archivos y carpetas en un proyecto de Magento 2.

Antes que nada, vamos a listar el repositorio por defecto de Magento 2.4:

• composer.json: este archivo contiene la información de los módulos y sus dependencias del proyecto.
  
  
• composer.lock: este archivo especifica las versiones exactas de los componentes en el proyecto.
  
  
• .htaccess, pub/.htaccess, pub/media.htaccess y pub/static/.htaccess: los archivos .htaccess contienen información de encabezados y directivas para que el servidor pueda ejecutar las solicitudes de los usuarios en el sitio web.
  
  
• .gitignore: este archivo contiene las especificaciones de todos los archivos y directorios que no deben ser incluidos en el repositorio de git, ya sea porque son archivos generados en el proceso de compilación o consumen espacio innecesario en el repositorio.
  
  

Los archivos anteriores deben estar incluidos en nuestro repositorio siempre, pero además, es posible que también se incluyan los siguientes archivos o directorios:

• app/code: aquí se ubican los módulos del proyecto que no fueron instalados usando Composer.
  
  
• app/design: en esta carpeta se encuentran los temas disponibles en el comercio.
  
  
• app/etc: esta carpeta contiene configuraciones y variables del proyecto. Estos archivos pueden ser útiles en el repositorio parar tenerlos como respaldo, pero es importante tomar en consideración que en este directorio se encuentran archivos con datos sensibles o confidenciales, en particular el archivo app/etc/env.php, que contiene credenciales para accesar a la base de datos y el acceso al sitio administrativo. Esta carpeta solo debe incluirse en el repositorio si es privado y solo es accesible a personas autorizadas.
  
  
• pub/media: esta carpeta contiene las imágenes del catálogo, de los bloques de contenido y otros tipos de archivos públicos como PDFs o videos. Debido a esto, a menudo se excluyen del repositorio debido a las limitaciones de almacenamiento que proveen los repositorios remotos como GitHub. Para el almacenamiento de estos archivos, se recomienda utilizar servicios como Google Drive, Dropbox, AWS S3, etc.
  
  
  
  >> ¿Cómo realizar el proceso de carga de productos en Adobe Commerce? <<
  
  
  

Archivos y carpetas que debes evitar agregar en el repositorio (deben estar en el archivo .gitignore):

• pub/static (excepto .htaccess): aquí se encuentran los archivos estáticos generados en el proceso de setup:static-content:deploy, por lo que cargarlos al repositorio es innecesario.
  
  
• generated: el contenido de esta carpeta es auto-generado en el proceso de compilación del sitio, por lo que no hay motivo para agregarlos al repositorio.
  
  
• var: los contenidos de esta carpeta a menudo son de carácter temporal o de registro de bitacoras y reportes. Puede resultar útil respaldar esta carpeta pero se recomienda utilizar un servicio de almacenamiento dedicado, ya que pueden ser grandes y volátiles, por lo que no se recomienda agregarlos al repositorio.
  
  
• vendor: el contenido de esta carpeta no debe ser modificado manualmente, sólo con composer, por lo que agregar los archivos composer.json y composer.lock son suficientes para determinar el contenido del directorio vendor, sin necesidad de agregar el código en sí.
  
  
• lib: aquí hay librerías utilizadas en módulos y componentes, podría ser necesario agregarlo al repositorio, pero se recomienda utilizar composer para la orquestación de las librerías, en cuyo caso, al igual que con la carpeta vendor, no es necesario agregar el código en sí.
  
  

Finalmente, las siguientes recomendaciones pueden facilitar la administración del código y recursos del repositorio y evitar errores:

• Utilizar branches para cada modificación: crear un branch es rápido y fácil, sin mencionar que permite controlar las versiones, realizar pruebas de integración y analizar modificaciones más ordenadamente... y por supuesto, evitar subir errores fatales a la master branch.
  
  
• Mantener consistencia entre los ambientes de desarrollo y producción (u otros): es común que con el tiempo, los diferentes ambientes empiecen a acumular diferencias, ya que no están en los mismos commits o versiones del repositorio. Cuando existen muchas inconsistencias entre los diferentes ambientes, es una señal de malas prácticas de desarrollo, ya que para realizar pruebas y modificaciones, es importante tener ambientes lo más idénticos posibles. Este procedimiento de desarrollo y despliegue es pertinente al ámbito de DevOps, el cual es utilizado para agilizar procesos de desarrollo, integración y pruebas, y reducir posibles errores en el proceso.
  
  
• Agrega un archivo README.md: este archivo es meramente para explicar la naturaleza y contenido del repositorio, sirve para ayudar a nuevos colaboradores a entender y utilizar el código efectivamente.
  
  
• Escribe mensajes commits significativos: evita commits genéricos tal como "bugfix" o "cambios v4", ya que no permiten a otras personas entender o identificar a simple vista el propósito del cambio. Además, todos olvidamos algunas cosas con el paso del tiempo, entonces toma unos segundos extra para escribir mensajes claros y significativos cada vez que vayas a realizar un commit.
  
  

Espero que este artículo haya sido útil para entender cómo organizar un repositorio de GitHub en Magento 2, recuerda que todos los proyectos son diferentes y no existen reglas definitivas de que puedes agregar y que no, sin embargo si aplicas los conceptos explicados anteriormente, puedes evitar varios problemas en el camino y trabajar de manera más ordenada y segura.