1. 貢献のための一歩一歩¶
注釈
ここでは手順の説明のためにQGISドキュメントを使用しますが、以下で説明するコマンドおよび手順はすべて、QGISウェブサイトにも当てはまります。
あなたがこの文章を読まれているということはきっと、QGISドキュメントに貢献しようという気持ちがあって、そのための方法を探されているのでしょう。 ここで提供しようとしているのは、まさしくそれです。現在この文書では、目的を達成するための複数の方法を一通り案内し、従うべき主な手順を示し、使用可能な小技と知っておくべき落とし穴を教えています。
何か助けが必要なときには迷わず、修正しようとしているIssueレポートのコメントに書き込むか、 QGISコミュニティチームメーリングリスト に投稿をしてください。より詳しくは ドキュメントを書く をご覧ください。
さあ、では集中して始めてみましょう。
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:
1.1. GitHub のウェブインタフェースを使用する¶
GitHubのウェブインタフェースでは次のことを行うことができます。
ファイルを編集する
変更をプレビューし、コミットする
変更がメインリポジトリに挿入されるようにプルリクエストを行う
ブランチを作成、更新または削除する
gitやGitHubで使われる言葉にまだ馴染みがない場合は、GitHubの Hello-world プロジェクトを読んで、以下でも使われる基本的な語彙と操作について学んだ方がいいでしょう。
注釈
報告されたIssueをあなたが修正中なら
もしあなたが issue を修正するための変更を加えている最中なら、issueレポートにコメントをして、それをあなた自身に割り当ててください。これにより、複数の人が同じissueに取り組むことを防ぐことができます。
1.1.1. Fork QGIS-Documentation¶
GitHubアカウント はすでに取得しているものと仮定すると、まず最初にするべきは、ドキュメントのソースファイルをフォークすることです。
QGIS-Documentation のリポジトリ ページに移動して、右上隅の 
ボタンをクリックします。
ご自身のGitHubアカウントに、QGIS-Documentationリポジトリ (https://github.com/<YourName>/QGIS-Documentation) が作られていることと思います。このリポジトリは公式のQGIS-Documentationリポジトリのコピーです。あなたに完全な書込権限が与えられていて、公式のドキュメントに影響を与えることなく変更を加えることができます。
1.1.2. Make changes¶
QGISドキュメンテーションに貢献するにはいくつかの異なった方法があります。以下ではそれらを別々に示しますが、あるプロセスから別のプロセスに切り替えることに何ら問題はありません。
選択肢 1： Edit on GitHub ショートカットを使用する¶
QGIS ドキュメントのそれぞれのページは、ページの右上にある Edit on GitHub というリンクをクリックすると、素早く簡単に編集することができます。
Edit on GitHubをクリックすると、qgis:masterブランチのファイルが開きます。ページの上部には、あなたにはこのリポジトリへの書込権限がないため、変更はあなたのリポジトリの新しいブランチで適用される旨を知らせるメッセージが、表示されます。変更を行います。ドキュメントはreStructureTextシンタックスを使用して書かれていますので、変更の内容によっては、 執筆のためのガイドライン を参照しながら行う必要があるかもしれません。
終了したら、行った変更について短いコメントを書いて、 Propose changes をクリックします。これによってあなたのリポジトリに新しい ブランチ (
patch-xxx) が作成されます。Propose changes をクリックすると、GitHubの Comparing changes ページに移動します。
すべての変更が終わったら、下の プルリクエストで変更をシェアする のセクションの、 変更を比較 にスキップしてください。
QGISに送信する前に追加の変更が必要な場合は、次の手順に従ってください。
フォークしたあなたのQGIS-Documentation (
https://github.com/<YourName>/QGIS-Documentation) リポジトリに移動します。
をクリックして `` patch-xxx`` ブランチを探し、このブランチを選択します。 ボタンが Branch: patch-xxx に変わります。下の ファイルを修正する に飛んでください。
注釈
Edit on GitHub ショートカットは左サイドバーの一番下のドロップダウンメニューからも利用できます。
選択肢 2：あなたのドキュメンテーションレポジトリに一時的な専用ブランチを作成する¶
あなたがフォークしたQGIS-Documentationで直接ファイルを編集できます。
フォークしたQGIS-Documentationリポジトリの左上隅にある をクリックして、テキストフィールドに一意の名前を入力して新しい ブランチ を作成します。新しいブランチの名前は、修正しようとしている問題に関連していなければなりません。すると ボタンは Branch: branch_name となるはずです。
ちなみに
変更はこの一時的な専用ブランチで行うこと。絶対に master ブランチでは行わないこと
qgis/QGIS-Documentation の master ブランチからあなたのQGIS-Documentationリポジトリに変更をマージする場合を除いて、 慣例として master ブランチでは変更を行わないでください。問題ごとに別々のブランチを使用することによって、他のブランチに干渉することなく、同時に複数の問題に取り組むことができます。間違えた場合は、いつでもブランチを削除して、masterブランチから新しいブランチを作成してやり直すことができます。
1.1.3. Modify files¶
フォークしたQGIS-Documentationのソースファイルをブラウズして、修正する必要があるファイルに移動します。
執筆のためのガイドライン に従いながら修正を行います。
終了したら、ページの一番下にある Commit Changes フレームに移動し、行った変更について短いコメントを書き、そして Commit Changes をクリックしてあなたのブランチに直接変更をコミットします。 Commit directly to the branch_name branch. が選択されていることを確認してください。
問題を修正するために更新する必要がある他のファイルについて上記の手順を繰り返します。
1.1.4. Share your changes via Pull Request¶
あなたの変更を公式ドキュメントに統合するためにはプルリクエストをする必要があります。
注釈
Edit on GitHub リンクを使用して始めた場合は
変更をコミットした後、GitHubはあなたの patch-xxx ブランチで行った変更を qgis/QGIS-Documentation マスターブランチと比較する新しいページを自動的に開きます。
下の Step 2 にスキップしてください。
Start a new pull request¶
QGIS-Documentation リポジトリのメインページに行き、 New pull request をクリックします。
Compare changes¶
一方が base:master 、もう一方が ``compare:branch_name` （図を参照）という2つのダイアログボックスが表示されている場合は、あなたの行った変更はあなたのリポジトリの中で、変更を加えたブランチからあなたのマスターブランチへとマージされるだけです。これを修正するために compare across forks と表示されているリンクをクリックします。
図 1.1 Comparing changes ページがこのようなものだったら、 compare across forks リンクをクリックします。¶
4つのドロップダウンメニューが表示されていることと思います。このドロップダウンメニューによって、あなたのブランチで行った変更を、変更をマージしたい相手である公式のマスターブランチと比較することが可能になります。4つのドロップダウンメニューは以下の通りです。
base fork ：あなたの変更をマージしたい相手先のフォーク
base ：あなたの変更をマージしたいbase forkのブランチ
head fork ：base forkに組み込みたい変更があるフォーク
compare ： 変更が行われたブランチ
base fork で qgis/QGIS-Documentation を、base で master を選択します。head fork をあなたのリポジトリ <YourName>/QGIS-Documentation に、compare をあなたが変更を行ったブランチに設定します。
図 1.2 qgis/QGIS-Documentation とあなたのリポジトリとの間で変更を比較している¶
Able to merge と書いてある緑色のチェックマークは、あなたの変更が衝突することなく公式のドキュメントにマージできることを示しています。
Create pull request ボタンをクリックします。
警告
と表示されたら
これは 競合 があることを意味します。他の誰かがあなたの変更と競合するコミットをしたので、あなたが修正中のファイルは対象のブランチの最新の状態を反映していません。それでもプルリクエストは作成できますが、マージを完了するには 競合 を修正する必要があります。
ちなみに
最新バージョン のQGISドキュメントは、翻訳されてはいますが、保守は継続しており、問題が見つかれば修正が行われています。特定リリースの問題を修正する場合は、上記の手順で base を master から適切な release_... ブランチに変更してください。
Describe your pull request¶
テキストボックスが開きます。対処している問題に関するコメントを入力します。
これが特定の issue に関連する場合は、コメントにissue番号を追加します。これは＃とissue番号 (例 #1234) を入力することによって行われます。 直前に fix や close のような語が置かれている場合は、プルリクエストがマージされると、すぐにそのissueはクローズされます。
あなたが変更を行ったすべてのドキュメントのページへのリンクを含めてください。
Create pull request をクリックします。
Review and comment pull request¶
上で見たように、誰でもプルリクエストを通してドキュメントの修正を提案することができます。同様に、誰でも質問や コメント でプルリクエストをレビューすることが可能です。おそらくそれは、プロジェクトのガイドラインに沿っていない執筆スタイルだったり、重要な細部やスクリーンショットが変更に欠けていたり、あるいはすべてが素晴らしくて申し分なさそうだ、ということだったりするでしょう。レビューはドキュメントの形式と実質の両面において、貢献の質を高める助けになります。
プルリクエストをレビューするには
pull requests のページ へ移動して、コメントをしたいプルリクエストをクリックします。
ページの一番下に、このプルリクエストについて全体的なコメントを残すことのできるテキストボックスがあると思います。
特定の行についてコメントをするには、
をクリックして、コメントをしたいファイルを探します。 変更を確認するために Display the source diff をクリックしないといけないかもしれません。コメントしたい行までスクロールして、
をクリックします。テキストボックスが開きますので、コメントを残すことができます。
特定の行に対するコメントは、次のいずれかの方法で公開することができます。
Add single comment ボタンを使って、単独のコメントとして公開する。この場合コメントはその都度即座に公開されます。コメント数が少ない場合や他のコメントにコメントする場合にのみ、この方法を使ってください。
Start a review ボタンを押して、レビューの一部として公開する。コメントは検証後に自動的に送信されないため、後で編集やキャンセルしたり、レビューの主要な点を要約したりそのプルリクエストについての全体的な指示を追加したり、そのプルリクエストを承認するかどうかを述べたりすることができます。こちらの方がよりよい方法でしょう。より柔軟ですし、レビューを構造化したりコメントを編集したりして準備ができてから公開することができますし、リポジトリのフォロワーにコメントごとに通知を送るのではなく、ひとつだけ通知を送ることができるからです。 より詳しくは を参照してください。
図 1.3 特定の行に対して修正の提案とともにコメントを行う¶
行に対するコメントには提案を埋め込むことができ、プルリクエストの作成者はこれをプルリクエストに適用することができます。提案を追加するには、コメントテキストブロックの上にある 
Insert a suggestion ボタンをクリックして、提案ブロックの中のテキストを修正します。
ちなみに
プルリクエストへの提案をバッチとして追加したいときは
プルリクエストの作成者としてレビュワーからのフィードバックを直接プルリクエストに組み込むときに、対処すべき提案の数が多いためにそれらをバッチコミットとして追加したい場合は、コメントの一番下にある Commit suggestion ボタンを使用するのは避けてください。 すなわち、以下のようにします。
- タブに移動します。
取り込みたい提案のそれぞれで Add suggestion to batch を押します。押すごとにカウンターが増えるのが分かると思います。
取り込みたいすべての提案をプルリクエストに適用する準備ができたら、どれでもいいので Commit suggestions ボタンを押して、この変更を説明するメッセージを入力します。
これによってすべての修正がひとつのコミットとしてブランチに追加されます。結果として、変更履歴が読みやすいものとなり、リポジトリのフォロワーに送信される通知の数も減ります。ついでに言えば、この処置によってあなたのクリック数も大きく減らすことができます。
Make corrections¶
新しいプルリクエストは自動的に プルリクエストリスト に追加されます。他の編集者や管理者があなたのプルリクエストを見直し、提案をしたり修正を求めたりするかもしれません。
A pull request will also trigger automated build checks (eg, for rst formatting,
python code syntaxes), and reports are displayed at the bottom of the page.
If an error is found, a red cross will appear next to your commit.
Click on the red cross or on Details in the summary section at the bottom
of the pull request page to see the details of the error. You'll have to fix
any reported errors or warnings before your changes are committed to the
qgis/QGIS-Documentation repository.
メインリポジトリにマージされるまでは、プルリクエストに修正を加えることができます。それはプルリクエストを改善するためだったり、提案された修正に対処するためだったり、あるいはビルドエラーを修正するためだったりするでしょう。
変更するにはプルリクエストのページで をクリックして、変更したいファイル名の横にある鉛筆ボタン 
をクリックします。
プルリクエストで使用したのと同じブランチで変更を加えた場合、追加された変更はすべてプルリクエストに自動的に追加されます。このため、追加の変更は、プルリクエストで修正しようとしている問題にその変更が関連する場合にのみ、行うようにしてください。
別の問題を解決したい場合は、それらの変更に対して新しいブランチを作成して上記のステップを繰り返します。
ビルドエラーが修正され、あなたと管理者が変更に満足したら、管理者はあなたの貢献をマージします。
1.1.5. Delete your merged branch¶
変更がマージされた後でブランチを削除できます。古いブランチを削除すると、未使用のブランチや古いブランチをリポジトリに保存しておく必要がなくなります。
フォークしたあなたのQGIS-Documentationリポジトリ (
https://github.com/<YourName>/QGIS-Documentation) に移動します。Branches タブをクリックします。 Your branches の下にあなたのブランチがあることと思います。
不要なブランチの
Delete this branch アイコンをクリックして削除します。
1.2. Gitコマンドラインツールを使用する¶
GitHubのウェブインターフェイスは、簡単なやり方でQGIS-documentationレポジトリの更新に貢献することができますが、下記のためのツールは提供していません。
複数のコミットをまとめることによって変更履歴をきれいにする
メインリポジトリとの間で生じうる衝突を解決する
あなたの変更をテストするためにドキュメントをビルドする
より高度で強力なツールへアクセスし、リポジトリのコピーをローカル環境に持つためには、ハードドライブ上に gitをインストール する必要があります。しばしば必要となる基本的な事項は以下で説明されています。そこではウェブインターフェイスを使用する場合であっても気をつけるべきルールを学ぶことができるでしょう。
以下のコードサンプルでは、 $ で始まる行はあなたが入力すべきコマンドを示します。一方、 # で始まる行はコメントです。
1.2.1. ローカルリポジトリ¶
さあ、QGIS-Documentationリポジトリの**あなた用の**コピーをローカル環境に取得する準備はできましたね。
ウェブURLを使った以下のコマンドで、QGISドキュメンテーションリポジトリを複製し取得することができます。
# 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 <YourName>
with your github user name.
次に以下の確認を行ってください。
# 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-Documentationリポジトリの、リモートリポジトリにつけられた名前です。
master はデフォルトのメインブランチです。貢献する際にはこのブランチを使用してはいけません。 絶対に です！
SSHプロトコルを使用してQGISドキュメンテーションリポジトリを複製することもできます。
# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone git@github.com:<YourName>/QGIS-Documentation.git
ちなみに
Permission denied (publickey) エラーが出た時は？
上記のコマンドで Permission denied (publickey) というエラーが出た場合は、おそらくはあなたのSSH keyに問題があります。詳細は GitHubのヘルプ を参照してください。
SSHプロトコルを使用した場合は確認は以下のようになります。
# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin git@github.com:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master
これで始めることができますが、長い間のうちには、あなたの貢献をプッシュした際（GitHubのプロセスではプルリクエストと呼びます）に、たくさんの問題が生じると思います。これは公式のqgis/QGIS-Documentationリポジトリのmasterブランチが、あなたのローカル／リモートリポジトリからだんだんと差異を増してずれていくことによるものです。このため、常にメインリモートリポジトリの状態を追跡したうえで、ブランチにおける作業を行う必要があります。
1.2.2. もうひとつのリモートリポジトリを追加¶
メインプロジェクトで行われた作業を追跡できるようにするために、ローカルリポジトリに新しいリモートリポジトリを追加します。この新しいリモートリポジトリは、QGISプロジェクト公式のQGIS-Documentationリポジトリです。
$ 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)
ローカルリポジトリにリモートリポジトリを追加するときにも、同様にSSHプロトコルを使うことができます。
$ 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)
これで2つのリモートリポジトリの、どちらかを選ぶことができるようになりました。
origin は あなたの リモートリポジトリに、あなたのローカルブランチをプッシュするときに使用します。
upstream は、あなたの貢献を公式のリポジトリにマージしたり（その権限がある場合）、あなたのローカルリポジトリのマスターブランチを公式リポジトリのマスターブランチに従って更新したりする際に使用します。
注釈
upstream は標準の名前のようになっていますが、実際はただのラベルですので、あなたの好きなように名前をつけることができます。
1.2.3. ベースブランチを更新する¶
新しい貢献に取り組む前には、必ず、ローカルリポジトリのマスターリポジトリをアップデートしなければなりません。
# 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
これであなたのローカルリポジトリとリモートリポジトリ双方の master ブランチを、公式QGIS-Documentationリポジトリの master ブランチに一致するようアップデートしましたので、貢献の作業を始めることができます。
注釈
リリースドキュメントに貢献したい場合はブランチを移動すること
testing版ドキュメントとともに、 latest release 版ドキュメントについても問題を修正する作業が続けられていますので、このドキュメントに対して貢献することも可能です。コード中の master を最新の対応するブランチに置き換えた上で、前セクションのサンプルコードに従ってください。
1.2.4. 制作ブランチに取り組む¶
ベースブランチを最新に更新しましたので、次は自分の貢献を追加する専用のブランチを作成する必要があります。作業は必ずベースブランチ以外のブランチで行ってください！これは常にです！
# 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文字以内に収め、最後には
.を付けないでください。簡潔にしてください。コミットの説明文は長くなってもよいので、より多く詳細について語ることができます。最後は.で終了してください。Issueを参照するには、
#を頭につけたIssue番号を使用してください。チケットを修正する場合はFixをその前につけておくと、コミットによってチケットが閉じられます。
さあ変更が保存されローカルブランチにコミットされました。プルリクエストを作成するためには、リモートリポジトリに送信する必要があります。
$ git push origin myNewBranch
1.2.6. ローカルおよびリモートリポジトリをクリーンアップ¶
プルリクエストが公式のQGIS-Documentationにマージされたら、あなたの制作ブランチは削除してかまいません。この方法で多くの作業をこなした場合、数週間のうちに用済みのブランチがたくさんできると思います。ですので以下のようにしてあなたのリポジトリをきれいに保ちましょう。
# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch
またローカルリポジトリ中の master ブランチを更新して最新の状態を保つことも忘れないでください！
1.3. より詳しく知りたい場合は¶
上記のGithubウェブインターフェイスとgitコマンドラインツール以外にも、ドキュメントへの貢献を作成および管理するために使用できる GUIアプリケーション があります。
プルリクエストの変更が、ターゲットブランチにプッシュされた最近の変更と競合している場合は、マージが可能になるよう、先にこの競合を解決する必要があります。
競合が競合する数行に関連している場合は、Githubのプルリクエストのページに Resolve conflicts ボタンがあります。 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/ を参照してください。