Skip to content

Latest commit

 

History

History
319 lines (225 loc) · 9.98 KB

CONTRIBUTING.md

File metadata and controls

319 lines (225 loc) · 9.98 KB
Raw

Contribución

Nos encantaría que contribuyeras a este proyecto y ayudaras a mejorarlo. Estas son las directrices que nos gustaría que siguieras:

Código de conducta

Ayúdanos a mantener este proyecto accesible e inclusivo. Por favor, lee y sigue nuestro código de conducta.

Preguntas, problemas o ideas

Empieza una nueva discusión y selecciona la categoría adecuada para ello:

  • General: Cualquier cosa que sea relevante para el proyecto.
  • Ideas: Ideas para mejorar el proyecto o proponer nuevas características.
  • Encuestas (polls): Encuestas con múltiples opciones para que la comunidad.
  • Q&A: Preguntas para que la comunidad responda.
  • Mostrar y contar (show and tell): Creaciones, experimentos o pruebas.

Agregar o mejorar algo

  • Para un cambio importante, abre una nueva discusión en la categoría Ideas y expón tu propuesta para que pueda ser discutida. Esto también nos permitirá coordinar mejor nuestros esfuerzos, evitar la duplicación del trabajo y ayudarte a elaborar el cambio para que sea para que sea aceptado con éxito en el proyecto.

  • Pequeñas características pueden desarrollarse y enviar directamente un pull request.

Reportar un error

Si encuentras un error en el código, puedes ayudarnos enviando un issue a nuestro repositorio. O mejor aún, puedes enviar un pull request con una solución.

Enviar un issue

Los reportes de problemas son muy valiosos para cualquier proyecto.

Los grandes informes de errores suelen tener:

  • Un resumen rápido y/o antecedentes.
  • Pasos para reproducir el problema.
  • Ser específico.
  • Dar un ejemplo de código si se puede.
  • Lo que se esperaba que ocurriera.
  • Lo que realmente sucede.
  • Notas; por qué podría estar sucediendo, pruebas que no funcionaron...

Envía un nuevo issue para reportar un error.

Enviar un pull request

Los pull request son una gran manera de incluir tus ideas en este proyecto o simplemente arreglar algo.

Antes de enviar tu pull request ten en cuenta las siguientes directrices:

  1. Busca en GitHub si existe algún tema relacionado para asegurarte que no esté repetido.

  2. Bifurca el repositorio a tu propia cuenta de GitHub.

  3. Clona el repositorio en tu máquina.

  4. Sitúate en el repositorio clonado.

    cd php-url

  5. Crea una rama a partir de la rama main con un nombre corto pero descriptivo.

    git checkout -b descriptive-name main

  6. Realiza tus cambios en la nueva rama, incluyendo las pruebas necesarias.

  7. Sigue nuestras reglas de codificación.

  8. Ejecuta el conjunto de pruebas del repositorio completo.

    composer tests

  9. Confirma tus cambios utilizando un commit descriptivo que siga nuestras reglas para escribir commits.

    git commit -a

    La opción -a agregará (add) y eliminará (rm) los archivos editados.

  10. Envía (push) tu rama a GitHub:

    git push origin descriptive-name

  11. En GitHub, envía un pull request hacia php-url:main.

  • Si te sugerimos algún cambio:

    • Realiza las actualizaciones necesarias.

    • Vuelve a ejecutar las pruebas para asegurarse de que siguen pasando.

    • Reorganiza tu rama y envíala a tu repositorio de GitHub (esto actualizará tu pull request):

      git rebase main -i
git push -f

¡Eso es todo! ¡Gracias por tu contribución!

Después de fusionar tu pull request

Después de que tu pull request se fusione, puedes eliminar con seguridad tu rama y actualizar los cambios desde la rama main:

  • Elimina la rama remota en GitHub, ya sea a través de la interfaz de GitHub o de tu shell local:

    git push origin --delete descriptive-name

  • Sitúate en la rama main:

    git checkout main -f

  • Elimina la rama local:

    git branch -D descriptive-name

  • Actualiza tu rama main con la última versión:

    git pull --ff upstream main

Reglas de codificación

