一歩ずつの貢献

注釈

手順を説明するためにQGIS文書を使用していますが、以下で示すコマンドおよび手順はすべてQGISウェブサイトにも適用されます。

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.

GitHubのWebインターフェイスを使用する

GitHubのWebインターフェイスでは次のことを行うことができます：

  • ファイルを編集する

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

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

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

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

QGISドキュメンテーションに貢献するにはさまざまな方法があります。以下に別々に示しますが、害を及ぼすことなく、あるプロセスから別のプロセスに切り替えることができます。

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.

代替案2：ドキュメンテーションレポジトリにアドホックブランチを作成する

QGISドキュメンテーションのあなたのフォークから直接ファイルを編集できます。

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

ちなみに

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

慣習的に、 qgis/QGIS-Documentation の master ブランチから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つのダイアログボックスが表示されている場合、これは一方のブランチからのマスターブランチへの変更をマージするだけです。この問題を解決するには フォークを越えて比較 リンクをクリックしてください。

../../_images/githubCompareAcrossForks.png

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

4つのドロップダウンメニューが見えるはずです。これらはあなたがあなたのブランチで行った変更をマージしたいマスターブランチと比較することを可能にします。それらは：

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

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

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

  • compare: the branch with those changes

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

../../_images/githubCreatePullRequestComparison.png

Comparing changes between qgis/QGIS-Documentation and your repository

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

Click the Create pull request button.

警告

If you see githubCantMerge

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

ちなみに

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

3. Describe your pull request

テキストボックスが開きます。対処している問題に関連するコメントを入力してください。

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

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 このブランチを削除 アイコンをクリックしてください。

Gitのコマンドラインツールを使用する

GitHubウェブインターフェースはあなたの貢献でQGISドキュメンテーションレポジトリを更新する簡単な方法ですが、それはツールを提供しません：

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

別のリモートリポジトリを追加

メインプロジェクトで作業を追跡できるようにするには、ローカルリポジトリに新しいリモートリポジトリを追加します。この新しいリモートリポジトリはQGISプロジェクトからの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)

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)

だから今は、2つのリモートリポジトリ間の選択肢があります。

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

commit/pushコマンドについて一言：

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

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

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

今、変更は保存されローカルブランチにコミットされましたので、プルリクエストを作成するためにリモートリポジトリに送信する必要があります:

$ git push origin myNewBranch

変更を共有

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

ローカルおよびリモートリポジトリをクリーンアップ

PRが公式QGIS文書にマージされたらブランチは削除してかまいません。このような方法で多くを作業している場合は、数週間のうちに、役に立たない多くのブランチができるでしょう。だからこのような方法でリポジトリをきれいに保ちましょう：

# 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/ に詳細