Importante

La traducción es un esfuerzo comunitario puede unirse. Esta página está actualmente traducida en |progreso de traducción|.

1. Una contribución paso a paso

Nota

Aunque QGIS documentación se utiliza para demostrar el proceso, todas las instrucciones y pasos que se muestran a continuación también se aplican al sitio web de QGIS.

Si está leyendo estas líneas, sin duda es porque está dispuesto a contribuir a escribir la documentación de QGIS y está buscando una guía práctica. ¡Has venido al lugar correcto! El documento actual lo guiará a través de las diferentes formas de lograr este objetivo, mostrándole los principales pasos a seguir, los trucos que puede usar y los trucos que debe conocer.

Para cualquier ayuda, no dude en preguntar ya sea por medio de un reporte de fallo o escribiendo a la lista QGIS-community-team list <https://lists.osgeo.org/mailman/listinfo/qgis-community-team> `_, describiendo el problema que está tratando. Más detalles en la sección `Participe en la documentación <https://qgis.org/en/site/getinvolved/document.html> _.

Vamos a sumergirnos en el proceso.

Las fuentes de documentación se almacenan utilizando el sistema de control de versiones de git y están disponibles en GitHub en https://github.com/qgis/QGIS-Documentation. Puede encontrar una lista de problemas para solucionar y funciones a explicar en https://github.com/qgis/QGIS-Documentation/issues.

Truco

Si es la primera vez que colabora y no sabe por dónde empezar, quizá le interese abordar nuestros informes de problemas de bienvenida.

Hay dos formas principales, no excluyentes entre sí, de modificar los archivos:

  1. Usando la interfaz web de GitHub

  2. Usando herramientas de línea de comando Git.

1.1. Usando la interfaz web de GitHub

La interfaz web de GitHub le permite hacer lo siguiente:

  • editar archivos

  • previsualizar y confirmar -commit; sus cambios

  • haga un «pull request» para que sus cambios se inserten en el repositorio principal

  • Crear, actualizar o borrar ramas

Si todavía no está familiarizado con el vocabulario git y GitHub, puede desear leer el proyecto Hola mundo ello-world de GitHub para aprender sobre el vocabulario básico y las acciones que se usarán a continuación.

Nota

** Si está solucionando un problema reportado **

Si está realizando cambios para solucionar un problema <https://github.com/qgis/QGIS- Documentation/issues> _, agregue un comentario al informe de problemas -issue report; para auto-asignárselo. Esto evitará que más de una persona trabaje en el mismo problema.

1.1.1. Fork QGIS-Documentation

Suponiendo que ya tiene una cuenta en GitHub <https://github.com/join> _, lo primero que debe hacer es bifurcar los archivos fuente de la documentación.

Vaya a la página del repositorio QGIS-Documentation <https://github.com/qgis/QGIS-Documentation> _ y haga clic en el botón | githubFork | en la esquina superior derecha.

