Saltar al contenido principal

Generación de un registro de cambios

Se puede generar un registro de cambios usando @jutro/cli.

Para generar un registro de cambios correcto, siga las directrices de confirmación convencionales a continuación.

Ejecutar el comando​

Se puede ejecutar el comando de dos maneras:

En una aplicación de Jutro:

npm run changelog - [additionalParams]

En cualquier repositorio que siga los estándares para compromisos convencionales:

npx @jutro/cli generate changelog [additionalParams]

El comando admite los siguientes parámetros opcionales:

  • --workdir [workdir]: directorio de trabajo con un repositorio git, directorio de trabajo actual por opción predeterminada
  • --for-version [forVersion]: versión correspondiente al registro de cambios generado; por opción predeterminada, toma la versión de package.json en el directorio de trabajo
  • --ignored-scopes [ignoredScopes]: ámbitos separados por comas, ignore las confirmaciones que comienzan con [type]: ([scope])
  • --issue-prefixes [issuePrefixes]: prefijos separados por comas que deben incluirse en el archivo generado; por opción predeterminada, acepta todos los prefijos

Las versiones del registro de cambios se basan en etiquetas git, por lo que debe mantenerlas sincronizadas para generar las diferencias adecuadas.

Proceso para el mantenimiento del registro de cambios​

  1. Cambie la versión en package.json raíz a una versión futura (puede agregar un sufijo, por ejemplo, 1.0.0-next).
  2. Continúe con el desarrollo y siga las directrices de confirmación convencionales.
  3. Genere el registro de cambios y elimine el sufijo de la versión preliminar (si se usó). Confirme los cambios como la versión oficial.
  4. Cree una etiqueta git que apunte a la confirmación con el lanzamiento oficial.

Flujo de muestra​

npx @jutro/create-app sample-app
cd sample-app
git init
git remote add origin ssh://git@stash.guidewire.com/jut/fake-repo.git
git add .
git commit -m"feat: initial commit (FOO-23456)"

# change version to 1.0.0 in root package.json file

npm run changelog
git add .
git commit -m"chore: release 1.0.0 version (_)"
git tag 1.0.0

# continue development

touch sample-file
git add .
git commit -m"feat: add sample-file (BAZ-123456)"

# change version to 2.0.0 in root package.json file

npm run changelog
git add .
git commit -m"chore: release 2.0.0 version (_)"
git tag 2.0.0

El archivo CHANGELOG.md generado después de ejecutar los comandos anteriores será similar a:

# 2.0.0 (2020-10-09)

## Features

add sample-file (1e996a3), closes BAZ-123456

# 1.0.0 (2020-10-09)

## Features

initial commit (64b9ab6), closes FOO-23456

Convenciones para mensajes de confirmación (registro de cambios convencional)​

Cómo confirmar​

El mensaje de confirmación debe estructurarse de la siguiente manera:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Ejemplos de buenos mensajes de confirmación​

Para los componentes nuevos, siga el patrón feat(component-name): create new component. Por ejemplo:

feat(button): create new component (EL-42)

Para los cambios importantes, utilice un mensaje de confirmación de varias líneas. Deje una línea vacía y comience la línea inferior con BREAKING CHANGE:.

fix(button): change proptype `mode` (EL-42)

BREAKING CHANGE: Change Button's proptype `mode` from int to string

Si desea hacer referencia a tickets adicionales, menciónelos en la descripción:

refactor(uiconfing): split code for better readability (EL-42)

Split method getComponent into two

Fixes EL-123

Tipos de confirmación​

  • feat: una nueva característica (se incluirá en el registro de cambios).
  • fix: una corrección de errores (se incluirá en el registro de cambios).
  • docs: solo cambios en la documentación (no se incluirá a menos que se incluya BREAKING CHANGE en el cuerpo o pie de página).
  • perf: un cambio de código que mejora el rendimiento (se incluirá en el registro de cambios).
  • refactor: un cambio de código que no corrige un error ni agrega una característica (no se incluirá a menos que se incluya BREAKING CHANGE en el cuerpo o pie de página).
  • test: adición de nuevas pruebas o corrección de pruebas existentes (no se incluirá a menos que se incluya BREAKING CHANGE en el cuerpo o pie de página).
  • chore: cambios en el proceso de construcción o herramientas y bibliotecas auxiliares como la generación de documentación (no se incluirá en el registro de cambios).

