3. Proceso de Desarrollo

Como es común en los proyectos de código abierto, las contribuciones de código y documentación al proyecto son muy apreciadas. La comunidad de QGIS es un gran apoyo. Esta sección describe el procedimiento para desarrollar y fusionar sus contribuciones en el proyecto QGIS.

3.1. Un proyecto basado en git 

La complejidad del código fuente de QGIS ha aumentado considerablemente durante los últimos años. Por lo tanto, es difícil anticipar los efectos secundarios que tendrá la adición de una función. En el pasado, el proyecto QGIS tenía ciclos de lanzamiento muy largos porque era mucho trabajo restablecer la estabilidad del sistema de software después de que se agregaban nuevas funciones. Para superar estos problemas, QGIS cambió a un modelo de desarrollo utilizando el sistema de control de versiones git: las nuevas características se codifican primero en las ramas contribuyentes y se fusionan con el maestro de QGIS (el ramal principal) cuando estén terminados y estables.

El código fuente de QGIS está alojado en https://github.com/qgis/QGIS.

3.1.1. Roles 

Existen varios roles en GitHub. Cuando tienes una cuenta en GitHub, ya puedes contribuir al bifurcar el repositorio y tener el rol de “colaborador”. Los desarrolladores principales son “colaboradores” y pueden fusionar ramas en el repositorio oficial y original.

3.1.2. Entorno 

Para empezar a usar y contribuir al repositorio QGIS, necesitarás:

tener una cuenta GitHub
haga su propia copia del Repositorio QGIS (vea fork)
tener un cliente git instalado en tu sistema
configure su entorno git
¡y diviertete!

3.1.3. Instalar git 

El proyecto git proporciona versiones recientes del software para la mayoría de las plataformas. Siga las instrucciones en https://git-scm.com/downloads para obtener e instalar la copia correspondiente a su sistema operativo y arquitectura. Allí, también es posible instalar un cliente GUI de git para navegar y administrar sus repositorios (la mayoría de las veces, instalará git si aún no está disponible).

3.2. Desarrollo usando ramas 

3.2.1. Contribuciones al desarrollo 

Una vez que se haya registrado en GitHub y haya bifurcado el repositorio, puede participar como colaborador.

Nota

Las contribuciones al código QGIS se pueden realizar desde su repositorio bifurcado en el sitio web de GitHub. El nuevo código será creado automáticamente por el entorno de prueba. Pero este flujo de trabajo puede revelar rápidamente sus límites cuando desee realizar cambios complejos. Las instrucciones a continuación supondrán un clon local.

Puede contribuir iniciando una solicitud de extracción. Para hacer eso, siga estos pasos genéricos:

Clone su repositorio en su computadora local y configure el entorno de compilación
Crea una nueva rama y haz las ediciones para el desarrollo.
Confirme sus cambios y devuelva su rama a la bifurcación remota en GitHub. Luego, se ofrece una solicitud de extracción como enlace web (URL) inmediatamente después.
Abra una solicitud de extracción (PR) solicitando extraer la(s) confirmación(es) de su rama a la rama maestra en el repositorio ascendente.
Se está iniciando un proceso de revisión para informar a otros contribuyentes y colaboradores sobre su solicitud de extracción. Debe ser reactivo a sus comentarios y sugerencias.

Nota

Un flujo de trabajo de horquilla y tracción de Github más detallado está disponible en https://reflectoring.io/github-fork-and-pull/

Nota

La mayoría de los proyectos de QGIS (sitio web, documentación, API de pyQGIS, complementos …) están disponibles en la página del proyecto GitHub. <https://github.com/qgis>`_ y puede obtener contribuciones, siguiendo el mismo proceso.

3.2.2. Accediendo al repositorio 

Para poder interactuar desde su disco local con su bifurcación remota y los repositorios ascendentes de QGIS, necesita:

Hacer un clón de su copia en su disco local

cd path/to/store/the/repository
git clone https://github.com/<yourName>/QGIS.git

Conectar el repositorio principal de QGIS (le llamaremos upstream) al suyo
```
git remote add upstream https://github.com/qgis/QGIS.git
```

Verifique los repositorios remotos conectados

git remote -v
# origin   https://github.com/<YourName>/QGIS.git (fetch)
# origin   https://github.com/<YourName>/QGIS.git (push)
# upstream https://github.com/qgis/QGIS.git (fetch)
# upstream https://github.com/qgis/QGIS.git (push)

Su repositorio en línea ahora es accesible desde su unidad local y puede interactuar con él usando el nombre origen. Siempre que desee obtener cambios del repositorio qgis/QGIS, use upstream.

Nota

