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.

Los archivos fuente de la documentación se gestionan con el sistema de control de versiones git y están disponibles en GitHub: https://github.com/qgis/QGIS-Documentation. Hay dos formas principales, no mutuamente excluyentes, 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 aún no está familiarizado con el vocabulario de git y GitHub, se recomienda leer el proyecto en GitHub Hello-world <https://guides.github.com/activities/hello-world/> _ para aprender el vocabulario básico y las acciones que se utilizará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. 1. Bifurcar -fork - la documentación de QGIS

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. 2. Realizar 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.

1.1.2.1. Alternative 1: Use the Edit on GitHub shortcut

Pages on the QGIS website can be edited quickly and easily by clicking on the Edit on GitHub link at the top right of each page.

  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 finalice, haga un pequeño comentario sobre sus cambios y haga click en Propose file change. Esto generará un nuevo ramal (patch-xxx) en su repositorio.

  4. Trás clickar en Propose file change github navegará hasta la página Comparing changes.

    • 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

The Edit on GitHub shortcut is also available in the drop-down menu at the bottom of the left sidebar.

1.1.2.2. 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.

Click en githubBranch en la esquina superior izquierda de su enlace QGIS- Repositorio de Documentación y entre un nombre único en el texto de campo para crear un nuevo ramal . El nombre de este nuevo ramal debe redactar el problema que intenta solucionar. EL botón githubBranch ahora debe decir Branch: branch_name

Truco

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. 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. 4. Comparta sus cambios mediante solicitud de extracción

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

Nota

If you used an Edit on GitHub link

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.

1.1.4.1. 1. Iniciar un nuevo «pull request»

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.

1.1.4.2. 2. 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

This means that there are conflicts. The files that you are modifying are not up to date with the branch you are targeting because someone else has made a commit that conflicts with your changes. You can still create the pull request but you’ll need to fix any conflicts to complete the merge.

Truco

Though released and being translated, the documentation of QGIS 3.10 is still maintained and existing issues are fixed. If you are fixing issues for a different release, change base from master to the appropriate release_... branch in the steps above.

1.1.4.3. 3. Describa su «pull request»

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

If this relates to a particular issue, add the issue number to your comments. This is done by entering # and the issue number (e.g. #1234). If preceded by terms like fix or close, the concerned issue will be closed as soon as the pull request is merged.

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

Click en Crear solicitud de extracción.

1.1.4.4. 4. Revisar y comentar solicitud de extracción

As seen above, anyone can submit modifications to the documentation through pull requests. Likewise anyone can review pull requests with questions and comments. Perhaps the writing style doesn’t match the project guidelines, the change is missing some major details or screenshots, or maybe everything looks great and is in order. Reviewing helps to improve the quality of the contribution, both in form and substance.

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.

  • or as part of a review, pressing the Start a review button. Your comments are not automatically sent after validation, allowing you to edit or cancel them afterwards, to add a summary of the main points of the review or global instructions regarding the pull request and whether you approve it or not. This is the convenient way since it’s more flexible and allows you to structure your review, edit the comments, publish when you are ready and send a single notification to the repository followers and not one notification for each comment. Get more details <https://help.github.com/en/articles/reviewing-proposed-changes-in-a-pull-request>.

../../_images/githubAddLineComment.png

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

Line comments can embed suggestions that the pull request writer can apply to the pull request. To add a suggestion, click the githubSuggestions Insert a suggestion button on top of the comment text box and modify the text within the suggestion block.

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. Press any of the Commit suggestions button when you are ready to apply the suggestions to your pull request, and enter a message describing the changes.

This will add all the modifications to your branch as a single commit, resulting in a more legible history of changes and less notifications for the repository followers. Incidentally, proceeding as this will also save you many clicks.

1.1.4.5. 5. Hacer correcciones

A new pull request will automatically be added to the Pull requests list. Other editors and administrators will review your pull request and they may make suggestions or ask for corrections.

A pull request will also trigger a Travis CI build which automatically checks your contribution for build errors. If Travis CI finds an error, a red cross will appear next to your commit. Click on the red cross or on Details in the summary section at the bottom of the pull request page to see the details of the error. You’ll have to fix any reported errors or warnings before your changes are committed to the qgis/QGIS-Documentation repository.

