Contribuir en Mercury

Introducción

Entendemos como contribuir en el core de Mercury cuando estamos trabajando para añadir alguna funcionalidad, aplicar algún fix o mejora al propio Mercury.

Requerimientos

  • NodeJS 16
  • Google Artifact Registry
  • YARN

Instalación de requerimientos

NodeJS

nvm para poder instalar y cambiar fácilmente entre versiones de NodeJS.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
nvm install 16

Google Artifact Registry

Tener NPM configurado para poder descargar paquetes de repositorio privado de google e instalar gestor de dependencias para Javascript.

npx google-artifactregistry-auth
npm install -g npm@9.4.0

YARN

YARN (alternativa a NPM, la cual es la usada en el proyecto)

npm install -g yarn

Preparación de entorno local

1. Clonar proyecto

Tras clonar el repositorio deo de Mercury:

git clone git@bitbucket.org:etailers/mercury.git

La estructura de directorios sería como la siguiente:

Estructura directorios de mercury.

Tenemos varios directorios destacados:

app
contiene las aplicaciones, las cuales usan Mercury. Por defecto viene la aplicación “demo” para un Adobe Commerce, y “docs” que contiene la documentación de Mercury.
packages
Contiene el código de los distintos paquetes que componen Mercury. Más adelante los veremos más detalladamente.

Los detalles de esta estructura de directorios los iremos viendo en la documentación.

2. Instalar paquetes

Una vez tengamos descargada la aplicación iremos al root del proyecto e instalaremos todos los paquetes:

npx google-artifactregistry-auth
yarn

Comandos

Podemos consultar los comandos disponibles en el fichero package.json del root de Mercury:

yarn dev
Inicializa Mercury en modo desarrollo con las aplicaciones por defecto: demo y docs.
yarn workspace @mercury/docs dev
Inicializa en modo desarrollo la aplicación de “docs”.
yarn dev:packages —filter=<app_name>
Inicializa Mercury en modo desarrollo para una aplicación en concreto, que no sea ni “demo” ni “docs”.
yarn build
Lo usaremos cuando queramos hacer “build” de la Mercury. Es recomendable ejecutarlo antes de hacer un “merge” de nuestras modificaciones para comprobar que no hay ningún error, y para testear la aplicación como si estuviéramos en modo producción.
yarn lint

Ejecuta el linter para poder encontrar errores en la aplicación.

yarn format

Formatea los archivos .ts, .tsx, .md del proyecto.

yarn publish-packages
TO DO
yarn install

Para descargar e instalar todos los paquetes.

yarn clear

Para limpiar la instalación. Después de este comando habrá que ejecutar “yarn” para que vuelva a instalar todos los paquetes.

yarn copy-to-base
TO DO
yarn copy-from-app <existing/app/path> <app_name>

Copia la aplicación que se encuentra en la ruta indicada al directorio “app” para poder ser usada para desarrollar en Mercury.

yarn copy-to-app <existing/app/path> <app_name>

Copia la aplicación <app_name> del directorio “app” de Mercury a la ruta indicada.

Importar aplicación

En muchas ocasiones cuando queremos desarrollar una mejora o algún fix de Mercury es por qué lo hemos encontrado trabajando en algún proyecto en concreto, y para reproducirlo necesitamos que Mercury se ejecute en ese entorno.

En estos casos lo que haremos es importar la aplicación a nuestra instalación de Mercury usando el comando **yarn copy-from-app. Por ejemplo:

yarn copy-from-app ~/Sites/eshop-horeca-front horeca

Este comando copia la aplicación Mercury del path ~/Sites/eshop-horeca-front al directorio apps/horeca

Estructura directorios de mercury apps.

Una vez tenemos la nueva aplicación deberemos coprobar si los siguientes archivos existen en el root de la misma:

  • tsconfig.json
  • tailwind.config.js
  • postcss.config.js

Si no existen los copiaremos de la aplicación “demo” y los añadiremos a la nueva aplicación.

Una vez esté la aplicación importada ya podremos arrancar Mercury para que use la aplicación importada y poder empezar a desarrollar en ese entorno.

yarn dev:packages --filter=horeca

Ahora ya podemos acceder a la aplicación desde el navegador. Deberemos asegurarnos que el Docker de la aplicación también esté inicializado.

Create Mercury App CLI

Una de las apps que componen a Mercury es la aplicación que se encarga de crear un nuevo proyecto de Mercury. Esta aplicación se encuentra en el directorio packages/create-mercury-app.

En caso de que queramos hacer alguna modificación en esta aplicación deberemos seguir los siguientes pasos.

1. Instalar el cli localmente

Para poder ejecutar el link apuntando a los ficheros locales precisamos instalar el cli localmente. Para ello ejecutaremos el siguiente comando:

yarn global add file:$(pwd)/packages/create-mercury-app

2. Inicializar modo desarrollador

yarn dev:packages

3. Verificar instalación

Una vez realizado los pasos ya deberíamos poder ejecutar el comando create-mercury-app desde cualquier directorio y crear una nueva aplicación de Mercury.

