Comunidad

Comenzar a contribuir

Nos encantaría que contribuyese a nuestro código fuente para ayudar a que la Comunidad de iText 7 sea aún mejor de lo que es hoy.

Aportaciones a la comunidad de iText 7

Nos encantaría que contribuyese a nuestro código fuente para ayudar a que la comunidad de iText 7 sea todavía mejor de lo que ya es en la actualidad. Si se anima, le agradeceríamos que siguiese estas normas:

¿Tiene preguntas o problemas?

Las preguntas sobre el uso de la Comunidad de iText 7 deben dirigirse a Stack Overflow.

Si usted es cliente con contrato de mantenimiento, también dispone de acceso directo a nuestro sistema JIRA y a nuestros desarrolladores.

¿Ha detectado algún problema?

Si descubre algún error en el código fuente o en la documentación, nos ayudará si nos envía una solicitud de extracción (Pull Request) aportando una solución.

Lea las Normas para el envío de mensajes que encontrará abajo.

¿Desea incorporar una nueva función?

Si desea incorporar una nueva función, en primer lugar debe identificar de qué tipo de cambio se trata:

  • Cambios sustanciales (Major Changes): estos cambios requieren de un análisis y debate previo que nos permita coordinar nuestros esfuerzos, evitar la duplicación de trabajo y ayudarle a diseñar el cambio de manera que sea aceptado con éxito en el proyecto. Envíenos un correo electrónico a community@itextpdf.com.
  • Cambios pequeños (Small Changes): se pueden crear y enviar al Repositorio de GitHub mediante una solicitud de extracción.

Normas para el envío de mensajes

Envío de preguntas o comunicación de problemas

Antes de enviar su pregunta o de comunicar un problema, consulte en Stack Overflow si su consulta ya existe y ha sido respondida.

Si su problema parece deberse a un error todavía no comunicado, formule una pregunta en Stack Overflow para comprobar si realmente se trata de un error y no de un fallo en su propio código. Evite comunicar problemas ya conocidos. Así podremos dedicar más tiempo a la resolución de problemas y a la incorporación de nuevas funciones. Para contribuir a que su problema se resuelva rápidamente, aporte la información siguiente:

  • Cómo formular correctamente las preguntas
  • Descripción general del problema (Overview of the Issue): si el problema en cuestión genera un error, un registro de seguimiento de la pila no minificado facilita la identificación.
  • Motivo o uso previsto (Motivation for or Use Case): explique por qué, en su opinión, se trata de un error.
  • Versión o versiones de iText (iText Version(s)): ¿se trata de una regresión?
  • Sistema operativo (Operating System): ¿el problema se produce en Windows o Linux, o quizá en Mac?
  • Reproducir el error (Reproduce the Error): proporcione un ejemplo breve, reproducible independientemente y correcto (compilable), conocido también como ejemplo mínimo, completo y verificable.
  • Problemas relacionados (Related Issues): ¿se tiene ya constancia de algún problema similar?
  • Sugiera una solución (Suggest a Fix): si no puede resolver el error por su cuenta, quizá pueda indicar qué podría estar causándolo (línea de código o commit).
  • Etiquete la pregunta (Tag the question): añada la etiqueta itext7 a su pregunta para que podamos encontrarla.

La ayuda debe ser recíproca. "Good karma rulez!"

Enviar solicitudes de extracción

Ajústese a estas normas para enviar solicitudes de extracción:

  • Busque en GitHub si ya existe alguna solicitud de extracción abierta o cerrada relacionada con la suya. Así evitar la duplicación de esfuerzos.
  • Asegúrese de que el cambio que propone todavía no se haya abordado en la rama de desarrollo.
  • No envíe una solicitud de extracción por cada archivo que modifique.
  • Para poder enviar solicitudes de extracción que modifiquen más de 20 líneas significativas de código (sin contar corchetes, llaves ni otros elementos sintácticos obligatorios), deberá haber firmado el Acuerdo de Licencia de Colaborador de iText (iCLA). No podemos aceptar ningún código no sujeto a este acuerdo.
  • Bifurque el repositorio de iText en GitHub.
  • Clone la bifurcación de iText a su máquina local.
  • Realice sus cambios, incluyendo casos de prueba apropiados.
  • Ajústese a nuestras reglas de codificación.
  • Confirme sus cambios mediante un mensaje de commit claro y descriptivo que se ajuste a nuestras convenciones para la redacción de mensajes de commit.
  • Este sería un buen momento para arreglar los commits que considere necesarios por medio de la instrucción git rebase --interactive.
  • Verifique los cambios en su equipo local para asegurarse de que superan todas las pruebas.
  • Suba los cambios a su cuenta de GitHub.
  • Cree una solicitud de extracción en GitHub.