En QGIS mantenemos nuestro código más estable en la rama de lanzamiento actual. La rama maestra contiene código para la serie de lanzamientos denominada “inestable”. Periódicamente, ramificaremos una versión del maestro y luego continuaremos con la estabilización y la incorporación selectiva de nuevas funciones en el maestro.

Vea el archivo INSTALL en el árbol de fuentes para obtener instrucciones específicas sobre la creación de versiones de desarrollo.

3.2.3. Procedimiento 

Anuncio inicial en lista de correo o repositorio de problemas:
Antes de comenzar, haga un anuncio en la lista de correo del desarrollador para ver si otro desarrollador ya está trabajando en la misma función. También puede mencionar su interés como comentario en el informe de problemas, si existe uno en el repositorio. Si la nueva característica requiere algún cambio en la arquitectura de QGIS, un QGIS Enhancement Proposal (QEP) es necesario.
Crear una rama en su repositorio local:
Cree una nueva rama de git para el desarrollo de la nueva función, basada en el estado más reciente de la rama maestra.
git fetch upstream master git checkout -b newfeature upstream/master
Ahora puede empezar a desarrollar:
Codifique sus cambios en su disco local con su IDE habitual. Recuerde escribir un conjunto de pruebas para sus modificaciones, cuando sea apropiado.
Confirme sus cambios en el repositorio de git:
Al realizar una confirmación, coloque un comentario descriptivo y, en su lugar, realice varias confirmaciones pequeñas si los cambios en varios archivos no están relacionados. Por el contrario, preferimos que agrupe los cambios relacionados en una única confirmación.
git add path/to/your/files git commit -m "Add a comment describing your nice feature"
Ahora, es posible que desee compartir su trabajo con los miembros de la comunidad QGIS. Envíe su nueva función a su repositorio de bifurcaciones en línea haciendo:
```
git push origin newfeature
```
Nota

Si la rama ya existe, los cambios se insertarán en ella; de lo contrario, se creará.
Envíe sus cambios con una solicitud de extracción
Al abrir la solicitud de extracción, se activa el conjunto de pruebas automatizadas y verifica si sus cambios siguen las pautas de codificación de QGIS y no rompen ninguna función existente. Debería solucionar cualquier problema informado antes de que su rama se fusione en sentido ascendente.

Truco

Usamos GitHub actions para gestionar las pruebas que se ejecutarán en el repositorio. Para mayor comodidad, puede habilitar las acciones en su repositorio para que las pruebas se ejecuten cuando envíe los cambios. Luego, abriría la solicitud de extracción después de que todas pasaron, lo que haría que el proceso de revisión sea más eficiente.
Trasvase a la maestra aguas arriba regularmente:
Se recomienda reajustar para incorporar los cambios en el maestro a la rama de forma regular. Esto hace que sea más fácil fusionar la rama con la maestra más adelante. Después de un trasvase, necesita git push -f a su repositorio bifurcado.
git pull --rebase upstream master git push -f origin newfeature

Nota

Consulte los siguientes sitios para obtener información acerca de cómo convertirse en un maestro de GIT.

3.2.4. Realice las pruebas necesarias antes de volver a fusionar a la rama principal 

Cuando esté terminada la nueva funcionalidad y esté contento con la estabilidad, haga un anuncio en la lista de desarrollo. Antes de fusionar de nuevo, los cambios serán probados por los desarrolladores y usuarios.

3.3. Envío de solicitudes de extracción 

Existen algunas pautas que lo ayudarán a conseguir que sus parches y peticiones de incorporación de cambios (“pull requests”) formen parte de QGIS fácilmente, y nos ayudarán a facilitar el uso de los parches que se envían.

En general, es más fácil para los desarrolladores si envía solicitudes de extracción GitHub. No describimos las Solicitudes de Extracción aquí, más bine nos referimos a las documentación de solicitudes de extracción GitHub.

Si usted hace una petición de actualización (pull) le preguntaremos que fusione (merge) la rama master a su rama (branch) PR regularmente, así su PR estará siempre disponible para fusionar en el flujo (upstream) de su rama master

Si es desarrollador y desea evaluar la cola de peticiones de incorporación de cambios, hay una herramienta muy amigable que le permite hacer esto desde línea de comandos

En general, cuando envía un PR, debe asumir la responsabilidad de seguirlo hasta su finalización: responder a las consultas publicadas por otros desarrolladores, buscar un “campeón” para su función y darles un recordatorio suave ocasionalmente si ve que su PR es no ser actuado. Tenga en cuenta que el proyecto QGIS está impulsado por el esfuerzo de los voluntarios y es posible que las personas no puedan atender su RP instantáneamente. Analizamos las solicitudes de extracción entrantes, pero a veces nos perdemos cosas. No se ofenda ni se alarme. Trate de identificar a un desarrollador que lo ayude y comuníquese con ellos para preguntarles si pueden revisar su parche. Si cree que el RP no está recibiendo la atención que merece, sus opciones para acelerarlo deberían ser (en orden de prioridad):

