Contribuir a iText 7 Community

Nos encantaría que contribuyera a nuestro código fuente y a hacer de iText 7 Community una herramienta aún mejor de lo que ya es. Estas son nuestras directrices:

Contribución a iText 7 Community

¿Tienes preguntas o dificultades?

Si tienes alguna pregunta sobre el funcionamiento de iText 7 Community, publícala en Stack Overflow.

Si eres un cliente con un contrato de asistencia, también tienes acceso directo a JIRA y a nuestros desarrolladores.

¿Has encontrado un error?

Si encuentras un error en el código fuente o en la documentación, ayúdanos y envía una solicitud de incorporación de cambios con una solución.

Consulta las Directrices de envío más abajo.

¿Deseas implementar una característica?

Si quieres implementar una característica nueva, defina el tipo de cambio que es:

Directrices de envío

Enviar una pregunta o un problema

Antes de enviar una pregunta o un problema, busca en Stack Overflow, ya que quizá hayan contestado a esta pregunta en el pasado.

Si se trata de un error y nadie ha informado acerca de él, formula una pregunta en Stack Overflow para comprobar que es realmente un error y no un fallo en tu propio código. Para ayudarnos a maximizar el tiempo que podemos dedicar a solucionar problemas y a agregar nuevas características, no informes de problemas ya conocidos. Proporcionar la siguiente información aumentará las posibilidades de que tu problema se resuelva rápidamente:

  • Cómo hacer buenas preguntas

  • Descripción general del problema: Si hay un error, ayuda que añade el seguimiento de pila detallado (sin minificar).

  • Motivación o fundamento: Explica por qué cree que es un error.

  • Versiones de iText: ¿Es un error que viene de una versión anterior?

  • Sistema operativo: ¿El problema sucede en Windows, Linux o Mac?

  • Reproducción: Ofrece ejemplo breve, autónomo y correcto (compilable), también conocido como ejemplo mínimo, completo y verificable.

  • Problemas relacionados: ¿Alguien ha informado anteriormente de algún problema similar?

  • Sugerir una solución: Si no puedes arreglar el problema tú mismo, quizás puedas señalar aquello que lo está causando (línea de código o cambio).

  • Etiqueta la pregunta: Agregue la etiqueta itext7 a su pregunta para que la encontramos.

Si obtienes ayuda, ayuda a otros. ¡Así se extiende el buen karma!

Enviar una solicitud de incorporación de cambios

Antes de enviar tu solicitud de incorporación de cambios, ten en cuenta las siguientes directrices:

  • Busca en GitHub si existe una solicitud de incorporación de cambios abierta o cerrada relacionada con su envío. Es mejor no duplicar los esfuerzos.

  • Comprueba si el cambio propuesto no se ha abordado ya en la rama de desarrollo.

  • No envíes una solicitud de incorporación de cambios por cada archivo que cambies.

  • Firma el Contrato de licencia del contribuidor de iText (CLCi) antes de enviar solicitudes de incorporación de cambios para cualquier cambio de más de 20 líneas de código significativas (no contamos corchetes y otros adornos sintácticos). No podemos aceptar ningún código sin este contrato.

  • Clona iText 7 Community en tu equipo local.

    git clone git@github.com:itext/itext7.git
    cd itext7
    git fetch origin
    git checkout -b develop origin/develop
    
  • Haz tus cambios en una nueva ramificación de git basada en la rama de desarrollo:

    git checkout -b my-fix-branch develop
    
  • Crea tu parche, incluidos los casos de prueba apropiados.

  • Sigue nuestras Reglas de codificación.

  • Ejecuta el conjunto de pruebas de iText 7 Community y asegúrate de que pasa todas las pruebas.

  • Confirma tus cambios utilizando un mensaje de confirmación descriptivo que siga nuestras convenciones de mensajes de confirmación.

    git commit -a
    

    Nota: La confirmación opcional de línea de comandos -a ejecutará automáticamente add y rm sobre los archivos editados.

  • Ahora sería un buen momento para arreglar sus confirmaciones (en caso de necesidad) con git rebase --interactive.

  • Haz tus cambios en local para asegurarte de que pasan todas las pruebas.

  • Copia tu rama en tu cuenta de GitHub:

    git remote add my-remote git@github.com:my-remote/itext7.git
    git push my-remote my-fix-branch
    
  • En GitHub, envía una solicitud de incorporación de cambios a itext7:develop.

  • Si sugerimos cambios:

    • Efectúa las actualizaciones solicitadas.

    • Vuelve a ejecutar el conjunto de pruebas de iText 7 Community para asegurarte de que sigue pasando las pruebas.

    • Vuelve a colocar tu rama y fuerza tu copia en tu repositorio de GitHub (esto actualizará tu solicitud de incorporación de cambios):

      git fetch origin
      git rebase develop -i
      git push my-remote my-fix-branch -f
      

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