You can make modifications to your pull request until it is merged with the main repository, either to improve your request, to address requested modifications, or to fix a build error.

To make changes click on the githubFilesChanged tab in your pull request page and click the pencil button githubEditPencil next to the filename that you want to modify.

Any additional changes will be automatically added to your pull request if you make those changes to the same branch that you submitted in your pull request. For this reason, you should only make additional changes if those changes relate to the issue that you intend to fix with that pull request.

If you want to fix another issue, create a new branch for those changes and repeat the steps above.

An administrator will merge your contribution after any build errors are corrected, and after you and the administrators are satisfied with your changes.

1.1.5. 5. Delete your merged branch

You can delete the branch after your changes have been merged. Deleting old branches saves you from having unused and outdated branches in your repository.

Navigate to your fork of the QGIS-Documentation repository (https://github.com/<YourName>/QGIS-Documentation). Click on the Branches tab. Below Your branches you’ll see a list of your branches. Click on the deleteSelected Delete this branch icon to delete any unwanted branches.

1.2. Usando herramientas de línea de comando Git

The GitHub web interface is an easy way to update the QGIS-documentation repo with your contributions, but it doesn’t offer tools to:

  • group your commits and clean your change history

  • fix possible conflicts with the main repo

  • construir la documentación para probar sus cambios

You need to install git on your hard drive in order to get access to more advanced and powerful tools and have a local copy of the repository. Some basics you may often need are exposed below. You’ll also find rules to care about even if you opt for the web interface.

In the code samples below, lines beginning with $ show commands you should type while # are comments.

1.2.1. Repositorio local

Now you are ready to get a local clone of your QGIS-Documentation repository.

You can clone your QGIS repository using the web URL as follows:

# 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

The former command line is simply an example. You should adapt both the path and the repository URL, replacing <YourName> with your user name.

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 is the default main branch. You should never use it to contribute! Never!

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?

If you get a Permission denied (publickey) error with the former command, there may be a problem with your SSH key. See GitHub help for details.

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

You can start to work here but in the long terme process you will get a lot of issue when you will push your contribution (called Pull Request in github process) as the master branch of the QGIS-Documentation repository will diverge from your local/remote repository. You then need to keep track of the main remote repository and work with branches.

1.2.2. Adicionar otro repositorio remoto

To be able to follow the work in the main project, add a new remote repository in your local repository. This new remote repository is the QGIS-Documentation repository from QGIS project:

$ 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 to merge (if you have right to do so) your contribution to the official one OR to update your master branch of local repository from the master branch of the official repository.

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

Before working on a new contribution, you should always update your master branch in your local repository. Assuming you are willing to push changes to the testing documentation, run the following command lines:

# 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

Now you have your local and remote repositories which both have their master branch up to date with the official master branch of QGIS-Documentation. You can start to work on your contribution.

Nota

Switch the branch if you wish to contribute to released doc

Along with the testing documentation, we continue to fix issues in QGIS 3.10 doc, meaning that you can also contribute to it. Follow the previous section sample code, replacing master with the corresponding branch of the latest documentation.

1.2.4. Contribuir a su rama de producción

Now that your base branch is updated, you need to create a dedicated branch in which you add your contribution. Always work on a branch other than the base branch! Always!

# 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:

  • try to commit only one contribution (atomic change) i.e. address only one issue

  • try to explain carefully what you change in the title of your commit and in the description. The first line is a title and should start by an upper case letter and have 80 characters length, don’t end with a .. Be concise. Your description can be longer, end with a . and you can give much more details.

  • use a # with a number to refer to an issue. Prefix with Fix if you fix the ticket: your commit will close the 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

Now you can go to your github repository and create a Pull Request as exposed in a previous section. Ensure you create a PR from your branch to the remote branch you are targetting in the official QGIS-Documentation repository.

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. Lectura adicional

  • Other than the Github web interface and the git command line tools exposed above, there are also GUI applications you can use to create and manage your contributions to the documentation.