create-mercury-app -v

Desarrollar

Ahora que ya tenemos arrancado un entorno sobre el cual podemos probar nuestros desarrollos ya podemos empezar a implementar.

Crear rama

Crearemos una rama nueva a partir de la rama principal. Por ejemplo:

git checkout main
git pull
git checkout -b feature-nuevo_componente

Identificar paquete o paquetes donde intervenir

Como vimos anteriormente el código de Mercury lo componen los distintos paquetes que encontramos en el directorio “packages”.

Estructura directorios de mercury packages.
create-mercury-app

Implementa el comando de create-mercury-app para crear nuevas instalaciones de Mercury.

eslint-config-custom

Configuraciones custom de linter.

i18n

Implementa las traducciones de los textos de Mercury.

model

Implementa los modelos de las entidades usadas por Mercury

service-adobe-commerce

Implementa la capa de servicios y el proxy que sirve para conectarse a Adobe Commerce y convertir los datos a modelos de Mercury.

theme

Implementa el tema base de Mercury, es donde se encuentran todos los componentes, hooks, contextos, páginas y estilos.

tsconfig

Implementa configuración de Typescript.

ui

Implementa los componentes de la Ui de Mercury.

utils

Implementa métodos generales para user en Mercury.

Según la implementación que debamos llevar a cabo deberemos identificar en que paquete o paquetes deberemos trabajar.

Siguiendo con el ejemplo anterior, en que creamos una rama para crear un nuevo componente, deberíamos intervenir en el paquete “packages/theme”.

Publicar cambios

Una vez realizada la implementación y haberla probado la podemos publicar a Mercury para posteriormente poderla usar en el proyecto o los proyectos para el cual hemos requerido la funcionalidad. Por ejemplo:

git add .
git commit -m 'Creación de nuvo componente'
git push

Tras subir los cambios y haberlos “mergeado” a la rama principal de Mercury, ya podemos actualizar Mercury en el proyecto donde queremos añadir la nueva funcionalidad. Por ejemplo:

cd ~/Sites/eshop-horeca-front/
yarn upgrade-packages

Esto actualizará las versiones en el archivo yarn.lock del proyecto y tras comprobar que la modificación funciona ya podemos publicar los cambios al repositorio del proyecto.

Documentar

La documentación de Mercury se encuentra en apps/docs, se trata de una apliación hecha en Astro.

Inicializar documentación

Para inicialiar solo la aplicación de la documentación de Mercury podemos ejectuar el siguiente comando:

yarn workspace @mercury/docs dev

Tendremos la documentación accesible en http://127.0.0.1:3000/ y podremos ir visualizando ahí nuestros cambios.

Crear opciones de menú

Para añadir una opción en el menú lateral editaremos el objeto “Sidebar”:

apps/docs/src/consts.ts
...

export const SIDEBAR: Sidebar = {
  es: [
    {
      text: 'Introducción',
      link: '/es/introduccion'
    },

    {
      text: 'Básico',
      children: [
        { text: '¿Cómo funciona?', link: '/es/basico-como-funciona' },
        { text: 'Desarrollar con Mercury', link: '/es/desarrollar-con-mercury' },
        { text: 'Contribuir en Mercury', link: '/es/contribuir-en-mercury' },
        { text: 'Crear una aplicación Mercury', link: '/es/crear-una-aplicacion' }
      ]
    },
    {
      text: 'Framework',
      children: [
        { text: 'Theming', link: '/es/framework/theming' },
        { text: 'Páginas', link: '/es/framework/paginas' },
        { text: 'Componentes', link: '/es/framework/componentes' },
        { text: 'Service Layer', link: '/es/framework/services' }
      ]
    },
    {
      text: 'Integraciones',
      children: [
        {
          text: 'Adobe Commerce',
          children: [
            { text: 'Configuración Base', link: '/es/integraciones/adobe-commerce/configuracion-base' },
            { text: 'Module Api', link: '/es/integraciones/adobe-commerce/module-api' },
            { text: 'Module Cache', link: '/es/integraciones/adobe-commerce/module-cache' },
            { text: 'Module Redirects', link: '/es/integraciones/adobe-commerce/module-redirects' }
          ]
        }
      ]
    }
  ]
}

...

Crear página de contenido

Una vez tenemos la opción creada debemos crear la página a la cual enlaza. Por ejemplo:

apps/docs/src/content/docs/es/nueva-pagina.mdx
---
title: Nueva página de ejemplo
description: Nueva página de ejemplo para la documentación de Mercury.
---

## Sección 1

Introducción a la página de ejemplo, podemos usar markdown o HTML.

## Sección 2

Los titulares con ## delante aparece enlazados en la navegación lateral derecha.

### NodeJS

Los titulares sin ## aparecen como titulares, pero no en la navegación lateral derecha. 

También podemos usar imagenes tanto en HTML como en Markdown. 

Las imágenes deberán estar en el directorio **apps/docs/public**

<img src="/img/imagen-ejemplo.png" width="260" alt="Imagen de ejemplo."/>