From 3f48fdafacfa0bc66dcc8713a55991495c53b5b6 Mon Sep 17 00:00:00 2001 From: Carlos Tribiec Date: Mon, 8 Jan 2024 12:00:45 -0400 Subject: [PATCH] docs: update readme --- README.md | 115 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 70 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 12b1a43..4597e24 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,10 @@ [![GitHub](https://img.shields.io/github/license/transbankdevelopers/transbank-sdk-nodejs)](LICENSE) [![GitHub contributors](https://img.shields.io/github/contributors/transbankdevelopers/transbank-sdk-nodejs)](https://github.com/TransbankDevelopers/transbank-sdk-nodejs/graphs/contributors) [![Build Status](https://travis-ci.org/TransbankDevelopers/transbank-sdk-nodejs.svg?branch=master)](https://travis-ci.org/TransbankDevelopers/transbank-sdk-nodejs) + # Transbank SDK Node.js -Este es el SDK oficial de Transbank para Node.js +Este es el SDK oficial de Transbank para Node.js ## Requisitos: @@ -15,17 +16,21 @@ Este es el SDK oficial de Transbank para Node.js ### Instalar con `npm` Puedes instalar SDK en tu proyecto usando NPM + ```bash -npm install transbank-sdk +npm install transbank-sdk ``` ### Instalar con `yarn` + ó también instalarlo usando [Yarn](https://yarnpkg.com/) + ```bash -yarn add transbank-sdk +yarn add transbank-sdk ``` ### Detectar vulnerabilidades con `npm` + ```bash # Este comando te permite ver las vulnerabilidades npm audit @@ -34,7 +39,7 @@ npm audit npm audit fix ``` -## Documentación +## Documentación Puedes encontrar toda la documentación de cómo usar este SDK en el sitio [www.transbankdevelopers.cl](https://www.transbankdevelopers.cl). @@ -47,60 +52,80 @@ La documentación relevante para usar este SDK es: - Primeros pasos con [Webpay](https://www.transbankdevelopers.cl/documentacion/webpay). - Referencia detallada sobre [Webpay](https://www.transbankdevelopers.cl/referencia/webpay) -## Información para contribuir y desarrollar este SDK +## Información para contribuir -### Requerimientos -- Node.js +8 -- Plugin de editorconfig para tu editor favorito. +### **Estándares generales** -### Estándares +- Para los commits, seguimos las normas detalladas en [este enlace](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits) 👀 +- Usamos inglés para los nombres de ramas y mensajes de commit 💬 +- Todas las fusiones a la rama principal se realizan a través de solicitudes de Pull Request(PR) ⬇️ +- Puedes emplear tokens como "WIP" en el encabezado de un commit, separados por dos puntos (:), por ejemplo: "WIP: este es un mensaje de commit útil ✅" +- Las ramas de nuevas funcionalidades que no han sido fusionada, se asume que no está finalizada⚠️ +- Los nombres de las ramas deben estar en minúsculas y las palabras deben separarse con guiones (-) 🔤 +- Los nombres de las ramas deben comenzar con uno de los tokens abreviados definidos. Por ejemplo: feat/tokens-configurations 🌿 -- Para los commits respetamos las siguientes normas: https://chris.beams.io/posts/git-commit/ -- Usamos ingles, para los mensajes de commit. -- Se pueden usar tokens como WIP, en el subject de un commit, separando el token con `:`, por ejemplo: -`WIP: This is a useful commit message` -- Para los nombres de ramas también usamos inglés. -- Se asume, que una rama de feature no mezclada, es un feature no terminado. -- El nombre de las ramas va en minúsculas. -- Las palabras se separan con `-`. -- Las ramas comienzan con alguno de los short lead tokens definidos, por ejemplo: `feat/tokens-configuration` +### **Short lead tokens** -#### Short lead tokens -##### Commits -- WIP = Trabajo en progreso. -##### Ramas -- feat = Nuevos features -- chore = Tareas, que no son visibles al usuario. -- bug = Resolución de bugs. +`WIP` = En progreso. -### Todas las mezclas a master se hacen mediante Pull Request. +`feat` = Nuevos features. -### Test -Para ejecutar los test localmente debes ejecutar los siguientes comandos en una terminal. +`fix` = Corrección de un bug. -```bash -npm install # si es que no se han instaldo todavía -npm run test -``` +`docs` = Cambios solo de documentación. -### Deploy de una nueva versión. -Para generar una nueva versión, se debe crear un PR (con un título "Prepare release X.Y.Z" con los valores que correspondan para `X`, `Y` y `Z`). Se debe seguir el estándar semver para determinar si se incrementa el valor de `X` (si hay cambios no retrocompatibles), `Y` (para mejoras retrocompatibles) o `Z` (si sólo hubo correcciones a bugs). +`style` = Cambios que no afectan el significado del código. (espaciado, formateo de código, comillas faltantes, etc) -En ese PR deben incluirse los siguientes cambios: +`refactor` = Un cambio en el código que no arregla un bug ni agrega una funcionalidad. + +`perf` = Cambio que mejora el rendimiento. + +`test` = Agregar test faltantes o los corrige. + +`chore` = Cambios en el build o herramientas auxiliares y librerías. -1. Modificar el archivo `CHANGELOG.md` para incluir una nueva entrada (al comienzo) para `X.Y.Z` que explique en español los cambios **de cara al usuario del SDK**. -2. Modificar el archivo `package.json` para que la propiedad `"version"` apunte a la nueva versión `X.Y.Z` +`revert` = Revierte un commit. -Luego de obtener aprobación del pull request, debe mezclarse a master e inmediatamente generar un release en GitHub con el tag `X.Y.Z`. En la descripción del release debes poner lo mismo que agregaste al changelog. +`release` = Para liberar una nueva versión. -Con eso Travis CI generará automáticamente una nueva versión de la librería y la publicará en npm. +#### Flujo de trabajo -### Vulnerabilidades de seguridad -Si descubres una falla de seguridad dentro de este proyecto, por favor, notifícanos por correo electrónico a transbankdevelopers@continuum.cl. Tomaremos el caso con la mayor celeridad. +1. Crea tu rama desde develop. +2. Haz un push de los commits y publica la nueva rama. +3. Abre un Pull Request apuntando tus cambios a develop. +4. Espera a la revisión de los demás integrantes del equipo. +5. Mezcla los cambios sólo cuando esté aprobado por mínimo 2 revisores. + +### Esquema de flujo + +![gitflow](https://wac-cdn.atlassian.com/dam/jcr:cc0b526e-adb7-4d45-874e-9bcea9898b4a/04%20Hotfix%20branches.svg?cdnVersion=1324) + +### **Reglas** 📖 + +1. Todo PR debe incluir test. +2. Todo PR debe cumplir con un mínimo de 80% de coverage para ser aprobado +3. El PR debe tener 2 o más aprobaciones para poder mezclarse. +4. Si un commit revierte un commit anterior deberá comenzar con "revert:" seguido del mensaje del commit anterior. + +### **Pull Request** + +- Usar un lenguaje imperativo y en tiempo presente: "change" no "changed" ni "changes". +- El título del los PR y mensajes de commit no pueden comenzar con una letra mayúscula. +- No se debe usar punto final en los títulos o descripción de los commits. +- El título del PR debe comenzar con el short lead token definido para la rama, seguido de : y una breve descripción del cambio. +- La descripción del PR debe detallar los cambios. +- La descripción del PR debe incluir evidencias de que los test se ejecutan de forma correcta. +- Se pueden usar gif o videos para complementar la descripción o evidenciar el funcionamiento del PR. + +## Generar una nueva versión + +Para generar una nueva versión, se debe crear un PR (con un título "release: prepare release X.Y.Z" con los valores que correspondan para `X`, `Y` y `Z`). Se debe seguir el estándar [SemVer](https://semver.org/lang/es/) para determinar si se incrementa el valor de `X` (si hay cambios no retrocompatibles), `Y` (para mejoras retrocompatibles) o `Z` (si sólo hubo correcciones a bugs). + +En ese PR deben incluirse los siguientes cambios: +1. Modificar el archivo `CHANGELOG.md` para incluir una nueva entrada (al comienzo) para `X.Y.Z` que explique en español los cambios. +2. Modificar el archivo `package.json` y modificar la versión. -### Para marcar una versión como Latest -Cuando se desea forzar una versión especifica de la librería como la última (versión `latest` o la que se instalará por defecto cuando se usa el comando `npm i transbank-sdk`) se debe hacer lo siguiente: +Luego de obtener aprobación del PR, debe mezclarse a master e inmediatamente generar un release en GitHub con el tag `vX.Y.Z`. En la descripción del release debes poner lo mismo que agregaste al changelog. -1. Agregar el usuario `transbankdevelopers` desde la consola del sistema operativo con el comando `npm adduser`. -2. Ejecutar el comando `npm dist-tag add transbank-sdk@xxx latest` +Posterior a la liberación debes mezclar la rama release en develop, finalmente realizar un rebase de la rama develop utilizando como base la rama main.