Cambio importante​

Si la confirmación introduce algunos cambios importantes, se pueden enumerar en el cuerpo o el pie de página de la confirmación:

fix(components): change Button proptype `mode` (EL-42)

BREAKING CHANGE: Change Button's proptype `mode` from int to string

Cualquier confirmación (excepto del tipo chore) se incluirá en el registro de cambios si contiene una nota BREAKING CHANGE:.

Ámbito​

El ámbito podría ser cualquier cosa que especifique el lugar del cambio de confirmación (p. ej. button, router, storybook, galen, e2e, etc.). Podemos utilizar \* cuando el cambio afecte a más de un ámbito.

Evite ámbitos genéricos, como “componentes”. Si puede, indique un componente en particular.

Si el ámbito consta de varias palabras, utilice guiones, por ejemplo card-selector, image-radio-button.

Los siguientes ámbitos no están incluidos en el registro de cambios:

storybook jutro-components

Asunto​

El asunto contiene una breve descripción del cambio.

  • use el imperativo, tiempo presente: "cambie" no "cambió" ni "cambia"
  • no escriba en mayúsculas la primera letra
  • sin punto (.) al final
  • intente no repetir el ámbito, por ejemplo, no diga arreglar (botón): arregle el botón dañado
  • intente no repetir el nombre de la aplicación o componente, por ejemplo, no diga arreglar (botón): arreglar botón dañado

Reversión​

Si la confirmación revierte una confirmación anterior, debe comenzar con revert:, seguido del encabezado de la confirmación revertida. En el cuerpo, debería decir: Esto revierte el hash de confirmación, donde el hash es el SHA de la confirmación que se está revirtiendo. El comando git revert crea automáticamente una confirmación con este formato.

Especificación​

  • Las confirmaciones DEBEN ir precedidas de un tipo, que consta de un sustantivo (característica, corrección, etc.), seguido de dos puntos y un espacio.
  • El tipo feat DEBE usarse cuando una confirmación agrega una nueva característica a la aplicación o biblioteca.
  • El tipo fix DEBE usarse cuando una confirmación representa una corrección de errores para su aplicación.
  • Se PUEDE proporcionar un ámbito opcional después de un tipo. Un ámbito es una frase que describe una sección del código base entre paréntesis (p. ej. fix(parser):).
  • Una descripción DEBE ir inmediatamente después del prefijo de tipo/ámbito. La descripción es una breve descripción de los cambios en el código (por ejemplo, fix: array parsing issue when multiple spaces were contained in string).
  • Se PUEDE proporcionar un cuerpo de confirmación más largo después de la descripción breve, lo que brinda información contextual adicional sobre los cambios en el código. El cuerpo DEBE comenzar una línea en blanco después de la descripción.
  • Se PUEDE proporcionar un pie de página con una línea en blanco después del cuerpo (o después de la descripción si falta el cuerpo). El pie de página DEBE contener referencias de problemas adicionales sobre los cambios en el código (como los problemas que soluciona, por ejemplo, Fixes JUT-123).
  • Los cambios importantes DEBEN indicarse al comienzo del pie de página o de la sección del cuerpo de una confirmación. Un cambio importante DEBE constar del texto en mayúscula BREAKING CHANGE:, (seguido de dos puntos y un espacio).
  • DEBE proporcionarse una descripción después del BREAKING CHANGE:, describiendo lo que ha cambiado en la API (p. ej., BREAKING CHANGE: environment variables now take precedence over config files).
  • El pie de página SOLO PUEDE contener: CAMBIO IMPORTANTE, enlaces externos, referencias de problemas y otra metainformación.
  • Los tipos que no sean característica y corrección PUEDEN usarse en sus mensajes de confirmación.

Preguntas frecuentes​

¿Qué debo hacer si la confirmación se ajusta a más de uno de los tipos de confirmación?​

Retrocede y haga varias confirmaciones siempre que sea posible.

¿Ralentiza el desarrollo?​

No se recomienda moverse rápido de manera desorganizada.

¿Qué pasa si alguien coloca accidentalmente un mensaje de confirmación incorrecto?​

Antes del lanzamiento, es posible ejecutar git rebase -i para editar el historial de confirmaciones.