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.

Ahora que usted conoce las reglas para seguir y crear un documento limpio para QGIS, entremos en el proceso de producción de esta documentación y cómo rápidamente y con seguridad compartir sus cambios con la comunidad.

Suponiendo que ya tiene una cuenta de GitHub <https://github.com/join> _, necesita primero copiar los archivos de origen de la documentación para poder tener su propia copia con que trabajar: ve al repositorio de la documentación- QGIS <https://github.com/qgis/QGIS-Documentation> _page (para su comodidad, este repositorio abajo es llamado qgis/QGIS-Documentation) y haga clic en el botón ** Fork ** en la esquina superior derecha.

Pocos segundos más tarde, en su cuenta de GitHub encontrará un repositorio de documentación de QGIS (https://github.com/<YourName>/QGIS-Documentation). Este repositorio es una copia de seguridad en el que tienes acceso completo de escritura y puede subir todas sus contribuciones sin un riesgo de afectar a la documentación oficial. Al principio, este repositorio contiene las mismas ramas como qgis/QGIS-Documentation y está predeterminado a rama ‘’ master’‘. Las ramas son líneas paralelas de desarrollo que contienen diferentes imágenes del documento que se pueden combinar o divergir. Es preferible crear una rama para cada tema que desea resolver y puede crear tantas ramas como quiera.

Truco

Haga sus cambios en una rama de ad hoc, nunca en master.

By convention, avoid making changes in your master branch except merging the modifications from the master branch of qgis/QGIS-Documentation (called qgis:master). And use it as model to create new branches for a clean history and snapshot.

There are different ways to contribute to QGIS documentation. Though we expose them below separately, they are not mutually exclusive, meaning that you can, at any moment, switch from one process to another without any harm because they both follow the scheme below:

  1. Haga sus modificaciones en una rama ad’hoc de su repositorio.

  2. Publique sus cambios y pida para combinarse en el documento principal a través de una solicitud de extracción. (PR)

  3. Others review, discuss and integrate your work in the main branch when everything seems ok.

Using GitHub web interface

From your cloned repository, you can now propose changes to the main documentation. Indeed, GitHub web interface offers you ways to easily:

  • edit files, preview and commit your changes
  • make a pull request to have your changes inserted in the main repo

  • crear, actualizar o eliminar ramas

Read the GitHub Hello-world project to learn some basic vocabulary and actions that will be used below.

Make changes in your repo

Documentation can be improved by addressing issues reported at https://github.com/qgis/QGIS-Documentation/issues or issues you may have encountered while browsing the doc. They can be of different types: typo error, missing feature, wrong or out of date description...

Alternative 1: Picking an issue in the list

  1. Select an issue you want to fix. To avoid many persons tackling the same issue, you can inform contributors about your choice by adding a comment to the issue report and get it assigned to you.
  2. From your repository, create (and switch to) a branch with a name that helps you remind what it’s about
  3. Browse the source files to the file that has to be changed
  4. Toggle the file into Edit mode using the pencil icon and do your modifications following guidelines
  5. Validate your changes by filling the Commit Changes frame and commit directly to your branch.
  6. Redo the previous steps for any other file that needs to be updated to fix the issue.

Alternative 2: Using the Fix Me shortcut

The QGIS project provides an easy way to reach source file from online documentation. Indeed, instead of browsing the source files in GitHub to find the one that suits the issue, or if you find an issue while reading the manuals, you simply have to click the “Fix Me” link at the bottom of the page to open its source file in Edit mode.

  1. This will open the file in the qgis:master branch with a message at the top of the page telling you that you don’t have write access to this repo and your changes will be applied in a new branch of your repository.
  2. Do your changes following guidelines available at http://docs.qgis.org/testing/en/docs/documentation_guidelines/
  3. When you finish, at the bottom of the page, comment a bit what your changes are about and click on Propose File change. This will generate a new branch (patch-xxx) in your repo.

Truco

If your master branch is even with qgis:master, you can safely replace in the link qgis by <YourName>. In this case, once your changes are done, you need to check radioButtonOn Create a new branch for this commit and start a pull request and avoid modifying master.

Comparta sus cambios vía Pedidos Pull

Now, you have a new branch in QGIS with a file that diverge from qgis:master. To integrate your changes in the official documentation, you need to do a pull request.

  1. De hecho, después de que hace commit de sus cambios, GitHub abre un nuevo diálogo comparando ramas:

    • if you used the Fix Me without changing the url, then the comparison is between your patch-xxx branch and qgis:master (the base fork is qgis/QGIS-Documentation and its branch master).
    • if you used a branch you had named yourself then the comparison is done between that branch and your own master branch (the base is simply master). You therefore need to leave that page and follow the next step.

  2. In any case (including pushing branch to GitHub from command lines) you can create a new pull request at any moment from many pages. Simply go to the main page of the repository (yours or qgis), click on New Pull Request and Compare across forks (if needed). Ensure you select qgis/QGIS-Documentation with master as base branch and that the head fork is your repository <YourName>/QGIS-Documentation with your modified branch along.

    Truco

    Though released and being translated, the documentation of QGIS 2.14 is still maintained and existing issues are fixed. If you plan to fix the issues in the current released doc, replace master branch by the appropriate manual_en_... branch in any of the steps exposed earlier.

  3. A green check along the compared branches shows that your changes can automatically be merged in the official doc. Click the Create pull request button. If you get a red cross, it means that the files you are modifying were not up to date with the branch you are targetting (a commit has been pushed to it since you create or last update your branch). You then need to use git command line tools to fix it.

  4. Fill the form if needed and click again Create pull request button.

  5. A new PR is added to https://github.com/qgis/QGIS-Documentation/pulls and everybody can look or comment it.

  6. That will trigger a Travis CI build automatically checking if your contribution doesn’t contain a build error. In case of error, a red cross appears along your commit. Simply click on it or on Details in the summary section at the bottom of the page to have details on the error. You’ll need to fix any reported error or warning before your changes are committed in the repository.

  7. Until your PR is merged with the main repo, you can add modifications to your proposal. Actually any new changes done to your branch is appended to your pull request. Do it if the change has to do with the issue you are fixing, otherwise create a new branch for those changes following steps above.

  8. Una vez que todo le parezca bien a usted y otros, un encargado de commit puede fusionar su rama con el repositorio principal. Su contribución será validada.

  9. If you want, you can now delete the branch you used, to avoid having too many (unused and outdated) branches crowding your repository.

Haciendo estos pequeños pasos le hará aprender el proceso más fácil

Advertencia

Be vigilant to pull request against qgis:master and not your own master branch, otherwise nobody is aware of your changes and you may mistakenly merge your changes into your master branch, polluting its history.

Truco

Automatically close issue report from pull request

To ease issue reports management, mention the number of the issue you are addressing in your pull-request. This can be done using #issue_number. If preceded by terms like fix, close... the concerned issue is closed as soon as the pull request is merged.

Using Git command line tools

GitHub web interface helps you update the repo with your contribution in an easier way but it doesn’t offer tools to:

  • group your commits and clean your changes history
  • fix conflicts with the main repo if needed...

  • construir la documentación para probar sus cambios

You then 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.

Repositorio local

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

$ cd ~/Documents/Development/QGIS/
$ git clone git@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.

Truco

Permission denied (publickey) error?

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

Revise:

$ git remote -v
origin  git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin  git@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!

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.

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 git@github.com:qgis/QGIS-Documentation.git
$ git remote -v
origin  git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin  git@github.com:<YourName>/QGIS-Documentation.git (push)
upstream        git@github.com:qgis/QGIS-Documentation.git (fetch)
upstream        git@github.com:qgis/QGIS-Documentation.git (push)

So now you have the choice between two remote repository:

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

Actualizar su rama base

Para probar doc (rama maestra)

Before working on a new contribution, you should always update your local master branch in your local repository. Just run this command line:

# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in 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
$ git push origin master

Now you have a local and remote repositories which have both master branch up to date with QGIS-Documentation from QGIS organisation. You can start to work on your contribution.

For released doc (manual_en_ branch)

Along the testing documentation, we continue to fix issues in QGIS 2.14 doc, meaning that you can also contribute to it. Following the previous section sample code, you can easily do that by selecting the corresponding branch.

When you clone the repository (see Repositorio local), your clone has all the branches of the upstream repository. As above, you need to ensure your branch is up to date with the upstream’s:

# change branch e.g. for 2.14 LTR
$ git checkout manual_en_2.14
# get "information" from the manual_en_2.14 branch in upstream repository
$ git fetch upstream manual_en_2.14
# merge update from upstream/manual_en_2.14 to the current local branch
$ git merge upstream/manual_en_2.14
# update **your** remote repository
$ git push origin manual_en_2.14

In this way your local and remote branches for the 2.14 version are up to date with the one of the official upstream repository.

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!

$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
$ git branch
master
manual_en_2.14
* myNewBranch
# a list of existing branch where * means the current branch
# You can now add your contribution, by editing the concerned file
# 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.

Now that your changes are saved and committed in your local branch, you need to send them to your remote repository in order to create pull request:

$ git push origin myNewBranch

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.

Limpiar su repositorio local y remoto

After your PR has been merged into the official QGIS-Documentation, you can delete your branch. If you work a lot this way, in few weeks you will get a lot of unuseful branches. So keep your repository clean this way:

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