Saltar al contenido principal

Pautas para C贸digo Abierto

Proceso de Desarrollo#

Utilizamos un estilo de tablero Kanban para priorizar nuestro trabajo. Por ejemplo, puedes mirar EOS rate project board.

Hemos a帽adido una columna adicional al dise帽o automatizado por defecto para mantener una columna To Do priorizada.

Cuando nuevos issues son creados, necesitas usar expl铆citamente la opci贸n de proyecto en el issue de GitHub para incluirlo en el tablero; una vez que lo haces, el issue quedar谩 autom谩ticamente agregado a la columna de issues nuevos.

Peri贸dicamente movemos los nuevos issues a la columna To Do y manualmente le damos la prioridad apropiada.

Cuando comienzas a trabajar en una tarea, deber铆as moverla manualmente a la columna In Progress.

Usamos el flujo de GitHub https://guides.github.com/introduction/flow/ para solicitar cambios en el c贸digo. Desarrollamos en la rama master y release usando etiquetas y versionamiento.

Los nuevos y reabiertos pull request son aut贸maticamente a帽adidos al tablero en la columna En Progreso.

Cuando un pull request cerrado es movido a la columna Done autom谩ticamente. Si el pull request se cierra y no tiene problemas, se indica correctamente con las palabras clave de GitHub que se cierra el pull request y se mueve autom谩ticamente a la columna Done.

Pautas para los Pull Request#

  • Por favor revisa para asegurarte que no hay ning煤n pull request existente tratando de localizar o vincular el issue mecionado.
  • Busca los issues relacionados en el registro de issues.
  • Los cambios no triviales deber铆an ser discutidos primero en un issue.
  • Desarrolla en una rama espec铆fica para caracter铆sticas (c贸digo no estable), nunca en la master: git checkout -b topic-branch.
  • Haz amplias y claras descripciones de los pull requests.
  • Realiza pull requests at贸micos y con un 谩mbito bien definido. 1 PR por caracter铆stica o bug.
  • Vincula el issue con la descripci贸n pull requestpara referencia entre el c贸digo y los issues.

Soportamos 煤nicamente squash merge de los pull requests como una buena pr谩ctica para asegurar que el registro de la rama master es mantenido limpio y relevante, sin requerir que el pull request sea modificado. Esta estrategia requiere que todos los pull request sea hechos de forma at贸mica, en otras palabras, que resuelvan una 煤nica cosa. Un pull request por caracter铆stica, bug o actualizac贸n de documentaci贸n.

Pautas para Mensajes en los Commits#

Tenemos reglas muy precisas acerca de c贸mo los mensajes de los commits de git deben ser formateados. Esto permite mensajes m谩s legibles que son f谩ciles de seguir cuando se est谩 buscando entre la historia del proyecto. Pero tambi茅n, usamos los mensajes de commit de git para generar el registro de cambios del proyecto.

Seguimos las convenciones de mensajes de commit como se muestra a continuaci贸n:

Formato de Mensaje del Commit#

Cada mensaje de commit consiste en un encabezado, un cuerpo y un pi茅. El encabezado tiene un especial formato que incluye un tipo, un 谩mbito y un aspecto o tema:

<tipo>(<ambito>): <aspecto><BLANK LINE><cuerpo><BLANK LINE><pie>

El encabezado es obligatorio y el 谩mbito del encabezado es opcional.

Ninguna l铆nea del mensaje de commit puede ser m谩s larga que 100 caracteres. Esto permite que el mensaje sea f谩cil de leer en GitHub as铆 como tambi茅n en varias herramientas de git.

El pie debe contener una referencia de cierre de un issue, si hay alguna.

Ejemplos:

docs(changelog): update changelog to beta.5
fix(release): need to depend on latest rxjs and zone.js
The version in our package.json gets copied to the one we publish, and users need the latest of these.

M谩s ejemplos aqu铆

Revertir#

Si el commit revierte un commit previo, debe empezar con revert: , seguido por el encabezado del commit revertido. En el cuerpo, deber铆a decir: This reverts commit <hash>, donde el hash is el SHA del commit que est谩 siendo revertido.

