1. A Step By Step Contribution¶
Though QGIS-Documentation is used to demonstrate the process, all commands and steps shown below also apply to QGIS-Website.
If you are reading these lines, it is certainly because you are willing to contribute to writing QGIS documentation and are looking for a how-to. You have come to the right place! The current document will guide you through the different ways to achieve this objective, showing you the main steps to follow, the tricks you can use and the traps you should be aware of.
Let’s now dive into the process.
Documentation sources are stored using the git version control system and are available on GitHub at https://github.com/qgis/QGIS-Documentation. A list of issues to fix and features to explain can be found at https://github.com/qgis/QGIS-Documentation/issues.
If you are a first-time contributor and do not know where to start from, you may be interested in tackling our welcoming reports.
There are two main ways, not mutually exclusive, to modify the files:
The GitHub web interface allows you to do the following:
preview and commit your changes
make a pull request to have your changes inserted into the main repository
create, update, or delete branches
If you are not yet familiar with git and GitHub vocabulary, you may want to read the GitHub Hello-world project to learn some basic vocabulary and actions that will be used below.
If you are fixing a reported issue
If you are making changes to fix an issue, add a comment to the issue report to assign it to yourself. This will prevent more than one person from working on the same issue.
Assuming you already have a GitHub account, you first need to fork the source files of the documentation.
Navigate to the QGIS-Documentation repository page and click on the button in the upper right corner.
In your GitHub account you will find a QGIS-Documentation repository
This repository is a copy of the official QGIS-Documentation repository where
you have full write access and you can make changes without affecting the
There are different ways to contribute to QGIS documentation. We show them separately below, but you can switch from one process to the other without any harm.
Pages on the QGIS documentation website can be edited quickly and easily by clicking on the
Edit on GitHub link at the top right of each page.
This will open the file in the
qgis:masterbranch 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 to a new branch of your repository.
Do your changes. Since the documentation is written using the reStructureText syntax, depending on your changes, you may need to rely on the writing guidelines.
When you finish, make a short comment about your changes and click on Propose changes. This will generate a new branch (
patch-xxx) in your repository.
After you click on Propose changes, github will navigate to the Comparing changes page.
If there are additional changes that you want to make before submitting them to QGIS, follow these steps:
Navigate to your fork of QGIS-Documentation (
Jump down to Modify files below.
Edit on GitHub shortcut is also available in the drop-down
menu at the bottom of the left sidebar.
You can edit files directly from your fork of the QGIS Documentation.
Click on in the upper left corner of your forked QGIS- Documentation repository and enter a unique name in the text field to create a new branch . The name of the new branch should relate to the problem you intend to fix. The button should now say Branch: branch_name
Do your changes in an ad hoc branch, never in the
By convention, avoid making changes in your
master branch except when
you merge the modifications from the
master branch of
into your copy of the QGIS-Documentation repository.
Separate branches allow you to work on multiple problems at the same time
without interfering with other branches. If you make a mistake you can
always delete a branch and start over by creating a new one from the master
Browse the source files of your fork of QGIS-Documentation to the file that needs to be modified
Make your modifications following the writing guidelines
When you finish, navigate to the Commit Changes frame at the bottom of the page, make a short comment about your changes, and click on Commit Changes to commit the changes directly to your branch. Make sure Commit directly to the branch_name branch. is selected.
Repeat the previous steps for any other file that needs to be updated to fix the issue
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.
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
build the documentation to test your changes
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
# are comments.
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
with your github user name.
Check the following:
# 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
origin is the name of the remote repository of your QGIS-Documentation repository.
master is the default main branch. You should never use it to contribute! Never!
Alternatively you can clone your QGIS repository using the SSH protocol:
# 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
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.
Check the following if you used the SSH protocol:
You can start to work here but in the long term process you will get a lot of issues when you will push your contribution (called Pull Request in github process) as the master branch of the qgis/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.
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)
Similarly, you can use the SSH protocol to add a remote repository in your local repository:
$ 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)
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.
upstream is just a label, a kind of standard name but you can call it as you want.
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
branch up to date with the official
master branch of QGIS-Documentation.
You can start to work on your contribution.
Switch the branch if you wish to contribute to released doc
Along with the testing documentation, we continue to fix issues in the
latest release, meaning
that you can also contribute to it. Follow the previous section sample code,
master with the corresponding branch of the latest documentation.
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
Few words about commit/push commands:
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.
#with a number to refer to an issue. Prefix with
Fixif 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
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
And do not forget to update the
master branch in your local repository!
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.
When the changes in the pull request are conflicting with recent changes pushed to the target branch, the conflicts need to be resolved before a merge is possible:
if the conflict relates to few competing lines, a Resolve conflicts button is available in the Github pull request page. Press the button and resolve the issue as explained at https://help.github.com/articles/resolving-a-merge-conflict-on-github/
if the conflict involves files renaming or removal, then you’d need to resolve the conflict using git command lines. Typically, you have to first rebase your branch over the target branch using
git rebase targetBranchcall and fix the conflicts that are reported. Read more at https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
Sometimes, at the end of the proofreading process, you may end up with changes split into multiple commits that are not necessarily worth it. Git command lines help you squash these commits to a smaller number and more meaningful commit messages. Some details at https://help.github.com/articles/using-git-rebase-on-the-command-line/