重要
翻訳は あなたが参加できる コミュニティの取り組みです。このページは現在 92.43% 翻訳されています。
1. 貢献のための一歩一歩
注釈
ここでは手順の説明のためにQGISドキュメントを使用しますが、以下で説明するコマンドおよび手順はすべて、QGISウェブサイトにも当てはまります。
あなたがこの文章を読まれているということはきっと、QGISドキュメントに貢献しようという気持ちがあって、そのための方法を探されているのでしょう。 ここで提供しようとしているのは、まさしくそれです。現在この文書では、目的を達成するための複数の方法を一通り案内し、従うべき主な手順を示し、使用可能な小技と知っておくべき落とし穴を教えています。
何か助けが必要なときには迷わず、修正しようとしているIssueレポートのコメントに書き込むか、 QGISコミュニティチームメーリングリスト に投稿をしてください。 QGISコミュニティサポート に関する一般情報をお読みください。
さあ、では集中して始めてみましょう。
ドキュメントのソースはgitバージョン管理システムを使って保存され、GitHubのhttps://github.com/qgis/QGIS-Documentation で公開されています。修正すべき問題や説明すべき機能の一覧は、https://github.com/qgis/QGIS-Documentation/issues にあります。
Tip
初めて貢献される方で、何から始めたらいいかわからないという方は、welcoming issue reports に取り組むのが面白いかもしれません。
ファイルを修正するには、排他的ではない2つの方法があります:
1.1. GitHub のウェブインタフェースを使用する
GitHubのウェブインタフェースでは次のことを行うことができます。
ファイルを編集する
変更をプレビューし、コミットする
変更がメインリポジトリに挿入されるようにプルリクエストを行う
ブランチを作成、更新または削除する
もしあなたがgitやGitHubの語彙にまだ慣れていないなら、GitHubの Hello-world プロジェクトを読んで、以下で使用する基本的な語彙やアクションを学ぶとよいでしょう。
注釈
報告されたissueを修正するとき
もしあなたが issue を修正するための変更を加えている最中なら、issueレポートにコメントをして、それをあなた自身に割り当ててください。これにより、複数の人が同じissueに取り組むことを防ぐことができます。
1.1.1. QGISドキュメントをフォークする
GitHubアカウント をすでに取得していれば、まず最初にするべきは、ドキュメントのソースファイルをフォークすることです。
QGIS-Documentation のリポジトリ ページに移動して、右上隅の ボタンをクリックします。
ご自身のGitHubアカウントに、QGIS-Documentationリポジトリ (https://github.com/<YourName>/QGIS-Documentation
) が作られていることと思います。このリポジトリは公式のQGIS-Documentationリポジトリのコピーです。あなたに完全な書込権限が与えられていて、公式のドキュメントに影響を与えることなく変更を加えることができます。
1.1.2. 変更を加える
QGISドキュメントに貢献するにはいくつかの異なった方法があります。以下ではそれらを別々に示しますが、あるプロセスから別のプロセスに切り替えることに何ら問題はありません。
選択肢 1: Edit on GitHub
ショートカットを使用する
QGISドキュメントウェブサイト上のページは、次にある Edit on GitHub
リンクをクリックするだけで、迅速かつ簡単に編集できます:
各ページの最上部右
左サイドバーの最下部にあるドロップダウンメニュー。
Edit on GitHub
をクリックすると、qgis:master
ブランチのファイルが開きます。ページの上部には、あなたにはこのリポジトリへの書込権限がないため、変更はあなたのリポジトリの新しいブランチで適用される旨を知らせるメッセージが、表示されます。変更を行います。ドキュメントはreStructureTextシンタックスを使用して書かれていますので、変更の内容によっては、 執筆のためのガイドライン を参照しながら行う必要があるかもしれません。
ファイルの編集が完了したら、変更をコミット... をクリックし、変更内容を説明する短いタイトルを入力してください。必要に応じて、より詳細な説明を追加することもできます。
変更を提案 をクリックし、変更内容をあなたのリポジトリに保存します。これにより、リポジトリに専用の ブランチ (
patch-xxx
) が作成され、ウェブブラウザが 変更の比較 ページを開きます。対処しているissueに追加の変更が不要な場合は、以下の 変更をプルリクエストで共有する セクションに進んでください。
QGISに送信する前に追加の変更が必要な場合は、次の手順に従ってください。
フォークしたあなたのQGIS-Documentation (
https://github.com/<YourName>/QGIS-Documentation
) リポジトリに移動します。下の ファイルの編集 セクションまで移動してください。
選択肢 2:あなたのドキュメンテーションリポジトリに一時的な専用ブランチを作成する
あなたがフォークしたQGIS-Documentationで直接ファイルを編集できます。
まず、master
ブランチがupstream、つまり qgis/QGIS-Documentation:master
ブランチと同期していることを確認してください。その手順は次のとおりです:
リポジトリのメインページ、つまり
https://github.com/<YourName>/QGIS-Documentation
にアクセスしてください。master
ブランチがアクティブで、qgis/QGIS-Documentation:master
が最新かどうかが表示されているはずです。そのブランチがupstreamブランチより先にコミットしている場合は、
master
ブランチを揃えるまで、以前の shortcut button alternative を使った方がよいでしょう。後ろにコミットがあるだけなら:
右側の Sync fork ドロップダウンメニューを展開します。以下の操作が可能です:
ブランチを 比較 し、upstreamブランチに存在するが、自分のものにはまだ存在しない新しい変更を確認する
フェッチとマージ: upstreamブランチの変更を自分のものに取り込みます。
Click Fetch and merge: after the process, your branch is mentioned as up to date with
qgis/QGIS-Documentation:master
.
フォークしたQGIS-Documentationリポジトリの左上角にある
をクリックし、テキストフィールドに一意の名前を入力して、新しい ブランチ を作成します。新しいブランチの名前は、修正しようとする問題に関連した名前を付けることをおすすめします。後でブランチを識別する際に便利です。
マスターからブランチ <branch_name> を作成 を押します。
ボタンには branch_name が表示されるはずです。
新しいブランチ上で新しい変更を開始する準備が整いました。
注意
変更はこの一時的な専用ブランチで行うこと。絶対に master
ブランチでは行わないこと
qgis/QGIS-Documentation
の master
ブランチからあなたのQGIS-Documentationリポジトリに変更をマージする場合を除いて、 慣例として master
ブランチでは変更を行わないでください。問題ごとに別々のブランチを使用することによって、他のブランチに干渉することなく、同時に複数の問題に取り組むことができます。間違えた場合は、いつでもブランチを削除して、masterブランチから新しいブランチを作成してやり直すことができます。
1.1.3. ファイルを変更する
変更したいブランチがアクティブであることを確認してください:その名前は左上のメニューまたはページURLに表示されています。
ソースファイルを閲覧し、変更が必要なファイルを選択してください。
Update the text following the writing guidelines
ファイルの編集が完了したら、変更をコミット... をクリックし、変更内容を説明する短いタイトルを入力してください。必要に応じて、より詳細な説明を追加することもできます。
Make sure Commit directly to the <branch_name> branch is selected.
Press Commit changes to save your modifications in the branch.
To update or add a new image file:
Browse your branch to the folder of the file to update or add.
Top right, use the スクリーンショットを管理する.
menu to select and load files from your drive. You can find hints for formatting an image for the docs atIf a file of the same name already exists, it gets overwritten.
Commit once again your changes to the target branch.
Repeat the previous steps for any other files that need to be updated to fix the issue.
1.1.5. マージしたブランチを削除する
変更がマージされた後でブランチを削除できます。古いブランチを削除すると、未使用のブランチや古いブランチをリポジトリに保存しておく必要がなくなります。
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
前者のコマンドラインは単なる例です。パスもリポジトリのURLも適応させ、<YourName>
を自分のgithubユーザー名に置き換える必要があります。
次に以下の確認を行ってください。
# 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 [email protected]:<YourName>/QGIS-Documentation.git
Tip
Permission denied (publickey) エラーが出た時は?
前者のコマンドで Permission denied (publickey) エラーが出る場合は、SSH 鍵に問題がある可能性があります。詳しくは GitHub help を参照してください。
SSHプロトコルを使用した場合は確認は以下のようになります。
# 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
これで始めることができますが、長い間のうちには、あなたの貢献をプッシュした際(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 [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 は標準の名前のようになっていますが、実際はただのラベルですので、あなたの好きなように名前をつけることができます。
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 ボタンが利用できます。ボタンを押し、Resolving a merge conflict on GitHub の説明に従って問題を解決してください。
ファイルのリネームや削除がコンフリクトに関係している場合は、git コマンドラインを使ってコンフリクトを解決する必要があります。一般的には、まず
git rebase targetBranch
を使ってターゲットブランチの上に自分のブランチをリベースし、報告された競合を修正しなければなりません。詳しくは コマンドラインを使ったマージの競合の解決 をご覧ください。
校正作業の最後に、複数のコミットに分割された、必ずしも価値のない変更になってしまうことがあります。Git のコマンドラインは、このようなコミットをより少ない数にまとめ、より意味のあるコミットメッセージにするのに役立ちます。詳しくは コマンドラインで git rebase を使う を参照ください