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 un colaborador por primera vez y no sabe por dónde empezar, es posible que le interese abordar nuestros informes de bienvenida.
Hay dos formas principales, no excluyentes entre sí, de modificar los archivos:
Usando la interfaz web de GitHub
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. 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.
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 .
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>.
Cuando termine, haga un breve comentario sobre sus cambios y haga clic en Proponer cambios. Esto generará una nueva rama (
patch-xxx) en su repositorio.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:
Diríjase a su copia -fork- de la documentación QGIS(
https://github.com/<YourName>/QGIS-Documentation)Click en
y busque el ramal patch-xxx. Seleccione este ramal de parches. El botón ahora dirá Branch: patch-xxxSalte 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.
Click en 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 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. Modificar archivos
Explore los archivos fuente de su bifurcación de documentación de QGIS hasta el archivo que necesite ser modificado
Haga sus modificaciones siguiendo las writing guidelines
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.
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”.
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.
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 
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. Todavía puede crear la solicitud de extracción, pero deberá corregir cualquier conflicto para completar la mezcla.
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
Como se vio anteriormente, cualquiera puede enviar modificaciones a la documentación a través de solicitudes de extracción. Del mismo modo, cualquiera puede revisar las solicitudes de extracción con preguntas y comentarios. <https://help.github.com/articles/commenting-on-a-pull-request/>`_. Quizás el estilo de escritura no coincide con las pautas del proyecto, al cambio le faltan algunos detalles importantes o capturas de pantalla, o tal vez todo se ve bien y está en orden. La revisión ayuda a mejorar la calidad de la contribución, tanto en forma como en sustancia.
Para revisar una solicitud de extracción:
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.
En la parte inferior de la página, encontrará un cuadro de texto donde puede dejar comentarios generales sobre la solicitud de extracción.
Para añadir comentarios sobre líneas específicas,
Haga clic en
y encuentre el archivo que desea comentar. Puede que tenga que hacer clic en :guilabel: Mostrar la diferencia de origen para ver los cambios.Desplácese hasta la línea que desea comentar y haga clic en
. 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, presionando el botón: guilabel: Iniciar una revisión. Sus comentarios no se envían automáticamente después de la validación, lo que le permite editarlos o cancelarlos posteriormente, para agregar un resumen de los puntos principales de la revisión o instrucciones globales con respecto a la solicitud de extracción y si la aprueba o no. Esta es la forma conveniente ya que es más flexible y le permite estructurar su revisión, editar los comentarios, publicar cuando esté listo y enviar una sola notificación a los seguidores del repositorio y no una notificación por cada comentario. Obtenga más detalles.
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 
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:
Cambie a la lengüeta
Presione Agregue una sugerencia al lote para cada nueva redacción que desee incluir. Verá un contador aumentando mientras avanza.
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 
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.
Navegue a su ramificación del repositorio de documentación de QGIS (
https://github.com/<YourName>/QGIS-Documentation).Click en la pestaña Branches. Abajo Your branches verá una lista de sus ramales.
Click en el icono
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?
Si recibe un error de Permiso denegado (clave pública) con el comando anterior, es posible que haya un problema con su clave SSH. Consulte la ayuda de GitHub para detalles.
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 conArreglarsi 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.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
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, un botón Resolver conflictos está disponible en la página de solicitud de extracción de Github. Presione el botón y resuelva el problema como se explica en https://help.github.com/articles/resolving-a-merge-conflict-on-github/
si el conflicto involucra el cambio de nombre o la eliminación de archivos, entonces deberá resolver el conflicto usando las líneas de comando de git. Por lo general, primero debe reajustar su rama sobre la rama de destino utilizando la llamada
git rebase targetBranchy corregir los conflictos que se informan. Lea mas en https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
A veces, al final del proceso de revisión, puede terminar con cambios divididos en múltiples confirmaciones que no necesariamente valen la pena. Las líneas de comando de Git te ayudan a reducir estas confirmaciones a un número menor y a mensajes de confirmación más significativos. Algunos detalles en https://help.github.com/articles/using-git-rebase-on-the-command-line/