Tipo#

  • build: Cambios que afectan el sistema de operaci贸n o dependencias externas (ejemplo scopes: gulp, broccoli, npm)
  • ci: Cambios a los scripts y archivos de configuraci贸n de CI (ejemplo scopes: Travis, Circle, BrowserStack, SauceLabs)
  • docs: Cambios s贸lo en la documentaci贸n
  • feat: Una nueva caracter铆stica
  • fix: Un arreglo de un bug
  • perf: Cambio en el c贸digo que mejora el rendimiento
  • refactor: Cambio en el c贸digo que no arregla un bug ni a帽ade una caracter铆stica
  • style: Cambios que no afectar en significado del c贸digo (espacios en blanco, formato, puntos y comas olvidados, etc)
  • test: A帽adir pruebas faltantes o corregir las existentes
  • content: A帽adir o remover contenido
  • devtools: Heramientas para desarrolladores

脕mbito#

El 谩mbito es el nombre del componente o servicio que afecta, ejemplo:

  • common
  • smart-contracts
  • webapp
  • storage
  • graphql
  • frontend
  • demux
  • docker

Aspecto#

El aspecto contiene una breve descripci贸n del cambio:

  • usa el imperativo, tiempo presente: "cambio" no "cambiado" ni "cambios"
  • no pongas la primera letra en may煤scula
  • no a帽adas (.) al final

Cuerpo#

Justo como en el aspecto, usa el imperativo, tiempo presente: "cambio" no "cambiado" ni "cambios". El cuerpo debe incluir la motivaci贸n para el cambio y contrastar esto con el comportamiento anterior.

Pi茅#

El pi茅 debe contender cualquier informaci贸n acerca de los cambios importantes con repercusiones (breaking changes) y es tambi茅n el lugar para referenciar los issues que el commit cierra.

Los Breaking Changes deben empezar con la palabraBREAKING CHANGE: con un espacio o dos nuevas l铆neas. El resto del mensaje de commit es luego usado para esto.

Reportar bugs#

Antes de subir tu issue por favor revisa que has completado los siguientes pasos:

  • Aseg煤rate de estar en la 煤ltima versi贸n.
  • Usa la funcionalidad de b煤squeda para asegurarte de que el bug no ha sido reportado a煤n.

Los reportes de bug deben contener la siguiente informaci贸n:

  • Summary: Una breve descripci贸n.
  • Steps to reproduce: 驴C贸mo encontraste el bug? Instrucciones para reproducirlo.
  • Expected behavior: 驴C贸mo esperas que se comporte?
  • Actual behavior: 驴C贸mo se comporta actualmente?
  • References: V铆nculos a cualquier tag o recursos de informaci贸n.
  • Si es posible, a帽adie informaci贸n visual del bug. Una captura de pantalla o un gif.

Lanzamientos#

Lanzamos el software para producci贸n usando las etiquetas de GitHub Semver, excepto que la versi贸n tiene nombres sem谩nticos, por ejemplo "Breaking.Feature.Fix" en lugar de "Major.Minor.Patch".

Breaking.Feature.Fix#

No decidimos cu谩l ser谩 la versi贸n. Los cambios en el API deciden. Los n煤meros en la versi贸n son para computadoras, no para personas. Los nombres en los lazamientos son para las personas.

Breaking#

Cualquier "breaking change", no importa cu谩n peque帽o, incrementa el n煤mero de la versi贸n. Incrementar la versi贸n no tiene relaci贸n con emitir un lanzamiento.

Caracter铆stica (Feature)#

Cuando una nueva caracter铆stica es a帽adida, esto puede ser tan peque帽a como propiedad p煤blica, o tan larga como m贸dulo siendo expuesto.

Fix#

Cuando una caracter铆stica documentada no se comporta como est谩 documentada, o cuando un problema de seguridad es descubierto y arreglado sin alterar el comportamiento documentado.

Generaci贸n de Registro de Cambios#

En cada nuevo lanzamiento, generamos un archivo de registro de cambios usando el est谩ndar git-changelog. Hay una tarea de npm para esto.

Herramientas de Git Avanzadas#

Hay tambi茅n herramientas como Hub y git-extras que facilitan la interacci贸n con GitHub. Puedes aprovechar estas herramientas para contribuir a este repositorio.

Est谩ndares de C贸digo#

Usamos standardjs code style.

Integraci贸n Continua y Entrega#

Esto es un trabajo en progeso, problamente usaremos Netlify y TravisCI.

Pre-commit Hooks#

Usamos los pre-commit hooks para asegurarnos que los est谩ndares de c贸digo y las convenciones de mensajes son cumplidas.