Tras combinar tu solicitud de incorporación de cambios

Una vez que se combine tu solicitud de incorporación de cambios, puedes eliminar tu rama e incorporar los cambios desde el repositorio principal (nivel superior):

  • Elimina la versión remota en GitHub a través de la interfaz de usuario web de GitHub o en tu shell local de la siguiente manera:

    git push my-remote --delete my-fix-branch
    
  • Echa un vistazo a la rama de desarrollo:

    git checkout develop -f
    
  • Elimina la rama local:

    git branch -D my-fix-branch
    
  • Actualiza tu desarrollo con la última rama de nivel superior:

    git pull --ff upstream develop
    

Reglas de codificación

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

  • Desarrollamos en Java primero y luego migramos los archivos a .NET, por lo que se prefieren los envíos de código en Java. Sin embargo, esto no es un impedimento para enviar una buena solicitud de incorporación de cambios al puerto .NET.

  • Todo el código de Java debe estar en Java 7. No admitimos expresiones lambda ni otras características del lenguaje Java 8.

  • Todas las características o correcciones de errores deben ser comprobadas por una o más pruebas de unidad.

  • Todos los métodos API públicos deben estar documentados con JavaDoc. Para ver cómo documentamos nuestras API, comprueba los javadocs existentes.

  • Seguimos las reglas descritas en las Convenciones de código Oracle para el lenguaje de programación Java, con las siguientes adiciones:

    • Separar toda línea de código en los 100 caracteres.

Directrices de confirmación git

Tenemos varias directrices sobre cómo formatear los mensajes de confirmación git. Esto produce mensajes más legibles y fáciles de seguir al comprobar el historial del proyecto. Además, los mensajes de confirmación git también sirven para generar el registro de cambios de iText 7 Community.

Estas directrices están tomadas de la publicación del blog de Chris Beams Cómo escribir un mensaje de confirmación git.

Formato del mensaje de confirmación

Cada mensaje de confirmación consta de asunto, cuerpo y pie de página:

<subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Las líneas del mensaje de confirmación no deben tener más de 72 caracteres. Con esto el mensaje es más fácil de leer en GitHub y en otras herramientas git.

Asunto

El asunto debe contener una descripción breve del cambio:

Cuerpo

Pie de página

El pie de página contiene toda la información sobre cambios de último minuto y es donde se deben mencionar los errores en JIRA o GitHub que esta confirmación cierra.

Firmar el CLCi

Firma el Contrato de licencia del contribuidor de iText (CLCi) antes de enviar solicitudes de incorporación de cambios. Para que se acepte cualquier cambio de código importante (más de 20 líneas de código significativo) es necesario firmar el CLCi. ¡Es un proceso rápido, lo prometemos!

Debes (digitally) firmar el formulario y enviarlo por correo electrónico, fax o correo postal.

Código de conducta del contribuidor

Ten en cuenta que este proyecto se distribuye con un Código de conducta del contribuidor. Al participar en este proyecto, aceptas cumplir sus condiciones.

Usamos la red Stack Exchange para la asistencia gratuita y GitHub para alojar el código. Al usar estos servicios, aceptas cumplir sus condiciones: