Consideraciones al documentar y mantener librerías open source

Comento lo que aprendí gracias a mi segunda contribución a un proyecto open source

hace 2 años   •   3 min de lectura

Por Andrés Tuñón

Hace unos meses, me atreví a crear una solución definitiva para todas las personas que usaban Chakra UI + Storybook, a continuación comparto el post donde explico como inicio todo esto:

Mi experiencia contribuyendo a un repositorio open source
Comparto lo que aprendí al contribuir en un proyecto open source y algunos puntos a mejorar en mi arsenal de habilidades

Primer Error: Configuraciones

Luego de esa primera contribución, 2 personas levantaron Issues a partir de la solución que propuse; ya que rompe sus pruebas visuales:

Storybook Addon: configuration to remove the color mode switcher · Issue #5544 · chakra-ui/chakra-ui
Description I recently began migrating my CSS to Chakra from CSS modules and already have Storybook stories publishing visual regression tests to Chromatic. I would like to be able to disable the c...
[Chakra Storybook Addon] Color mode switch breaks visual testing tools · Issue #5380 · chakra-ui/chakra-ui
Description When using visual testing tools that take screenshots of stories, the color mode switch appears in all of them, triggering a false positives. Link to Reproduction N/A Steps to reproduce...

¡Cuánta razón! No había contemplado cuando no quieres que se vea el botón en el resto del flujo. Por esta razón, procedí a agregar opciones para que el usuario pueda configurar el botón.

Una buena documentación

Usualmente me suelo encontrar librerías que tienen claros todos los parámetros, valores permitidos y predeterminados; justo repliqué eso:

Las documentación de las librerías que he visto suelen tener una estructura en común:

  • Título y badges de estabilidad, compilado y pruebas
  • ¿Cómo instalarlo?
  • ¿Cómo se usa? (Ejemplo rápido)
  • Configuraciones
  • Parámetros
  • Casos Generales
  • Casos Específicos
  • Preguntas Frecuentes

No es la clásica documentación de un proyecto en desarrollo, es distinto. Solo empiezas a notar estos detalles cuando te toca hacerlo a ti.

Segundo Error: Mantenimiento

Fueron amables al menos...
Fueron amables al menos...

No me explicaron los motivos por los cuales cerraron mi PR; pero, es claro que una de esas razones, es el esfuerzo que conlleva mantener lo que estoy proponiendo.

La solución más acertada es moverlo al toolbar donde no afecta las pruebas de nadie; en otras palabras, una solución de raíz.

Reflexión Final

No quiero entrar en muchos detalles técnicos, pero aprendí que debo contemplar todos los aspectos del flujo de desarrollo cuando se trata de algo que va a ser muy utilizado (sobretodo producción).

Siempre debes velar por el mantenimiento de la aplicación y consultar la mejor opción con el equipo.

feat: add configurable parameters to the ColorModeSwitch of the storybook-addon package by ngxCoder · Pull Request #5732 · chakra-ui/chakra-ui
Closes #5544 #5380📝 DescriptionThis PR enhances the configuration of the Storybook Addon for Chakra-UI. This will allow users to configure the Color Mode Switch with following parameters: Para...
Mi segunda contribución (cerrado)

Corre la voz

Sigue leyendo