En su cuenta de GitHub encontrará un repositorio QGIS-Documentation (https://github.com/<usuario>/QGIS-Documentation). Este repositorio es una copia del repositorio oficial de documentación QGIS donde tiene completo acceso de escritura y puede realizar cambios sin afectar la documentación oficial.

1.1.2. Hacer cambios

Hay diferentes formas de contribuir a la documentación de QGIS. Aunque se muestren por separado, se puede cambiar de un proceso a otro sin ningún problema.

Alternativa 1: Usa el atajo Editar en GitHub

Las páginas del sitio web de documentación de QGIS se pueden editar rápida y fácilmente haciendo clic en el enlace Editar en GitHub en la parte superior derecha de cada página.

  1. Esto abrirá el archivo en la rama `` qgis: master`` con un mensaje en la parte superior de la página que le indica que no tiene acceso de escritura a este repositorio y sus cambios se aplicarán a una nueva rama de su repositorio .

  2. Realice los cambios. Dado que la documentación está escrita utilizando la sintaxis reStructureText, dependiendo de sus cambios, es posible que deba remitirse a: ref: directrices de escritura <QGIS-documentation-guidelines>.

  3. Cuando termine, haga un corto comentario sobre sus cambios y pulse Proponer cambios. Esto generará una nueva rama (patch-xxx) en su repositorio.

  4. Despues de que pulse en Proponer cambios, github navegará página Comparando cambios.

    • Si está haciendo cambios, salte a Compare changes en la sección inferior Share your changes via Pull Request.

    • Si desea realizar cambios adicionales antes de enviarlos a QGIS, siga estos pasos:

      1. Diríjase a su copia -fork- de la documentación QGIS(https://github.com/<YourName>/QGIS-Documentation)

      2. Click en githubBranch y busque el ramal patch-xxx . Seleccione este ramal de parches. El botón githubBranch ahora dirá Branch: patch-xxx

      3. Salte a Modify files abajo.

Nota

El atajo Editar en GitHub también está disponible en el menú desplegable en la parte inferior de la barra lateral izquierda.

Alternativa 2: Cree una rama ad hoc en su repositorio de documentación

Puede editar archivos diréctamente desde su enlace de la Documentación de QGIS.

En primer lugar, asegúrate de que tu rama master está actualizada con la rama qgis:master. Para ello:

  1. Vaya a la página principal de su repositorio, es decir, https://github.com/<YourName>/QGIS-Documentation. La rama master debería estar activa con una mención de si está actualizada con qgis/QGIS-Documentation:master o no.

    Si tiene commits por delante de la rama upstream, es mejor utilizar la alternativa anterior del botón shortcut hasta que alinee su rama maester.

    Si sólo tiene commits detrás:

    1. Despliegue el menú desplegable Buscar en la parte superior de la corriente de la derecha. Puede

      • Comparar las ramas y ver los nuevos cambios en el repositorio principal

      • Recoger y fusionar: toma los cambios de la rama upstream a la suya.

    2. Hagamos clic en Recoger y fusionar: después del proceso, su rama se menciona como actualizada con qgis/QGIS-Documentation:master.

  2. Pulse githubBranch en la esquina superior izquierda de su repositorio de Documentación QGIS e introduzca un nombre único en el campo de texto para crear una nueva rama . El nombre de la nueva rama debería estar relacionado con el problema que pretende corregir. El botón githubBranch debería decir ahora Branch: nombre de rama

  3. Está preparado para iniciar nuevos cambios encima.

Atención

Haga sus cambios en un ramal ad hoc, nunca en la **rama ** master

Por convención, evite realizar cambios en su rama maestra'', excepto cuando combine las modificaciones de la rama ``maestra de qgis/QGIS-Documentation en su copia del repositorio de documentación QGIS. Las ramas separadas le permiten trabajar en múltiples problemas al mismo tiempo sin interferir con otras ramas. Si comete un error, siempre puede eliminar una rama y comenzar de nuevo creando una nueva desde la rama maestra.

1.1.3. Modificar archivos

  1. Explore los archivos fuente de su bifurcación de documentación de QGIS hasta el archivo que necesite ser modificado

  2. Haga sus modificaciones siguiendo las writing guidelines

  3. Cuando termine, navegue hasta el marco Confirmar cambios en la parte inferior de la página, haga un breve comentario sobre sus cambios y haga clic en Commit Changes” para confirmar los cambios directamente en su ramal. Asegúrese de que :guilabel:`Commit directly to the branch_name branch. esté seleccionado.

  4. Repita los pasos anteriores para cualquier otro archivo que deba actualizarse para solucionar el problema.

1.1.4. Compartir tus cambios mediante una Solicitud de extracción

Debe realizar una solicitud de extracción para integrar sus cambios en la documentación oficial.

Nota

Si uso un enlace Editar en GitHub

Después de confirmar sus cambios, GitHub abrirá automáticamente una nueva página comparando los cambios que realizó en su rama ``patch-xxx”” con la rama maestra ``qgis/QGIS-Documentation””.

Salta a Step 2 abajo.

Iniciar una nueva solicitud de extracción

Navegue a la página principal del repositorio QGIS-Documentation <https://github.com/qgis/QGIS-Documentation> _ y haga clic en Nueva solicitud de extracción.

Comparar cambios

Si ve dos cuadros de diálogo, uno que dice ``base:master “” y el otro ``compare:branch_name”” (vea la figura), esto solo fusionará los cambios de una de sus ramas a su rama master. Para arreglar esto, haga clic en el enlace :guilabel:`compare through forks”.

../../_images/githubCompareAcrossForks.png

Figura 1.1 Si su página Comparing changes tiene este aspecto, haga clic en el enlace ccompare across forks.

Debería ver cuatro menús desplegables. Esto le permitirá comparar los cambios que ha realizado en su rama con la rama maestra en la que desea fusionarse. Son:

  • base fork: la bifurcación en la que desea fusionar sus cambios

  • base: la rama de la bifurcación base en la que desea fusionar sus cambios

  • head fork: la horquilla que tiene cambios que desea incorporar a la horquilla base

  • compare:la rama con esos cambios

Seleccione qgis/QGIS-Documentation como la bifurcación base con `` maestro “” como base, configure la bifurcación principal en su repositorio <YourName>/QGIS-Documentation, y establecer comparar con su rama modificada.

../../_images/githubCreatePullRequestComparison.png

Figura 1.2 Comparando cambios entre qgis/QGIS-Documentation y su repositorio

Un check verde con las palabras Capaz de combinar muestra que sus cambios se pueden combinar en la documentación oficial sin conflictos.

Haga clic en el botón Create pull request.

Advertencia

Si se muestra githubCantMerge

Esto significa que hay conflictos. Los archivos que está modificando no están actualizados con la rama a la que se dirige porque otra persona ha realizado una confirmación que entra en conflicto con sus cambios.. Usted puede aún crear la petición de extracción pare necesitará corregir cualquier conflicts para completar la uniónto complete the merge.

Truco

Aunque se está traduciendo, la última versión de la documentación de QGIS aún se mantiene y los problemas existentes se han solucionado. Si está solucionando problemas para una versión diferente, cambie base de maestro a la rama correspondiente de versión _... en los pasos anteriores.

Describe tu solicitud de extracción

Se abrirá un cuadro de texto: complete los comentarios relevantes para el problema que está abordando.

Si esto se relaciona con un problema particular, agregue el número de problema a sus comentarios. Esto se hace ingresando # y el número de emisión (por ejemplo #1234). Si está precedido por términos como fix o close, el problema en cuestión se cerrará tan pronto como se fusione la solicitud de extracción.

Agregue enlaces a cualquier página de documentación que esté cambiando.

Click en Crear solicitud de extracción.

Revisar y comentar una solicitud de extracción

Igual que lo visto más arriba, cualquiera puede enviar modificaciones a la documentación a través de peticiones de extracción. Del mismo modo cualquiera puede revisar solicitudes de incorporación de cambios con pregunta y comentarios <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request>`_. Quizás el estilo de redacción no coincida con las directrices, al cambio le faltan algunos detalles importantes o capturas de pantalla o puede sr que todo se vea correcto yen orden. Las revisiones ayudan a mejorar la calidad de la contribución, tanto en forma como en fondo.

Para revisar una solicitud de extracción:

  1. Navegue a la página de solicitudes de extracción <https://github.com/qgis/QGIS-Documentation/pulls>`_ y haga click en la solicitud de extracción que desea comentar.

  2. En la parte inferior de la página, encontrará un cuadro de texto donde puede dejar comentarios generales sobre la solicitud de extracción.

  3. Para añadir comentarios sobre líneas específicas,

    1. Haga clic en githubFilesChanged y encuentre el archivo que desea comentar. Puede que tenga que hacer clic en :guilabel: Mostrar la diferencia de origen para ver los cambios.

    2. Desplácese hasta la línea que desea comentar y haga clic en githubBluePlus. Eso abrirá un cuadro de texto que le permitirá dejar un comentario.

Los comentarios de línea específicos se pueden publicar:

  • como comentarios únicos, usando el botón Agregar comentario único. Se publican a medida que avanza. Use esto solo si tiene pocos comentarios para agregar o al responder a otro comentario.

  • o como parte de una revisión, pulsando el botón Empezar una revisión. Sus comentarios no son automáticamente enviados después de la validación, permitiéndole su edición o cancelación posterior, para añadir un resumen de los puntos principales de la revisión o instrucciones globales acerca de la solicitud y sí usted la aprueba o no. Esta es una forma conveniente puesto que es más flexible y le permite estructurar su revisión, editar los comentarios, publicar cuando esté preparado y enviar una única notificación a los seguidores del repositorio y no una notificación sobre cada comentario. Obtenga más detalles en.

../../_images/githubAddLineComment.png

Figura 1.3 Comentando una línea con una sugerencia de cambio

Los comentarios de línea pueden incorporar sugerencias que el escritor de la solicitud de extracción puede aplicar a la solicitud de extracción. Para agregar una sugerencia, haga clic en el botón githubSuggestions Insert a suggestion en la parte superior del cuadro de texto del comentario y modifique el texto dentro del bloque de sugerencias.

Truco

** Prefiere enviar sugerencias a su solicitud de extracción como un lote **

Como autor de la solicitud de extracción, cuando incorpore directamente los comentarios de los revisores en su solicitud de extracción, evite usar el botón Enviar sugerencia en la parte inferior del comentario cuando tenga muchas sugerencias para abordar y prefiera agregarlas como una confirmación por lotes, es decir:

  1. Cambie a la lengüeta githubFilesChanged

  2. Presione Agregue una sugerencia al lote para cada nueva redacción que desee incluir. Verá un contador aumentando mientras avanza.

  3. Presione cualquiera de los botones Confirmar sugerencias cuando esté listo para aplicar las sugerencias a su solicitud de extracción, e ingrese un mensaje que describa los cambios.

Esto agregará todas las modificaciones a su rama como una única confirmación, lo que dará como resultado un historial de cambios más legible y menos notificaciones para los seguidores del repositorio. Por cierto, continuar así también le ahorrará muchos clics.

Hacer correciones

Se agregará automáticamente una nueva solicitud de extracción a la Lista de solicitudes de extracción. Otros editores y administradores revisarán su solicitud de extracción y pueden hacer sugerencias o solicitar correcciones.

Una solicitud de extracción también activará comprobaciones de compilación automatizadas (por ejemplo, para el primer formato, sintaxis de código Python), y los informes se muestran en la parte inferior de la página. Si se encuentra un error, aparecerá una cruz roja junto a su confirmación. Haga clic en la cruz roja o en Detalles en la sección de resumen en la parte inferior de la página de solicitud de extracción para ver los detalles del error. Tendrá que corregir cualquier error o advertencia informado antes de que sus cambios se envíen al repositorio qgis/QGIS-Documentation.

Puede realizar modificaciones en su solicitud de extracción hasta que se combine con el repositorio principal, ya sea para mejorar su solicitud, para abordar las modificaciones solicitadas o para corregir un error de compilación.

Para realizar cambios, haga clic en | githubFilesChanged | pestaña en su página de solicitud de extracción y haga clic en el botón de lápiz githubEditPencil junto al nombre de archivo que desea modificar.

Cualquier cambio adicional se agregará automáticamente a su solicitud de extracción si realiza esos cambios en la misma rama que envió en su solicitud de extracción. Por esta razón, solo debe realizar cambios adicionales si esos cambios se relacionan con el problema que desea solucionar con esa solicitud de extracción.

Si desea solucionar otro problema, cree una nueva rama para esos cambios y repita los pasos anteriores.

Un administrador fusionará su contribución después de que se corrijan los errores de compilación y después de que usted y los administradores estén satisfechos con los cambios.

1.1.5. Elimina tu rama fusionada

Puede eliminar la rama después de que se hayan fusionado sus cambios. Eliminar ramas antiguas le evita tener ramas no utilizadas y obsoletas en su repositorio.

  1. Navegue a su ramificación del repositorio de documentación de QGIS (https://github.com/<YourName>/QGIS-Documentation).

  2. Click en la pestaña Branches. Abajo Your branches verá una lista de sus ramales.

  3. Click en el icono deleteSelected Delete this branch para eliminar las ramas no deseadas.

1.2. Usando herramientas de línea de comando Git

La interfaz web de GitHub es una manera fácil de actualizar el repositorio de documentación de QGIS con sus contribuciones, pero no ofrece herramientas para:

  • agrupar sus confirmaciones y limpiar su historial de cambios

  • solucionar posibles conflictos con el repositorio principal

  • construir la documentación para probar sus cambios

Necesitará instalar git en su disco duro para tener acceso a herramientas más avanzadas y poderosas y tener una copia local del repositorio. A continuación se exponen algunos conceptos básicos que puede necesitar con frecuencia. También encontrará reglas importantes incluso si opta por la interfaz web.

En los ejemplos de código a continuación, las líneas que comienzan con $ muestra los comandos que debe escribir mientras # son comentarios.

1.2.1. Repositorio local

Ahora está listo para obtener un clon local de su repositorio de documentación de QGIS.

Puede clonar su repositorio QGIS usando la URL web de la siguiente manera:

# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone https://github.com/<YourName>/QGIS-Documentation.git

La primera línea de comando es simplemente un ejemplo. Debe adaptar tanto la ruta como la URL del repositorio, reemplazando <YourName> con su nombre de usuario de github.

Compruebe lo siguiente:

# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin  https://github.com/<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

  • origen es el nombre del repositorio remoto de su Repositorio Documentación de QGIS

  • master es la rama principal predeterminada. ¡Nunca debes usarlo para contribuir! ¡Nunca!

De manera alternativa, puede clonar su repositorio QGIS utilizando el protocolo SSH:

# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone [email protected]:<YourName>/QGIS-Documentation.git

Truco

Permission denied (publickey) error?

Sí obtiene un error de Permiso denegado (clave pública) con el anterior comando, puede haber un problema con su clave SSH. Vea detalles en Ayuda GitHub .

Compruebe lo siguiente si utilizó el protocolo SSH:

# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin  [email protected]:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

Puede comenzar a trabajar aquí, pero en el proceso a largo plazo obtendrá muchos problemas cuando empuje su contribución (llamada Solicitud de extracción en el proceso de github) ya que la rama maestra del repositorio de documentación qgis/QGIS divergerá de su/repositorio remoto. Luego, debe realizar un seguimiento del repositorio remoto principal y trabajar con las ramas.

1.2.2. Adicionar otro repositorio remoto

Para poder seguir el trabajo en el proyecto principal, agregue un nuevo repositorio remoto en su repositorio local. Este nuevo repositorio remoto es el repositorio de documentación QGIS del proyecto QGIS:

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

De manera similar, puede usar el protocolo SSH para agregar un repositorio remoto en su repositorio local:

$ git remote add upstream [email protected]:qgis/QGIS-Documentation.git
$ git remote -v
origin  [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin  [email protected]:<YourName>/QGIS-Documentation.git (push)
upstream        [email protected]:qgis/QGIS-Documentation.git (fetch)
upstream        [email protected]:qgis/QGIS-Documentation.git (push)

Ahora tiene la opción entre dos repositorios remotos:

  • origin to push your local branch in your remote repository

  • upstream para fusionar (si tiene derecho a hacerlo) su contribución a la oficial O para actualizar su rama principal del repositorio local desde la rama principal del repositorio oficial.

Nota

upstream is just a label, a kind of standard name but you can call it as you want.

1.2.3. Actualizar su rama base

Antes de trabajar en una nueva contribución, siempre debe actualizar su rama maestra en su repositorio local. Suponiendo que está dispuesto a introducir cambios en la documentación de prueba, ejecute las siguientes líneas de comando:

# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in the upstream repository
# (aka qgis/QGIS-Documentation's repository)
$ git fetch upstream master
# merge update from upstream/master to the current local branch
# (which should be master, see step 1)
$ git merge upstream/master
# update **your** remote repository (aka <YourName>/QGIS-Documentation)
$ git push origin master

Ahora tiene sus repositorios locales y remotos que tienen su rama master actualizada con la rama master oficial de QGIS-Documentation. Puede empezar a trabajar en su contribución.

Nota

Cambie de rama si desea contribuir al documento publicado

Junto con la documentación de prueba, continuamos solucionando problemas en la última versión, lo que significa que también puedes contribuir a ello. Siga el código de muestra de la sección anterior, reemplazando master con la rama correspondiente de la documentación más reciente.

1.2.4. Contribuir a su rama de producción

Ahora que su sucursal base está actualizada, necesita crear una sucursal dedicada en la que agregue su contribución. ¡Trabaje siempre en una rama que no sea la rama base! ¡Siempre!

# Create a new branch
$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
# Let's check the list of existing branches (* indicates the current branch)
$ git branch
master
release_2.18
...
* myNewBranch
# You can now add your contribution, by editing the concerned file(s)
# with any application (in this case, vim is used)
$ vim myFile
# once done
$ git add myFile
$ git commit

Pocas palabras acerca de comandos commit/push:

  • tratar de comprometer solo una contribución (cambio atómico), es decir, abordar solo un problema

  • intente explicar cuidadosamente lo que cambia en el título de su compromiso y en la descripción. La primera línea es un título y debe comenzar con una letra mayúscula y tener 80 caracteres de longitud, no terminar con un .. Sé conciso. Tu descripción puede ser más larga, terminar con un . Y puedes dar muchos más detalles.

  • use una # con un número para referirse a un problema. Prefijo con Arreglar si arregla el ticket: su confirmación cerrará el ticket.

Ahora que sus cambios están guardados y confirmados en su rama local, debe enviarlos a su repositorio remoto para crear un «pull request»:

$ git push origin myNewBranch

1.2.5. Comparta sus cambios

Ahora puede ir a su repositorio de github y crear una solicitud de extracción como se expone en una sección anterior. Asegúrese de crear un PR desde su sucursal a la sucursal remota a la que se dirige en el repositorio oficial de documentación de QGIS.

1.2.6. Limpiar su repositorio local y remoto

Después de que su «Pull Request» se haya fusionado con la documentación oficial de QGIS, puede eliminar la rama de su repositorio. Si no lo hace en pocas semanas endrá muchas ramas inútiles en su repo. Mantenga su repositorio limpio de esta manera:

# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch

Y no olvide de actualizar la rama master en su repositorio local!

1.3. Lecturas sugeridas

  • Además de la interfaz web de Github y las herramientas de línea de comandos de git expuestas anteriormente, también hay aplicaciones GUI que puede utilizar para crear y gestionar sus contribuciones a la documentación.

  • Cuando los cambios en la solicitud de extracción están en conflicto con los cambios recientes enviados a la rama de destino, los conflictos deben resolverse antes de que sea posible una fusión:

    • si el conflicto se relaciona con pocas líneas en competencia hay disponible un botón Resolver conflictos en la página de peticiones GitHub. Pulse el botón y resuelva la cuestión como se explica en Resolviendo un conflicto de fusión en GitHub

    • si el conflicto concierne a renombrar o quitar archivos, entonces necesitaría resolver el conflicto usando la línea de comandos git. Normalmente, primero debe volver a establecer la base de su rama usando la llamada git rebase targetBranch y corregir los conflictos que allí aparezcan. Lea más en Resolviendo un conflicto de fusión usando la línea de comandos

  • Algunas veces, al final del proceso de revisión, puede terminar con cambios divididos en varias confirmaciones que no necesariamente valen la pena. Las líneas de comando de Git le ayudan a reducir estos compromisos a un número más pequeño y significativo de mensajes de confirmación. Algunos detalles en Usando el rebase git en la línea de comandos