Ayude a revisar otras solicitudes de extracción para liberar a la persona asignada a la suya.
Envíe un mensaje a la lista de correo “promocionando” su petición de incorporación de cambios y qué maravilloso sería incluirlo en el código base.
Envíe un mensaje a la persona a la que se le asignó su petición de incorporación de cambios en la cola de peticiones de incorporación de cambios.
Envíe un mensaje al comité directivo del proyecto pidiendo que le ayuden a incorporar su petición de incorporación de cambios en el código base.

3.3.1. Mejores prácticas para la creación de una petición de incorporación de cambios 

Inicie siempre una rama para una nueva funcionalidad a partir de la rama principal actual.
Si está programando en una rama una nueva funcionalidad, no “”fusione”” (“merge”) nada en dicha rama; en lugar de ello use la opción de restablecer la base (“rebase”) como se indica en el siguiente punto para mantener su historial limpio.
Antes de crear una solicitud de extracción, haga git fetch upstream y git rebase upstream/master (dado que upstream es el control remoto para el usuario de qgis y no su propio control remoto, verifique su``.git/config`` or do git remote -v | grep github.com/qgis).
Puede hacer una reestablecer la base (“rebase”) de git como en la última línea repetidamente sin hacer ningún daño (siempre y cuando el único propósito de su rama sea fusionarse con la rama principal).
Atención: después de un rebase necesitará ejecutar git push -f en su repositorio bifurcado. DESARROLLADORES DEL NÚCLEO: NO HAGAN ESTO EN EL REPOSITORIO PÚBLICO DE QGIS!

3.3.2. Etiquetas especiales para notificar a los documentadores 

Hay una etiqueta especial (Necesita documentación) que los revisores pueden asignar a su solicitud de extracción para generar automáticamente informes de problemas en el repositorio de documentación de QGIS tan pronto como se combine su solicitud de extracción. Recuerde mencionar si su función merece dicha etiqueta.

Además, puede agregar etiquetas especiales a sus mensajes de confirmación para proporcionar más información a los documentadores. Luego, el mensaje de confirmación se agrega al informe de problemas generado:

[needs-docs] para indicar a los redactores de documentación que agreguen documentos extra después de una corrección o mejora de una funcionalidad ya existente.
«[característica]» en caso de una nueva funcionalidad. Diligenciar una buena descripción en su PR será un buen inicio.

Desarrolladores, utilicen por favor estas etiquetas (no distingue entre mayúsculas y minúsculas) para que los redactores de documentos tengan incidencias en las que trabajar y tengan una visión general de las cosas pendientes por hacer. PERO por favor dediquen también tiempo para añadir algo de texto: ya sea en el mensaje al guardar los cambios o en la documentación.

3.3.3. Auditoría 

QGIS se distribuye bajo licencia GPL. Debe hacer todos los esfuerzos posibles para garantizar que sólo envía parches que no estén sujetos a derechos de propiedad intelectual contradictorios. Además, no envíe código que no esté contento de haber puesto a disposición en virtud de la GPL.

3.4. Obteniendo acceso de escritura en GIT 

El acceso de escritura al árbol fuente de QGIS es por invitación. Normalmente, cuando una persona envía varios parches (no hay un número fijo) que demuestren la competencia básica y la comprensión de las convenciones de codificación C++ y de QGIS, uno de los miembros del PSC u otros desarrolladores existentes pueden nominar a esa persona al PSC para otorgar acceso de escritura . El nominador debe proporcionar un párrafo promocional básico de por qué creen que esa persona debe obtener acceso de escritura. En algunos casos otorgaremos acceso de escritura a desarrolladores que no sean de C++, p. ej., para traductores y documentadores. En estos casos, la persona aún así debe haber demostrado la capacidad de enviar parches y lo ideal es que haya enviado varios parches sustanciales que demuestren su comprensión de la modificación del código fuente base sin romper las cosas, etc.

Nota

Desde que nos mudamos a GIT es menos probable que otorguemos acceso de escritura a los nuevos desarrolladores, ya que es trivial compartir código dentro de github creando una bifurcación de QGIS y generando peticiones de incorporación de cambios.

Verifique siempre que todo compila antes de realizar cualquier solicitud de confirmación / petición de incorporación de cambios. Intente tener en cuenta las posibles roturas que sus confirmaciones pueden causar a las personas que compilan en otras plataformas y con versiones más antiguas / más nuevas de las librerías.