Para garantizar la coherencia en todo el código fuente, ten en cuenta estas reglas mientras trabajas:

  • Todas las características o correcciones de errores deben ser probadas por una o más especificaciones (pruebas unitarias).

    Puedes utilizar el siguiente comando para comprobar las pruebas:

    composer phpunit

  • Toda nueva característica debe ser documentada en el archivo README.md.

  • Utilizamos PHP CodeSniffer y PHP Mess Detector para definir nuestros estándares de código.

    Puedes utilizar los siguientes comandos para comprobar el estado de tu código:

    composer phpcs
    composer phpmd

    Puedes utilizar el siguiente comando para formatear automáticamente los errores encontrados con PHP CodeSniffer:

    composer fix

Reglas para escribir commits

Tenemos reglas muy precisas sobre cómo deben ser formateados nuestros commits. Este formato hace que el historial commits sea más fácil de leer.

Cada commit consta de un header, un body, y un footer.

<header>
<LÍNEA EN BLANCO>
<body>
<LÍNEA EN BLANCO>
<footer>

El header es obligatorio y debe ajustarse al formato para el encabezado del commit.

El body es opcional. Cuando está presente, debe tener al menos 20 caracteres y debe ajustarse al formato del cuerpo del commit.

El footer es opcional. El formato para la parte inferior del commit detalla su estructura.

Cabecera del commit

<tipo>(<ámbito>): <resumen corto>
  │          │          │
  │          │          └─> # Resumen en tiempo presente. Sin mayúsculas. Sin punto al final.
  │          │
  │          └─> # Palabra corta relevante. Sin mayúsculas.
  │
  └─> # Tipo de commit: build|ci|docs|feat|fix|perf|refactor|test.

Los campos <tipo> y <summary> son obligatorios, el campo (<ámbito>) es opcional.

Tipo

Debe ser uno de los siguientes:

  • build: Cambios que afectan al sistema de compilación o a las dependencias externas.
  • ci: Cambios en nuestros archivos de configuración y scripts de CI.
  • docs: Cambios en documentación.
  • feat: Nuevas características.
  • fix: Arreglar un error.
  • perf: Cambios en el código que mejoran el rendimiento.
  • refactor: Cambio de código que no corrige un error ni añade una característica.
  • test: Añadir pruebas que faltan o corregir las existentes.

Ámbito

Se puede proporcionar un ámbito al tipo del commit para proporcionar información contextual adicional. Éste debería ir entre paréntesis. Por ejemplo:

feat(parser): add ability to parse arrays

Resumen

Utiliza el campo de resumen para proporcionar una descripción sucinta del cambio:

  • Utiliza el imperativo y el tiempo presente: "change" en vez de "changed" o "changes".
  • No escribas la primera letra en mayúscula.
  • No pongas punto (.) al final.
  • Utiliza el inglés.

Cuerpo del commit

Al igual que en el resumen del commit, utiliza el imperativo y el tiempo presente: "fix" en vez de "fixed" o "fixes".

Explica la motivación del cambio en el cuerpo del commit. Este commit debe explicar por qué estas haciendo el cambio. Puede incluir una comparación del comportamiento anterior con el nuevo comportamiento para ilustrar el impacto del cambio.

Parte inferior del commit

El footer puede contener información sobre cambios de última hora o declarados obsoletos. También es el lugar para hacer referencia a los issues de GitHub y a otros PRs que ese commit cierra o con los que está relacionado. Por ejemplo:

BREAKING CHANGE: <resumen de cambios de última hora>
<LÍNEA EN BLANCO>
<descripción de los cambios de última hora + instrucciones de migración>
<LÍNEA EN BLANCO>
<LÍNEA EN BLANCO>
Fixes #<número de issue>

o

DEPRECATED: <qué es lo que está obsoleto>
<LÍNEA EN BLANCO>
<descripción de la desaprobación + ruta de actualización recomendada>
<LÍNEA EN BLANCO>
<LÍNEA EN BLANCO>
Closes #<número de pull request>

La sección de cambios de última hora debe comenzar con la frase "BREAKING CHANGE:" seguida de un resumen del cambio, una línea en blanco y una descripción detallada del cambio que incluya también instrucciones de migración.

Del mismo modo, una sección de desaprobación debe comenzar con "DEPRECATED:" seguido de una breve descripción sobre lo que quedó obsoleto, una línea en blanco y una descripción detallada que también recomiende una alternativa.

Esta guía de contribución está inspirada en la guía de contribución de Angular.