Indique "Head fork" como su repositorio y "base fork" como repositorio oficial de iText 7.

  • Si, por nuestra parte, le sugerimos alguna modificación:
    • Realice los cambios necesarios.
    • Si fuese necesario, arregle sus commits con un rebase interactivo.
    • Vuelva a ejecutar las pruebas y asegúrese de que su código las sigue superando.
    • Fuerce el envío a su repositorio de GitHub. Esta operación actualizará su solicitud de extracción.

¡Ya está! ¡Muchas gracias por su aportación!

Una vez fusionada su solicitud de extracción

Después de fusionar su solicitud de extracción, puede eliminar de forma segura su bifurcación local y tomar los cambios del repositorio principal (ascendente).

Reglas de codificación

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

  • Debido a que primero desarrollamos en Java y luego portamos el código a .NET, es preferible que las aportaciones de código sean en Java. Pero esto no significa que no se puedan realizar solicitudes de extracción directamente al porting de .NET.
  • Todo el código Java debe ser Java 7. Lo sentimos, pero no se aceptan expresiones lambda ni otras características de la versión 8 de Java.
  • Todas las funciones o correcciones de errores deben verificarse como mínimo con una prueba a nivel de unidad.
  • Todos los métodos de API públicas deben documentarse con JavaDoc. Para ver cómo documentamos nuestras API, consulte los javadocs existentes.
  • Seguimos las reglas establecidas en las Convenciones de código de Oracle para el lenguaje de programación Java, con estas adiciones:
    • Limite la longitud de las líneas de código forzando saltos de línea a los 100 caracteres.

Normas de git relativas a mensajes de commit

Tenemos normas para formatear nuestros mensajes de commit destinados a git. Se trata de producir mensajes claros e inteligibles y que sean fáciles de seguir para quienes consulten el historial del proyecto. Pero también empleamos los mensajes de commit de git para generar el registro de cambios de la comunidad de iText 7.

Hemos tomado estas normas del blog de Chris Beams, concretamente de la publicación titulada Cómo escribir un mensaje de commit de git.

Formato de los mensajes de commit

Cada mensaje de commit consta de un asunto, un cuerpo y un pie de página:

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

Ninguna línea del mensaje de commit debe contener más de 72 caracteres. Esta limitación de longitud aumenta la legibilidad del mensaje tanto en GitHub como en otras herramientas de git.

Asunto

El asunto contiene una breve descripción del cambio:

Cuerpo

El pie de página contiene cualquier información relativa a cambios sustanciales. También es donde se debe hacer referencia a posibles problemas relativos a JIRA o GitHub que se cierran con este commit.

Firma del acuerdo iCLA

Para poder enviar solicitudes de extracción, es necesario haber firmado el Acuerdo de Licencia de Colaborador de iText (iCLA). Para que se acepte cualquier cambio considerable de código (más de 20 líneas de código significativas), es necesario haber firmado el iCLA. Firmar este acuerdo es un proceso muy breve.

Deberá firmar (digitalmente) el formulario y enviarlo por correo electrónico, fax o correo.

Código de conducta para colaboradores

Tenga en cuenta que este proyecto está sujeto al cumplimiento de un Código de conducta para colaboradores. Con su participación en este proyecto, usted se compromete cumplir las condiciones del mismo.

Usamos la red Stack Exchange como recurso de soporte técnico gratuito y GitHub para el alojamiento de código. Con su utilización de estos servicios, usted acepta cumplir las condiciones de los mismos:

Contribuya a la comunidad de código abierto

Nos encantaría que contribuyese a nuestro código fuente para ayudar a que la Comunidad de iText 7 sea aún mejor de lo que es hoy.

Comenzar a contribuir
Contacto

¿Aún tiene preguntas? 

Estamos encantados de responder a sus preguntas. Comuníquese con nosotros y le responderemos a la brevedad.

Contáctenos
Manténgase actualizado

Únase a más de 11,000 suscriptores y conviértase en un experto en iText PDF al mantenerse al día con nuestros nuevos productos, actualizaciones, consejos, soluciones técnicas y eventos.

Suscríbase ahora