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.

For any help, do not hesitate to either ask in a comment on the issue report you are trying to fix or write to the QGIS-community-team list. More details at Get involved in documentation.

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. There are two main ways, not mutually exclusive, to modify the files:

  1. Using the GitHub web interface

  2. Using Git command line tools.



  • ファイルを編集する

  • 変更をプレビューし、コミットする

  • 変更がメインリポジトリに挿入されるようにプルリクエストを行う

  • ブランチを作成、更新または削除する

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

あなたが 問題 を修正するために変更を加えているなら、それをあなた自身に割り当てるためにissueレポートにコメントを加えてください。これにより、複数の人が同じ問題に取り組むことを防ぐことができます。

1. Fork QGIS-Documentation

あなたが既に GitHubアカウント を持っていると仮定すると、まずドキュメントのソースファイルをフォークする必要があります。

QGIS-Documentation repository ページに移動して、右上隅の githubFork ボタンをクリックします。

ご自身のGitHubアカウントにQGIS-Documentationリポジトリ( https://github.com/<YourName>/QGIS-Documentation )があるでしょう。このリポジトリは公式のQGIS-Documentationリポジトリのコピーですが、完全な書込権限が与えられていて、公式のドキュメントに影響を与えることなく変更を加えることができます。

2. Make changes


Alternative 1: Use the Fix Me shortcut

QGISウェブサイト上のページは各ページのフッターにある Fix Me リンクをクリックすることで素早く簡単に編集することができます。

  1. これは qgis:master ブランチ中のファイルを開き、ページの上部には、このリポジトリへの書込アクセス権はなく変更はリポジトリの新しいブランチで適用されます、と知らせるメッセージが出ます。

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

  3. 終了したら、あなたの変更について短いコメントを書いて ファイル変更を提案 をクリックしてください。これはあなたのリポジトリに新しい ブランチpatch-xxx )を作成します。

  4. ファイルの変更を提案 をクリックした後、githubは 変更の比較 ページに移動します。

    • 変更が終わったら、以下の Pull Request で変更をシェアする セクションの 変更を比較 にスキップしてください。

    • QGISに送信する前に追加の変更が必要な場合は、次の手順に従ってください。

      1. Navigate to your fork of QGIS-Documentation (https://github.com/<YourName>/QGIS-Documentation)

      2. githubBranch をクリックして、 `` patch-xxx``ブランチを検索してください。このパッチブランチを選択してください。 githubBranch ボタンはこうなります Branch: patch-xxx

      3. Jump down to Modify files below.



フォークしたQGISドキュメントリポジトリの左上隅にある githubBranch をクリックして、テキストフィールドに一意の名前を入力して新しい ブランチ を作成してください。新しいブランチの名前は、修正しようとしている問題に関連しているはずです。すると githubBranch ボタンはnow say Branch: branch_name となるはずです。


Do your changes in an ad hoc branch, never in the master branch

慣習的に、 qgis/QGIS-Documentationmaster ブランチからQGIS-Documentationリポジトリのコピーに変更をマージする場合を除いて、 master ブランチを変更しないでください。別々のブランチを使用すると、他のブランチに干渉することなく、同時に複数の問題に取り組むことができます。間違えた場合は、いつでもブランチを削除してから、マスターブランチから新しいブランチを作成することからやり直すことができます。

3. Modify files

  1. QGIS-Documentationのあなたのフォークのソースファイルを修正する必要があるファイルにブラウズしてください

  2. Make your modifications following the writing guidelines

  3. 終了したら、ページの一番下にある 変更をコミット フレームにナビゲートし、行った変更について短いコメントを書き、そして 変更をコミット をクリックしてあなたのブランチに直接変更をコミットしてください。 branch_nameブランチに直接コミットする が選択されていることを確認してください。

  4. 問題を修正するために更新する必要がある他のファイルについて上記の手順を繰り返します。

4. Share your changes via Pull Request

変更を公式文書に統合するためにはpull requestをする必要があります。


If you used a Fix Me link

変更をコミットした後、GitHubはあなたの patch-xxx ブランチで行った変更を qgis/QGIS-Documentation マスターブランチと比較する新しいページを自動的に開きます。

Skip to Step 2 below.

1. Start a new pull request

QGIS-Documentation リポジトリのメインページに行き、 新しいpull request をクリックしてください。

2. Compare changes

一方が base:master 、もう一方が ``compare:branch_name` (図を参照)という2つのダイアログボックスが表示されている場合、これは一方のブランチからのマスターブランチへの変更をマージするだけです。この問題を解決するには フォークを越えて比較 リンクをクリックしてください。


変更の比較 ページがこのようなものであれば、 フォーク全体の比較 リンクをクリックしてください。


  • ベースフォーク :変更をマージしたいフォーク

  • base :変更をマージしたいベースフォークのブランチ

  • ヘッドフォーク :ベースフォークに組み込みたい変更があるフォーク

  • compare: the branch with those changes

qgis/QGIS-Documentation をas the base fork with master をベースとするベースフォークとして選択し、ヘッドフォークを あなたのリポジトリ <YourName>/QGIS-Documentation に設定して、変更したブランチと比較してください。


Comparing changes between qgis/QGIS-Documentation and your repository

マージ可能 という単語の付いた緑色のチェックマークは、あなたの変更が衝突することなく公式の文書にマージできることを示しています。

Click the Create pull request button.


If you see githubCantMerge

これは 衝突 があることを意味します。他の誰かがあなたの変更と衝突するコミットをしたので、修正中のファイルはターゲットとしているブランチを持つ最新ではありません。それでもプルリクエストは作成できますが、マージを完了するには conflicts を修正する必要があります。


QGIS 3.4 のドキュメントは、リリースされ翻訳されていますが、まだ保守中であり既存の問題が修正されています。別のリリースの問題を修正している場合は、上記の手順で basemaster から適切な release_... ブランチに変更してください。

3. Describe your pull request


これが特定の 問題 に関連する場合は、コメントに問題番号を追加してください。これは#と問題番号 ( #1234 )を入力することによって行われます。 fixclose のような用語が先行している場合は、プルリクエストがマージされるとすぐにその問題は解決されます。

Add links to any documentation pages that you are changing.

Click on Create pull request

4. Make corrections

新しいプルリクエストは自動的に プルリクエストリスト に追加されます。他の編集者や管理者があなたのpull requestを見直し、提案をしたり修正を求めたりするかもしれません。

プルリクエストによって Travis CIビルド も実行されます。これはあなたの貢献をビルドエラーについて自動的にチェックします。 Travis CIがエラーを見つけた場合は、コミットの横に赤い×印が表示されます。エラーの詳細を見るには、プルリクエストページの下部にある概要セクションの赤い十字または「詳細」をクリックしてください。変更が qgis/QGIS-Documentation リポジトリにコミットされる前に、報告されたエラーや警告を修正する必要があります。


変更するには githubFilesChanged をクリックします。プルリクエストページのタブをクリックして、変更するファイル名の横にある鉛筆ボタン githubEditPencil をクリックします。




5. Review and comment pull request

プルリクエストの変更について コメント をすることができます。 プルリクエストページ に移動して、コメントしたいプルリクエストをクリックします。


特定の行に関するコメントを追加するには、 githubFilesChanged をクリックして、コメントしたいファイルを見つけてください。変更を見るために Load diff をクリックしなければならないかもしれません。コメントしたい行までスクロールして、 githubBluePlus をクリックします。コメントを残すことを可能にするテキストボックスが開くでしょう。

5. Delete your merged branch


QGIS-Documentationリポジトリのフォークに移動します( https://github.com/<YourName>/QGIS-Documentation )。 ブランチ タブをクリックしてください。 あなたのブランチ 下に、あなたの枝のリストが見えます。不要なブランチを削除するには、 deleteSelected このブランチを削除 アイコンをクリックしてください。



  • group your commits and clean your change history

  • fix possible conflicts with the main repo

  • 変更をテストするための文書を構築する

より高度で強力なツールへのアクセスを取得し、リポジトリのローカルコピーを持っているために、ハードドライブ上に gitをインストール する必要があります。多くの場合に必要かもしれないいくつかの基本は以下に公開されます。また、Webインターフェイスを選ぶ場合でも、気にするルールを見つけることができます。

以下のコードサンプルでは、 $ で始まる​​行はあなたが入力する必要があるコマンドを示し、 # はコメントです。


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

以前のコマンドラインは、単に一例です。 <YourName> をご自分のユーザー名で置き換え、パスとリポジトリURLの両方を適合させる必要があります。

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 は、あなたのQGIS-ドキュメントリポジトリのリモートリポジトリの名前です。

  • master はデフォルトのメインブランチです。あなたは貢献するためにそれを使用しないでください! 決して!

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



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:

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



$ 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)


  • origin あなたの リモートリポジトリにあなたのローカルブランチをプッシュする

  • upstream あなたの貢献を公式のものにマージ(そうする権利がある場合)したり、公式リポジトリのマスターブランチからローカルリポジトリのマスターブランチを更新します。


upstream はただのラベルで、標準の名前のようなものですが、好きなようにお呼びください。


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.


Switch the branch if you wish to contribute to released doc

Along with the testing documentation, we continue to fix issues in QGIS 3.4 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.



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


  • 一つだけの貢献(原子的変更)コミットするようにしてください、すなわち1つの問題だけアドレス

  • コミットのタイトルおよび説明の中で、変更するものを丁寧に説明するようにしてください。最初の行はタイトルで、大文字で始まり80文字の長さを持っていること、 . では終わらないことが必要です。簡潔に。説明はより長くでき、 . で終了でき、より多くの詳細を与えることができます。

  • 問題を参照するために # を番号とともに使用してください。チケットを修正する場合は Fix でプレフィックスしてください:コミットするとチケットは閉じます。


$ git push origin myNewBranch


これであなたのgithubのリポジトリに行って、前のセクションで公開されたように プルリクエストを作成 できます。ご自分のブランチから公式QGIS文書リポジトリ中のターゲットとしているリモートブランチへのPRを作成していることを確認してください。



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

そしてローカルリポジトリ中の master ブランチを更新することを忘れずに!

Further reading

  • 上記のGithub Webインターフェースとgitコマンドラインツール以外に、ドキュメントへの貢献を作成および管理するために使用できる GUIアプリケーション もあります。 。

  • プルリクエストの変更がターゲットブランチにプッシュされた最近の変更と矛盾している場合は、マージが可能になる前に矛盾を解決する必要があります。

    • 競合が競合する数行に関連している場合は、Githubのpull requestページに 競合の解決 ボタンがあります。 https://help.github.com/articles/resolving-a-merge-conflict-on-github/ で説明されているようにボタンを押し、問題を解決して下さい

    • 競合がファイルの名前変更または削除を伴う場合は、gitコマンドラインを使用して競合を解決する必要があります。典型的には、最初に git rebase targetBranch 呼び出しを使ってターゲットブランチの上にあなたのブランチをリベースし、報告された衝突を修正しなければなりません。詳細は https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/

  • 場合によっては、校正プロセスの最後に、変更が複数のコミットに分割されてしまうことがあります。分割されたコミットが必ずしもそれだけの価値があるわけではありません。 Gitコマンドラインは、これらのコミットをより少数の、より意味のあるコミットメッセージに変換するのに役立ちます。 https://help.github.com/articles/using-git-rebase-on-the-command-line/ に詳細