Cómo contribuir al código

¿Te preparas para contribuir a Nette Framework y necesitas orientarte sobre las reglas y procedimientos? Esta guía para principiantes te mostrará paso a paso cómo contribuir eficazmente al código, trabajar con repositorios e implementar cambios.

Procedimiento

Para contribuir al código, es esencial tener una cuenta en GitHub y estar familiarizado con los fundamentos del trabajo con el sistema de control de versiones Git. Si no dominas Git, puedes consultar la guía git – the simple guide y, opcionalmente, utilizar alguno de los muchos clientes gráficos.

Preparación del entorno y del repositorio

  1. en GitHub, crea un fork del repositorio del paquete que vas a modificar
  2. clona este repositorio en tu ordenador
  3. instala las dependencias, incluido Nette Tester, mediante el comando composer install
  4. comprueba que las pruebas funcionan ejecutando composer tester
  5. crea una nueva rama basada en la última versión publicada

Implementación de tus propios cambios

Ahora puedes realizar tus propias modificaciones en el código:

  1. programa los cambios deseados y no olvides las pruebas
  2. asegúrate de que las pruebas se ejecutan correctamente usando composer tester
  3. comprueba que el código cumple con los estándares de codificación
  4. guarda los cambios (haz commit) con una descripción en este formato

Puedes crear varios commits, uno para cada paso lógico. Cada commit debe tener sentido por sí solo.

Envío de cambios

Una vez que estés satisfecho con los cambios, puedes enviarlos:

  1. envía (haz push) los cambios a GitHub a tu fork
  2. desde allí, envíalos al repositorio de Nette creando una pull request (PR)
  3. proporciona suficiente información en la descripción

Incorporación de comentarios

Tus commits ahora serán visibles para otros. Es común recibir comentarios con sugerencias:

  1. sigue las modificaciones propuestas
  2. incorpóralas como nuevos commits o combínalas con los anteriores
  3. vuelve a enviar los commits a GitHub y aparecerán automáticamente en la pull request

Nunca crees una nueva pull request para modificar una existente.

Documentación

Si has cambiado la funcionalidad o añadido una nueva, no olvides añadirla también a la documentación.

Nueva rama

Si es posible, realiza los cambios sobre la última versión publicada, es decir, la última etiqueta en la rama correspondiente. Para la etiqueta v3.2.1, crea una rama con este comando:

git checkout -b nombre_nueva_rama v3.2.1

Estándares de codificación

Tu código debe cumplir con el estándar de codificación utilizado en Nette Framework. Hay disponible una herramienta automática para comprobar y corregir el código. Se puede instalar a través de Composer globalmente en la carpeta que elijas:

composer create-project nette/coding-standard /ruta/a/nette-coding-standard

Ahora deberías poder ejecutar la herramienta en la terminal. El primer comando comprueba y el segundo también corrige el código en las carpetas src y tests del directorio actual:

/ruta/a/nette-coding-standard/ecs check
/ruta/a/nette-coding-standard/ecs check --fix

Descripción del commit

En Nette, los asuntos de los commits tienen el formato: Presenter: fixed AJAX detection [Closes #69]

  • Área seguida de dos puntos.
  • Propósito del commit en tiempo pasado; si es posible, comienza con una palabra como: “added (nueva característica añadida)”, “fixed (corrección)”, “refactored (cambio en el código sin cambio de comportamiento)”, changed, removed.
  • Si el commit rompe la compatibilidad hacia atrás, añade “BC break”.
  • Posible vínculo con el issue tracker como (#123) o [Closes #69].
  • Después del asunto puede seguir una línea vacía y luego una descripción más detallada, incluyendo, por ejemplo, enlaces al foro.

Descripción de la pull request

Al crear una pull request, la interfaz de GitHub te permitirá introducir un título y una descripción. Proporciona un título descriptivo y en la descripción ofrece la mayor cantidad de información posible sobre las razones de tu cambio.

También se mostrará un encabezado donde especificarás si se trata de una nueva función o una corrección de error y si puede haber una ruptura de la compatibilidad hacia atrás (BC break). Si hay un problema relacionado (issue), enlaza a él para que se cierre después de la aprobación de la pull request.

- bug fix / new feature?  <!-- #issue numbers, if any -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- highly welcome, see https://nette.org/en/writing -->
  1. Documentación
  2. Conviértase en un contribuyente de Nette
  3. Cómo contribuir al código