From d7d2c49f1db7581298c4a44d5c3279e75541c957 Mon Sep 17 00:00:00 2001 From: Sergio Orozco Date: Sun, 15 Feb 2026 18:27:32 -0500 Subject: [PATCH 1/3] =?UTF-8?q?Creaci=C3=B3n=20ADR=20retrospectivos?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/adr/R01-fundacion-sitio-jekyll.md | 157 +++++++++++++ docs/adr/R02-migracion-jekyll-a-gatsby.md | 231 +++++++++++++++++++ docs/adr/R03-migracion-gatsby-a-astro.md | 258 ++++++++++++++++++++++ docs/adr/README.md | 17 ++ 4 files changed, 663 insertions(+) create mode 100644 docs/adr/R01-fundacion-sitio-jekyll.md create mode 100644 docs/adr/R02-migracion-jekyll-a-gatsby.md create mode 100644 docs/adr/R03-migracion-gatsby-a-astro.md diff --git a/docs/adr/R01-fundacion-sitio-jekyll.md b/docs/adr/R01-fundacion-sitio-jekyll.md new file mode 100644 index 0000000..321d6ce --- /dev/null +++ b/docs/adr/R01-fundacion-sitio-jekyll.md @@ -0,0 +1,157 @@ +# ADR R01: Fundación del sitio personal con Jekyll + +> **Estado:** Reemplazada → [R02](R02-migracion-jekyll-a-gatsby.md) +> **Fecha original:** 2016-04 (reconstruido retrospectivamente 2026-02) +> **Categoría:** Plataforma / SSG / Quality +> **Repositorio:** `secorto.com_jekyll` (423 commits, 2016–2023) + +--- + +## Contexto + +En marzo de 2016 se inició el desarrollo de un sitio web personal con el +objetivo de practicar desarrollo front-end y tener presencia profesional +en línea. El primer intento usó **Lektor** (SSG basado en Python) durante +apenas dos semanas (~8 commits, 16–17 mar 2016) antes de descartarse por +falta de ecosistema y documentación en español. + +Se necesitaba un generador de sitios estáticos que: + +- Tuviera ecosistema maduro de temas y plugins +- Permitiera escribir contenido en Markdown +- Se pudiera desplegar gratuitamente (GitHub Pages) +- Tuviera buena documentación + +--- + +## Decisión + +Adoptar **Jekyll** como generador de sitios estáticos, desplegado inicialmente +en GitHub Pages y luego migrado a Netlify. + +### Evolución del stack (fases) + +#### Fase 1 — Jekyll + Gulp + Bootstrap (abr 2016) + +- Migración completa de Lektor a Jekyll con Gulp como task runner +- Bootstrap 3, Sass, jQuery +- Bower para dependencias frontend +- Dominio `scot3004.xyz` +- CI: Travis CI (Ruby 2.5 + Node.js 8) + +#### Fase 2 — Bower → NPM (jun 2016, tags v1.2.x–v1.3.x) + +- Bower eliminado, dependencias movidas a NPM +- Scripts NPM reemplazan parcialmente a Gulp +- `html-proofer` integrado como `lint:html` +- `imagemin-cli` para optimización de imágenes + +#### Fase 3 — Dominio propio (2017) + +- Migración de `scot3004.xyz` a `secorto.com` +- SEO tags, Open Graph, formulario de contacto +- Notice de cookies, reCAPTCHA + +#### Fase 4 — Minimal Mistakes + Netlify (sep-oct 2018, tag v2.0.0) + +- Tema cambiado de custom a `minimal-mistakes-jekyll` (gema Ruby) +- Eliminación de todo el CSS/HTML personalizado +- Deploy migrado de GitHub Pages a **Netlify** +- **Netlify CMS** integrado (editorial workflow: draft → review → publish) +- Gulpfile eliminado definitivamente + +#### Fase 5 — Mantenimiento (2019–2020) + +- Remark lint para Markdown +- Portafolio con entradas de PyCon +- Bumps de dependencias vía Dependabot +- Último commit funcional: marzo 2020 + +#### Fase 6 — Deprecación (2023) + +- Commit final advirtiendo migración al nuevo repositorio (Astro) + +### Estrategia de calidad + +El comando `npm test` ejecutaba exclusivamente **linters y validación +estática** — no existían tests unitarios: + +| Herramienta | Tipo | Alcance | +|---|---|---| +| **html-proofer** | Validación HTML post-build | Enlaces rotos, alt vacíos, HTML válido | +| **ESLint** | Linter JS | `.eslintrc.yaml` con 207 líneas de reglas, complejidad máx 6 | +| **scss-lint** | Linter SCSS | `_sass/**/*.scss` | +| **remark-lint** | Linter Markdown | Preset recommended + frontmatter | +| **CodeClimate** | Análisis estático | Duplication (JS, Ruby), eslint, fixme, rubocop, scss-lint | + +Pipeline CI (Travis CI): + +``` +gem install bundler → bundle install → npm install +→ jekyll build → npm run test (= lint:js + lint:css + lint:html + lint:md) +``` + +Variable de entorno crítica: `NOKOGIRI_USE_SYSTEM_LIBRARIES=true` — necesaria +porque `html-proofer` dependía de **Nokogiri** (parser XML/HTML con binding +nativo en C), que era problemático de compilar en diferentes entornos. + +### Contenido + +- **17 posts** (2010–2018, los de 2010–2011 migrados desde Blogger) +- **3 entradas de portafolio** (pybaq, pycon, scot3004) +- **6 páginas** (404, archive, categories, contacto, portafolio, tags) +- Datos estructurados: `navigation.yml`, `timeline.yml` + +--- + +## Alternativas consideradas + +| Alternativa | Razón de descarte | +|---|---| +| **Lektor** (Python) | Ecosistema limitado, poca documentación, comunidad pequeña | +| **WordPress** | Requiere hosting dinámico, no alineado con práctica de front-end | +| **HTML estático** | No escala para blog con múltiples posts | + +--- + +## Consecuencias + +### Positivas + +- Jekyll era el SSG más maduro en 2016 con integración nativa en GitHub Pages +- Minimal Mistakes proporcionó un diseño profesional sin esfuerzo de CSS +- Netlify CMS permitió edición de contenido sin tocar código +- Los linters mantuvieron calidad básica del código +- `html-proofer` detectaba enlaces rotos antes del deploy + +### Negativas + +- **Nokogiri** se volvió un dolor de cabeza recurrente: compilación nativa + fallaba frecuentemente en CI y en diferentes sistemas operativos +- Sin tests unitarios — la calidad dependía 100% de linting estático +- El stack Ruby + Node.js duplicaba la complejidad del entorno de desarrollo +- Jekyll carecía de componentización moderna (Liquid tiene limitaciones) +- La falta de tipado hacía difícil refactorizar con confianza +- Minimal Mistakes, al ser una gema, ocultaba la estructura interna y + dificultaba personalizaciones profundas + +### Métricas del repositorio + +| Métrica | Valor | +|---|---| +| Commits totales | 423 | +| Período activo | 2016-04 a 2020-03 (~4 años) | +| Tags de versión | v1.2.1, v1.2.2, v1.3.1, v1.3.2, v2.0.0 | +| CI | Travis CI | +| Deploy | GitHub Pages → Netlify | +| Último commit | 2023-03-04 (aviso de deprecación) | + +--- + +## Referencias + +- Repositorio: `secorto.com_jekyll/` +- [Jekyll](https://jekyllrb.com/) +- [Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/) +- [html-proofer](https://github.com/gjtorikian/html-proofer) +- [Nokogiri](https://nokogiri.org/) diff --git a/docs/adr/R02-migracion-jekyll-a-gatsby.md b/docs/adr/R02-migracion-jekyll-a-gatsby.md new file mode 100644 index 0000000..fc0ee39 --- /dev/null +++ b/docs/adr/R02-migracion-jekyll-a-gatsby.md @@ -0,0 +1,231 @@ +# ADR R02: Migración de Jekyll a Gatsby + +> **Estado:** Reemplazada → [R03](R03-migracion-gatsby-a-astro.md) +> **Fecha original:** 2021-03 (reconstruido retrospectivamente 2026-02) +> **Categoría:** Plataforma / SSG / Testing / Quality +> **Repositorio:** `web2021` (111 commits, 2021–2023) + +--- + +## Contexto + +Después de ~4 años con Jekyll ([ADR R01](R01-fundacion-sitio-jekyll.md)), +el sitio enfrentaba múltiples fricciones: + +### Problemas con Nokogiri + +`html-proofer` — la herramienta central de validación de calidad — dependía +de **Nokogiri**, un parser XML/HTML con bindings nativos en C. Compilar +Nokogiri era un proceso frágil: + +- Fallaba frecuentemente en CI (Travis CI) requiriendo + `NOKOGIRI_USE_SYSTEM_LIBRARIES=true` +- Diferentes versiones de `libxml2`/`libxslt` en el sistema generaban + errores crípticos +- Actualizaciones de Ruby o del SO rompían la compilación nativa +- El stack dual Ruby + Node.js multiplicaba los puntos de fallo + +### Deseo de mayor estructura + +Jekyll con Liquid ofrecía poca componentización: + +- No había componentes reutilizables con props tipados +- La lógica de templates era difícil de testear +- No existía sistema de tipos — los errores se detectaban en runtime (build) +- El código CSS/HTML estaba acoplado al tema Minimal Mistakes (gema opaca) + +### Motivación personal + +- Practicar React y el ecosistema moderno de JavaScript +- Tener una base más estructurada y componentizada +- Poder escribir tests unitarios reales (no solo linters) + +--- + +## Decisión + +Migrar a **Gatsby** (v5) con React 18, Theme UI para estilos, MDX para +contenido, y Jest + Cypress como frameworks de testing. + +### Stack adoptado + +| Capa | Tecnología | Reemplaza a | +|---|---|---| +| SSG | Gatsby 5 | Jekyll | +| UI | React 18 | Liquid templates | +| Estilos | Theme UI 0.16 + Emotion | Sass + Minimal Mistakes | +| Contenido | MDX v5 (`.mdx` y `.md`) | Markdown + Liquid | +| Imágenes | gatsby-plugin-image + sharp | imagemin-cli | +| SVG | @svgr/webpack (componentes React) | Archivos estáticos | +| Color modes | Dark/Light via Theme UI | No existía | +| PWA | gatsby-plugin-manifest + offline | No existía | +| Tests unitarios | **Jest 29 + jsdom + Emotion serializer** | No existían | +| Tests E2E | **Cypress 12 + cypress-axe** | html-proofer | +| Linting | ESLint 8 + react-app + MDX plugin | ESLint + scss-lint + remark | +| Formatting | Prettier 3 | No existía | +| CI | **GitHub Actions** | Travis CI | +| Deploy | Netlify | Netlify (se mantuvo) | +| Dev env | DevContainer (Node 18) | Local únicamente | + +### Arquitectura de la aplicación + +``` +src/ +├── assets/ → Recursos estáticos (avatar, logo, iconos) +├── blocks/ → Contenido MDX como bloques (about.mdx) +├── components/ → Componentes React (Bio, Blog, Footer, Gallery, etc.) +├── constants.ts → Constantes (MAIN_CONTENT_ID) +├── containers/ → Layout, SEO, PostFooter +├── context/ → SidebarContext (React Context) +├── hooks/ → use-avatar, use-site-metadata +├── pages/ → 404, blog, index, portafolio +├── templates/ → blog-template, page-template, portafolio-template +├── theme/ → Colors, typography, styles (Theme UI) +└── types/ → Declaraciones TypeScript +``` + +### Generación de páginas (`gatsby-node.js`) + +Gatsby usaba **GraphQL** para consultar contenido y generar páginas +estáticamente. El archivo `gatsby-node.js` ejecutaba: + +1. `onCreateNode`: interceptaba nodos MDX, extraía `sourceInstanceName` + del padre y creaba campos `slug` y `collection` +2. `createPages`: dos queries GraphQL separadas (blog + portafolio), + cada post recibía contexto con `previous` y `next` para navegación +3. `onCreateWebpackConfig`: configuraba @svgr/webpack en los 4 stages + +El **cross-referencing** de posts (previous/next) requería resolver +relaciones en GraphQL durante el build, contribuyendo a tiempos de +compilación de **~3 minutos**. + +### Estrategia de testing + +#### Jest — Tests unitarios con snapshot testing + +```javascript +// jest.config.js +module.exports = { + testEnvironment: 'jsdom', + transform: { '^.+\\.[jt]sx?$': '/jest-preprocess.js' }, + moduleNameMapper: { + '.+\\.(css|style)$': 'identity-obj-proxy', + '.+\\.(jpg|png|gif|svg)$': '/__mocks__/file-mock.js' + }, + snapshotSerializers: ['@emotion/jest/serializer'] +} +``` + +- **Snapshot testing**: verificaba que los componentes renderizaran + consistentemente (SEO, layouts) +- `react-test-renderer` para renderizado sin DOM +- `identity-obj-proxy` para mockear CSS modules +- Mock completo de Gatsby (`__mocks__/gatsby.js`): `useStaticQuery`, + `graphql`, `Link`, `navigate`, `StaticImage` +- `@emotion/jest/serializer` para snapshots legibles de estilos Emotion + +#### Cypress — Tests E2E de accesibilidad + +```javascript +// cypress/e2e/accessibility.cy.js +// Tests de a11y con axe-core en modo oscuro y claro +``` + +- `cypress-axe` + `axe-core` para auditoría de accesibilidad +- `@testing-library/cypress` para queries semánticas +- Solo un spec file: accesibilidad en ambos color modes +- No se usó Cypress Cloud (evitando el límite de 500 ejecuciones/mes + que luego motivaría el [ADR 002](002-testing-framework-migration.md)) + +#### Pipeline CI (GitHub Actions) + +```yaml +# .github/workflows/tests.yml +name: Jest +on: push +jobs: + test: + steps: + - yarn install --frozen-lockfile + - yarn lint # ESLint (JS, JSX, MD, MDX) + - yarn test:unit # Jest +``` + +Solo lint + unit tests en CI. E2E se ejecutaba localmente o via Netlify +deploy previews. + +### Contenido migrado + +- **17 posts de blog** (mismos que Jekyll, convertidos de `.md` a MDX) +- **3 entradas de portafolio** (pybaq, perficient, scot3004) +- **Timeline profesional** (`content/timeline.yml`) +- Se mantuvo un solo idioma (español) + +--- + +## Alternativas consideradas + +| Alternativa | Razón de descarte | +|---|---| +| **Next.js** | Orientado a apps dinámicas con SSR; el sitio es 100% estático | +| **Hugo** | Go templates menos expresivos que JSX; sin ecosistema npm nativo | +| **Eleventy** | Más simple pero sin el ecosistema de componentes React | +| **Mantener Jekyll** | Nokogiri y la falta de componentización eran bloqueos | + +--- + +## Consecuencias + +### Positivas + +- **Componentes React** permitieron estructura modular y reutilizable +- **Theme UI** proporcionó dark mode, sistema de diseño tipado y + estilos consistentes +- **Jest con snapshots** introdujo tests unitarios por primera vez en + el proyecto — verificación automática de regresiones visuales +- **Cypress + axe-core** automatizó auditorías de accesibilidad +- **TypeScript parcial** (migración gradual) mejoró la confiabilidad +- **DevContainer** estandarizó el entorno de desarrollo +- **MDX** permitió React dentro del Markdown (componentes interactivos) +- Se eliminó la dependencia de Ruby y Nokogiri completamente + +### Negativas + +- **Dependencias inestables**: las actualizaciones de Gatsby y sus ~34 + plugins generaban conflictos frecuentes que retrasaban deploys. Snyk + reportó múltiples vulnerabilidades (9 commits de snyk-bot) +- **Builds de ~3 minutos**: el cross-referencing de posts via GraphQL + y la generación de imágenes con sharp alargaban el pipeline +- **GraphQL overhead**: consultas complejas para datos que podrían ser + simples archivos de configuración +- **Pocas actualizaciones de contenido**: el proyecto tenía baja + frecuencia de cambios, lo que hacía el overhead de Gatsby desproporcionado +- **gatsby-node.js monolítico**: toda la lógica de generación en un solo + archivo sin tipado +- **Snapshot testing frágil**: los snapshots se rompían con cambios + cosméticos, generando falsos positivos +- **Webpack opaco**: la configuración de webpack estaba abstraída por + Gatsby, dificultando optimizaciones + +### Métricas del repositorio + +| Métrica | Valor | +|---|---| +| Commits totales | 111 | +| Período activo | 2021-03 a 2023-07 (~2 años 4 meses) | +| Tags de versión | Ninguno | +| Versión final | 4.2.0 (package.json) | +| CI | GitHub Actions (lint + unit tests) | +| Deploy | Netlify | +| Último commit | 2023-07-20 (upgrade dependencias) | + +--- + +## Referencias + +- Repositorio: `web2021/` +- [ADR R01 — Jekyll](R01-fundacion-sitio-jekyll.md) (decisión reemplazada) +- [Gatsby](https://www.gatsbyjs.com/) +- [Theme UI](https://theme-ui.com/) +- [Jest Snapshot Testing](https://jestjs.io/docs/snapshot-testing) +- [cypress-axe](https://github.com/component-driven/cypress-axe) diff --git a/docs/adr/R03-migracion-gatsby-a-astro.md b/docs/adr/R03-migracion-gatsby-a-astro.md new file mode 100644 index 0000000..8736f6a --- /dev/null +++ b/docs/adr/R03-migracion-gatsby-a-astro.md @@ -0,0 +1,258 @@ +# ADR R03: Migración de Gatsby a Astro + +> **Estado:** Aceptada +> **Fecha original:** 2024-05 (reconstruido retrospectivamente 2026-02) +> **Categoría:** Plataforma / SSG / Testing / i18n +> **Repositorio:** `secorto_web` (502+ commits, 2024–presente) + +--- + +## Contexto + +Después de ~2 años con Gatsby ([ADR R02](R02-migracion-jekyll-a-gatsby.md)), +el sitio enfrentaba problemas sistémicos que hacían insostenible el +mantenimiento: + +### Infierno de dependencias + +Gatsby 5 dependía de **~34 plugins** (`gatsby-plugin-*`, +`gatsby-transformer-*`, `gatsby-remark-*`) cada uno con su propio ciclo de +releases. Las actualizaciones de dependencias generaban conflictos +frecuentes: + +- **Snyk reportaba vulnerabilidades** constantemente (9 commits de + `snyk-bot` solo para parches de seguridad) +- Un upgrade de un plugin podía romper la compatibilidad con otros +- Los deploy previews de Netlify fallaban por dependencias rotas +- El `yarn.lock` tenía conflictos de merge recurrentes + +### Builds lentos (~3 minutos) + +El pipeline de build tardaba aproximadamente **3 minutos** debido a: + +1. **Cross-referencing de posts**: `gatsby-node.js` ejecutaba queries + GraphQL separadas para blog y portafolio, resolviendo `previous`/`next` + para cada post +2. **Procesamiento de imágenes**: `sharp` + `gatsby-plugin-image` generaba + múltiples resoluciones de cada imagen +3. **Webpack bundling**: 4 stages de webpack (develop, develop-html, + build-html, build-javascript) con configuración custom para SVG +4. **GraphQL schema inference**: Gatsby infería el schema de GraphQL de + todo el contenido en cada build + +### Baja frecuencia de actualizaciones + +El sitio tenía pocas actualizaciones de contenido. El último post nuevo +databa de 2022. La relación esfuerzo de mantenimiento vs. contenido nuevo +era desproporcionada — se pasaba más tiempo actualizando dependencias que +escribiendo contenido. + +### Limitaciones arquitectónicas + +- **gatsby-node.js monolítico**: toda la lógica de generación de páginas + en un archivo sin tipado fuerte +- **GraphQL obligatorio**: incluso para datos simples como metadatos del + sitio, se requería una query GraphQL +- **Snapshot testing frágil**: los snapshots de Jest se rompían con + cualquier cambio cosmético, generando falsos positivos +- **Gatsby en declive**: menor actividad del ecosistema, plugins sin + mantener, comunidad migrando a otros frameworks + +--- + +## Decisión + +Migrar a **Astro** como generador de sitios estáticos, aprovechando su +modelo de zero-JS-by-default, Content Collections tipadas, y +enrutamiento basado en archivos. + +### ¿Por qué Astro? + +| Criterio | Gatsby | Astro | +|---|---|---| +| JS en cliente | React hydration completo | Zero JS por defecto | +| Datos | GraphQL obligatorio | Content Collections tipadas | +| Build speed | ~3 min (GraphQL + webpack) | ~30 s (Vite + esbuild) | +| Plugins necesarios | ~34 | ~3 (sitemap, expressive-code) | +| Tipado | Parcial (migración gradual) | TypeScript strict nativo | +| i18n | No implementado | Soporte built-in con prefixDefaultLocale | +| Dependencias | Ecosistema pesado | Ecosistema liviano | + +### Fases de la migración + +#### Fase 1 — Bootstrap (30 mayo 2024) + +El proyecto nació siguiendo el tutorial oficial de Astro (unidades 1–5: +páginas, componentes, layouts, blog, tags, RSS) en una sola sesión. Se +creó la estructura base y se migraron los posts del blog Jekyll/Gatsby. + +#### Fase 2 — Migración de contenido y secciones + +Se expandieron las colecciones de contenido más allá de blog y portafolio: + +| Colección | Descripción | +|---|---| +| `blog` | Posts del blog (migrados desde Jekyll/Gatsby) | +| `talk` | Charlas y conferencias | +| `work` | Experiencia laboral | +| `projects` | Proyectos personales | +| `community` | Participación en comunidades | + +#### Fase 3 — Testing con Cypress (pre-i18n) + +Inicialmente se adoptó **Cypress** como framework E2E, manteniendo +continuidad con Gatsby: + +- Tests de accesibilidad con `cypress-axe` +- Tests funcionales básicos de navegación +- Sin tests unitarios en esta fase + +Esta fue una decisión pragmática: reutilizar el conocimiento existente +de Cypress mientras se estabilizaba la nueva plataforma. + +#### Fase 4 — Internacionalización (i18n) + +Implementación del sistema multilingüe español/inglés — la primera vez +que el sitio soportaba más de un idioma. Documentado en detalle en +[ADR 001](001-i18n-router-framework.md): + +- Router polimórfico basado en configuración +- Aliasing de rutas por idioma (`/es/charla/` ↔ `/en/talk/`) +- 3 archivos dinámicos reemplazaron ~8 archivos de página +- Reducción de duplicación del 95% al 0% + +#### Fase 5 — Migración de testing (post-i18n) + +La complejidad del i18n evidenció las limitaciones de Cypress y la +ausencia de tests unitarios. Documentado en +[ADR 002](002-testing-framework-migration.md): + +- **Playwright** reemplazó a Cypress para E2E (multi-browser, sin límite + de ejecuciones) +- **Vitest** se adoptó como framework unitario (165+ tests, 100% cobertura) +- Mocks de terceros para E2E determinísticos + ([ADR 003](003-third-party-mocks.md)) + +### Stack final + +| Capa | Tecnología | Reemplaza a | +|---|---|---| +| SSG | Astro 5 | Gatsby 5 | +| Lenguaje | TypeScript (strict, zero `any`) | TypeScript parcial | +| Contenido | Content Collections + Markdown | MDX + GraphQL | +| Estilos | CSS nativo + variables | Theme UI + Emotion | +| Imágenes | Astro Image (built-in) | gatsby-plugin-image + sharp | +| Code blocks | astro-expressive-code | No existía | +| Comentarios | Giscus | No existía | +| Galería | PhotoSwipe 5 | PhotoSwipe 5 (se mantuvo) | +| Tests unitarios | **Vitest 4** (165+ tests) | Jest 29 (snapshots) | +| Tests E2E | **Playwright 1.58** (3 browsers) | Cypress 12 (1 spec) | +| Linting | ESLint 9 (flat config) | ESLint 8 | +| CI | GitHub Actions (2 jobs paralelos) | GitHub Actions (1 job) | +| Deploy | Netlify | Netlify (se mantuvo) | +| i18n | Built-in Astro + router custom | No existía | + +### Estrategia de calidad — evolución completa + +``` +Jekyll (2016) → Linters + html-proofer (validación estática) +Gatsby (2021) → Jest snapshots + Cypress a11y (tests básicos) +Astro pre-i18n → Cypress E2E (continuidad) +Astro post-i18n → Playwright E2E + Vitest unitarios (cobertura completa) +``` + +--- + +## Alternativas consideradas + +| Alternativa | Razón de descarte | +|---|---| +| **Next.js** | SSR/ISR innecesario para sitio estático; mayor complejidad | +| **Eleventy** | Sin tipado nativo, sin Content Collections | +| **SvelteKit** | Curva de aprendizaje de Svelte, ecosistema menos maduro para blogs | +| **Mantener Gatsby** | Dependencias insostenibles, builds lentos, ecosistema en declive | +| **Volver a Jekyll** | Los problemas originales (Nokogiri, falta de tipos) persistían | + +--- + +## Consecuencias + +### Positivas + +- **Builds ~6× más rápidos**: de ~3 min a ~30 s gracias a Vite/esbuild +- **Zero JavaScript por defecto**: el sitio es HTML/CSS puro excepto donde + se necesita interactividad (Giscus, PhotoSwipe, theme toggle) +- **Content Collections tipadas**: schema Zod con validación en build-time, + incluyendo estados de traducción y changelog estructurado +- **TypeScript strict sin `any`**: confiabilidad completa del sistema de tipos +- **i18n nativo**: primer soporte multilingüe en la historia del proyecto +- **Testing maduro**: de 0 tests unitarios a 165+ con 100% de cobertura; + de 1 spec E2E a suite completa multi-browser +- **Dependencias mínimas**: ~3 integraciones Astro vs ~34 plugins Gatsby +- **ADRs formales**: primera vez que se documentan decisiones arquitectónicas +- **Escalabilidad O(1)**: agregar una sección nueva requiere solo una + entrada en `sections.ts` + +### Negativas + +- **Cypress legacy pendiente**: la migración de Cypress no está completa; + la configuración y dependencia aún existen en el proyecto +- **Sin React**: se perdieron los componentes React existentes (reescritos + como componentes Astro) +- **Curva de aprendizaje**: Astro tiene convenciones propias (frontmatter + script, slots, directivas `client:*`) +- **Ecosystem más joven**: menos plugins de terceros que Gatsby/Next.js + +### Métricas del repositorio + +| Métrica | Valor | +|---|---| +| Commits totales | 502+ | +| Período activo | 2024-05 a presente | +| Colecciones de contenido | 5 (blog, talk, work, projects, community) | +| Idiomas | 2 (es, en) | +| Tests unitarios | 165+ (100% cobertura) | +| Tests E2E | Suite completa (Chromium, Firefox, WebKit) | +| ADRs | 5 formales + 3 retrospectivos | +| CI jobs | 2 paralelos (unit + E2E) | + +--- + +## Línea temporal completa del proyecto + +``` +2016-03 ┌─ Lektor (Python) — 2 semanas, descartado +2016-04 ├─ Jekyll — R01 + │ ├─ Gulp + Bootstrap + Bower + │ ├─ NPM scripts + html-proofer + │ ├─ secorto.com domain + │ ├─ Minimal Mistakes + Netlify CMS (v2.0.0) + │ └─ Mantenimiento hasta 2020 +2021-03 ├─ Gatsby — R02 + │ ├─ React 18 + Theme UI + MDX + │ ├─ Jest snapshots + Cypress a11y + │ ├─ GitHub Actions CI + │ ├─ TypeScript parcial + │ └─ Último commit: 2023-07 +2024-05 └─ Astro — R03 (actual) + ├─ Content Collections + TypeScript strict + ├─ Cypress (pre-i18n) + ├─ i18n español/inglés — ADR 001 + ├─ Playwright + Vitest — ADR 002 + ├─ Mocks de terceros — ADR 003 + ├─ Linting + zero any — ADR 004 + └─ 502+ commits, 165+ tests, 100% cobertura +``` + +--- + +## Referencias + +- Repositorio actual: `secorto_web/` +- Repositorio Gatsby: `web2021/` +- Repositorio Jekyll: `secorto.com_jekyll/` +- [ADR R01 — Jekyll](R01-fundacion-sitio-jekyll.md) +- [ADR R02 — Gatsby](R02-migracion-jekyll-a-gatsby.md) +- [ADR 001 — i18n y router polimórfico](001-i18n-router-framework.md) +- [ADR 002 — Migración Cypress → Playwright + Vitest](002-testing-framework-migration.md) +- [Astro](https://astro.build/) diff --git a/docs/adr/README.md b/docs/adr/README.md index b6d5ded..783d45b 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -8,6 +8,20 @@ simplificada del [formato de Michael Nygard](https://cognitect.com/blog/2011/11/ ## Índice +### ADRs retrospectivos + +Decisiones reconstruidas a partir del historial git de los repositorios +anteriores (`secorto.com_jekyll`, `web2021`). Documentan la evolución +completa del proyecto a través de tres reescrituras en diferentes frameworks. + +| # | Título | Estado | Fecha original | +|---|--------|--------|----------------| +| [R01](R01-fundacion-sitio-jekyll.md) | Fundación del sitio personal con Jekyll | Reemplazada → R02 | 2016-04 | +| [R02](R02-migracion-jekyll-a-gatsby.md) | Migración de Jekyll a Gatsby | Reemplazada → R03 | 2021-03 | +| [R03](R03-migracion-gatsby-a-astro.md) | Migración de Gatsby a Astro | Aceptada | 2024-05 | + +### ADRs del proyecto actual + | # | Título | Estado | Fecha | |---|--------|--------|-------| | [001](001-i18n-router-framework.md) | Framework i18n y router polimórfico de secciones | Aceptada | 2025-06 | @@ -19,6 +33,9 @@ simplificada del [formato de Michael Nygard](https://cognitect.com/blog/2011/11/ ## Convenciones - Numeración secuencial: `NNN-titulo-breve.md` +- **ADRs retrospectivos**: prefijo `R` + número (`R01`, `R02`, …) para + decisiones reconstruidas a partir del historial git de repositorios + anteriores. Se ubican antes de la serie `001+` - Estados posibles: **Propuesta**, **Aceptada**, **Reemplazada**, **Retirada** - Idioma: español (consistente con el `defaultLocale` del proyecto) - Los ADR no se eliminan; si una decisión se revierte se marca como From fd255a5525ff5cdbaef5dd0d260b9a22851fcdfd Mon Sep 17 00:00:00 2001 From: "Sergio C. Orozco Torres" Date: Sun, 15 Feb 2026 18:59:27 -0500 Subject: [PATCH 2/3] Update docs/adr/R03-migracion-gatsby-a-astro.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/adr/R03-migracion-gatsby-a-astro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/R03-migracion-gatsby-a-astro.md b/docs/adr/R03-migracion-gatsby-a-astro.md index 8736f6a..f141649 100644 --- a/docs/adr/R03-migracion-gatsby-a-astro.md +++ b/docs/adr/R03-migracion-gatsby-a-astro.md @@ -201,7 +201,7 @@ Astro post-i18n → Playwright E2E + Vitest unitarios (cobertura completa) como componentes Astro) - **Curva de aprendizaje**: Astro tiene convenciones propias (frontmatter script, slots, directivas `client:*`) -- **Ecosystem más joven**: menos plugins de terceros que Gatsby/Next.js +- **Ecosistema más joven**: menos plugins de terceros que Gatsby/Next.js ### Métricas del repositorio From 2578bbd3fdb2e882985ca35359384fc62802d6f4 Mon Sep 17 00:00:00 2001 From: Sergio Orozco Date: Sun, 15 Feb 2026 20:29:57 -0500 Subject: [PATCH 3/3] =?UTF-8?q?Fecha=20para=20los=20ADR=20retrospectivos,?= =?UTF-8?q?=20agregada=20fecha=20reconstrucci=C3=B3n?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/adr/R01-fundacion-sitio-jekyll.md | 3 ++- docs/adr/R02-migracion-jekyll-a-gatsby.md | 3 ++- docs/adr/R03-migracion-gatsby-a-astro.md | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/adr/R01-fundacion-sitio-jekyll.md b/docs/adr/R01-fundacion-sitio-jekyll.md index 321d6ce..236ded2 100644 --- a/docs/adr/R01-fundacion-sitio-jekyll.md +++ b/docs/adr/R01-fundacion-sitio-jekyll.md @@ -1,9 +1,10 @@ # ADR R01: Fundación del sitio personal con Jekyll > **Estado:** Reemplazada → [R02](R02-migracion-jekyll-a-gatsby.md) -> **Fecha original:** 2016-04 (reconstruido retrospectivamente 2026-02) +> **Fecha:** 2016-04 > **Categoría:** Plataforma / SSG / Quality > **Repositorio:** `secorto.com_jekyll` (423 commits, 2016–2023) +> **Fecha reconstrucción:** 2026-02 --- diff --git a/docs/adr/R02-migracion-jekyll-a-gatsby.md b/docs/adr/R02-migracion-jekyll-a-gatsby.md index fc0ee39..8babb18 100644 --- a/docs/adr/R02-migracion-jekyll-a-gatsby.md +++ b/docs/adr/R02-migracion-jekyll-a-gatsby.md @@ -1,9 +1,10 @@ # ADR R02: Migración de Jekyll a Gatsby > **Estado:** Reemplazada → [R03](R03-migracion-gatsby-a-astro.md) -> **Fecha original:** 2021-03 (reconstruido retrospectivamente 2026-02) +> **Fecha:** 2021-03 > **Categoría:** Plataforma / SSG / Testing / Quality > **Repositorio:** `web2021` (111 commits, 2021–2023) +> **Fecha reconstrucción:** 2026-02 --- diff --git a/docs/adr/R03-migracion-gatsby-a-astro.md b/docs/adr/R03-migracion-gatsby-a-astro.md index f141649..12242b7 100644 --- a/docs/adr/R03-migracion-gatsby-a-astro.md +++ b/docs/adr/R03-migracion-gatsby-a-astro.md @@ -1,9 +1,10 @@ # ADR R03: Migración de Gatsby a Astro > **Estado:** Aceptada -> **Fecha original:** 2024-05 (reconstruido retrospectivamente 2026-02) +> **Fecha:** 2024-05 > **Categoría:** Plataforma / SSG / Testing / i18n > **Repositorio:** `secorto_web` (502+ commits, 2024–presente) +> **Fecha reconstrucción:** 2026-02 ---