3. 開発プロセス

オープンソースプロジェクトではよくあることですが、プロジェクトへのコードやドキュメントの貢献は高く評価されます。QGISコミュニティは非常に協力的です。このセクションでは、QGISプロジェクトであなたの貢献を開発し、マージする手順について説明します。

3.1. git型のプロジェクト

QGISのソースコードの複雑さは、ここ数年でかなり増しています。そのため、機能の追加がもたらす副作用を予測することは困難です。過去、QGISプロジェクトはリリースサイクルが非常に長く、新機能の追加後にソフトウェアシステムの安定性を再構築するのに多くの労力を要しました。これらの問題を克服するために、QGISは git バージョン管理システムを使った開発モデルに切り替えました:新しい機能はまずコントリビューターブランチでコーディングされ、完成して安定した時点でQGISマスタ(メインブランチ)にマージされます。

QGISのソースコードは、https://github.com/qgis/QGIS にホストされています。

3.1.1. ロール

GitHub にはさまざまなロールがあります。GitHub にアカウントを持つと、リポジトリをフォークして貢献することができるようになり、「コントリビュータ」というロールが与えられます。コア開発者は「コラボレータ」であり、ブランチをアップストリームや公式リポジトリにマージすることができます。

3.1.2. 環境

QGISリポジトリの使用と貢献を始めるには、次のことが必要です:

  1. GitHubアカウント を持っている

  2. QGIS リポジトリ <https://github.com/qgis/QGIS>`_ の自分用のコピーを作る (フォーク を参照)

  3. 自分のシステムに gitクライアントをインストール している

  4. git環境 をセットアップする

  5. そして楽しむ!

3.1.3. gitをインストールする

gitプロジェクトは、ほとんどのプラットフォーム用にソフトウェアの最新バージョンを提供しています。https://git-scm.com/downloads の指示に従って、あなたのOSとアーキテクチャに対応するコピーを入手し、インストールしてください。リポジトリをブラウズして管理するためのgit GUIクライアントをインストールすることもできます(ほとんどの場合、利用できなければgitがインストールされます)。

3.2. ブランチでの開発

3.2.1. 開発への貢献

GitHubにサインアップしてリポジトリをフォークすれば、コントリビューターとして参加できます。

注釈

QGISコードへの貢献は、GitHubウェブサイト上のフォークしたリポジトリから行うことができます。新しいコードはテスト環境によって自動的にビルドされます。しかし、複雑な変更を加えたい場合、このワークフローではすぐに限界が見えてしまいます。以下の説明では、ローカルクローンを想定しています。

プルリクエストを開始することで貢献できます。そのためには、以下の一般的な手順に従ってください:

  1. ローカルコンピューターに リポジトリをクローン し、ビルド環境をセットアップします

  2. 新しいブランチを作成し、開発用の編集を行います

  3. 変更をコミットし、ブランチをGitHubのリモートフォークにプッシュバックします。プルリクエストは、その直後にウェブリンク(URL)として提供されます。

  4. プルリクエスト(PR) を開き、あなたのブランチからマスターブランチへのコミットをアップストリームリポジトリにプルするよう依頼します。

  5. あなたのプルリクエストについて他のコントリビュータやコラボレータに知らせるレビュープロセスが開始されます。あなたは彼らのコメントや提案に反応するべきです。

注釈

Githubのフォーク&プルワークフローの詳細は、https://reflectoring.io/github-fork-and-pull/ にあります。

注釈

ほとんどのQGISプロジェクト(ウェブサイト、ドキュメント、pyQGIS API、プラグイン...)は、 `プロジェクトのGitHubページ<https://github.com/qgis>`_ で公開されており、同じプロセスでコントリビューションを得ることができます。

3.2.2. リポジトリにアクセスする

ローカルディスクからリモートフォークとQGISアップストリームリポジトリの両方とやり取りするには、次のことが必要です:

  1. ローカルディスクにコピーのクローンを作る

    cd path/to/store/the/repository
    git clone https://github.com/<yourName>/QGIS.git
    
  2. QGISのメインリポジトリを自分のものに繋げる(ここではそれを upstream と呼びます)

    git remote add upstream https://github.com/qgis/QGIS.git
    
  3. リモートリポジトリの接続を確認する

    git remote -v
    # origin   https://github.com/<YourName>/QGIS.git (fetch)
    # origin   https://github.com/<YourName>/QGIS.git (push)
    # upstream https://github.com/qgis/QGIS.git (fetch)
    # upstream https://github.com/qgis/QGIS.git (push)
    

    これでオンラインリポジトリにローカルドライブからアクセスできるようになり、 origin という名前を使って操作できるようになりました。qgis/QGIS リポジトリから変更を取得したい場合は、いつでも upstream を使います。

注釈

QGIS では、最も安定したコードを現在のリリースブランチに保持しています。master ブランチには、いわゆる「不安定な」リリースシリーズのコードが含まれています。定期的に master ブランチからリリースを分岐し、安定化と新機能の選択的な取り込みを master ブランチで行います。

開発版のビルド方法については、ソースツリーの INSTALL ファイルを参照してください。

3.2.3. 手順

  1. メーリングリストまたはイシューリポでの最初のアナウンス:

    作業を始める前に、開発者メーリングリストにアナウンスして、 他の開発者がすでに同じ機能に取り組んでいないかどうか確認してください。また、イシューレポートがリポに存在する場合は、コメントとしてあなたの関心に言及することもできます。新機能が QGIS アーキテクチャへの変更を必要とする場合、QGIS Enhancement Proposal (QEP) が必要です。

  2. ローカルリポジトリにブランチを作る:

    masterブランチの最新の状態に基づいて、新機能の開発用に新しいgitブランチを作成する。

    git fetch upstream master
    git checkout -b newfeature upstream/master
    
  3. 開発を始める:

    あなたのローカル・ディスクで、いつものIDEを使って変更をコーディングしてください。適切なときは、あなたの変更に対してテストスイートを書くことを忘れないでください。

  4. 変更を git リポジトリにコミットする:

    コミットを行う際には、説明的なコメントをつけ、複数のファイルの変更が関連しないものの場合は、複数の小さなコミットを行うようにしてください。逆に、関連する変更は1つのコミットにまとめることを推奨します。

    git add path/to/your/files
    git commit -m "Add a comment describing your nice feature"
    
  5. ここで、QGISコミュニティのメンバーとあなたの作業を共有したいと思うかもしれません。次の方法で新しい機能をオンラインフォークリポジトリにプッシュしてください:

    git push origin newfeature
    

    注釈

    ブランチがすでに存在する場合は、あなたの変更がそれにプッシュされ、そうでない場合はブランチが作成されます。

  6. プルリクエストで 変更を提出します

    プルリクエストを開くと、自動テストスイートが起動し、あなたの変更が QGIS のコーディングガイドラインに沿っているか、既存の機能を壊していないかをチェックします。ブランチがupstreamにマージされる前に、報告されたイシューを修正する必要があります。

    Tip

    GitHubアクション を使用して、リポジトリ上で実行するテストを管理します。便利なように、プッシュしたときにテストが実行されるように、リポジトリ上でアクションを有効にすることができます。そして、すべてのテストが合格した後にプルリクエストをオープンすることで、レビュー作業をより効率的に行うことができます。

  7. 定期的にupstream masterにリベースする:

    masterでの変更をブランチに取り込むために、定期的にリベースすることをお勧めします。こうすることで、後でブランチを master にマージするのが簡単になります。リベースの後は、フォークしたレポジトリに git push -f する必要があります。

    git pull --rebase upstream master
    git push -f origin newfeature
    

注釈

GITのマスターになることについては、以下のサイトを参照してください。

3.2.4. マスターに戻してマージする前にテストする

新しい機能性と安定性に満足して終了したら、開発者リストで発表を行います。戻してマージする前に、変更は開発者とユーザーによってテストされるでしょう。

3.3. プルリクエストを送る

あなたがパッチやプルリクエストをQGISに簡単に取り込み、私たちが送られてきたパッチを簡単に処理するのに役立つガイドラインがいくつかあります。

一般的に、GitHub にプルリクエストを送ったほうが開発者にとって簡単です。ここではプルリクエストについては説明しませんので、GitHub プルリクエストドキュメント を参照してください。

プルリクエストを行う場合、あなたのPRブランチにmasterを定期的にマージし、あなたのPRが常にupstreamのmasterブランチにマージできるようにしてください。

もしあなたが開発者で、プルリクエストキューを評価したいのであれば、コマンドラインからこれを実行できる、とても素晴らしいツール > があります。

一般的に、PRを提出したら、それを最後までやり遂げる責任を負うべきですー他の開発者から投稿された問い合わせに対応し、あなたの機能の「チャンピオン」を探し、あなたのPRが実行されていないことがわかったら、時折彼らに優しく注意を促してください。QGISプロジェクトはボランティアの努力によって運営されており、あなたのPRに即座に対応できない場合があることを念頭に置いてください。入ってくるプルリクエストをスキャンしていますが、時には見逃してしまうこともあります。気を悪くしたり、心配したりしないでください。あなたを助けてくれる開発者を見つけ、あなたのパッチを見てもらえるかどうか連絡してみてください。もしあなたが、その PR が相応の注意を払われていないと感じるのであれば、それを加速するための選択肢を (優先順位の高い順に) 挙げてください:

  • 他のプルリクエストのレビューを手伝い、自分の担当者を解放します。

  • あなたのPRおよびそれがコードベースに含まれるとどれほど素晴らしいかを「売り込む」メッセージをメーリングリストに送信します。

  • PRキュー内であなたのPRが割り当てられている人にメッセージを送信します。

  • プロジェクトの運営委員会にメッセージを送信し、あなたのPRがコードベースに組み込まれるのを見るのを助けるよう求めます。

3.3.1. プルリクエストを作成するためのベストプラクティス

  • 常に現在のマスターから機能ブランチを開始します。

  • 機能ブランチをコーディングしている場合は、そのブランチに何かを「マージ」しないでください。むしろ、あなたの履歴をきれいなままに保持するために、次のポイントで説明されるように、リベースしてください。

  • プルリクエストを作成する前に git fetch upstreamgit rebase upstream/master を実行します (upstreamが qgis ユーザーのリモートであり、自分のリモートではない場合は .git/config を確認するか、git remote -v | grep github.com/qgis を実行します)。

  • 何らかのダメージを与えることなく繰り返し、最後の行のようにgitリベースを行うことができます(あなたのブランチの唯一の目的がマスターにマージされることである限り、)。

  • 注意:リベースした後、あなたのフォークレポに git push -f する必要があります。 CORE DEVS:QGIS公開リポジトリ上でこれ​​をしないでください!

3.3.2. ドキュメント作成者に通知する特別なラベル

レビュアーがあなたのプルリクエストに特別なラベル (Needs Documentation) を付けることで、あなたのプルリクエストがマージされると同時に、QGIS-Documentation リポジトリにイシューレポートが自動的に生成されます。あなたの機能がそのようなラベルを付けるに値するかどうかを忘れずに記述してください。

さらに、コミットメッセージに特別なタグを追加することで、ドキュメント作成者に詳細な情報を提供することができます。コミットメッセージは生成されたイッシューレポートに追加されます:

  • [needs-docs] 既存の機能に修正や追加した後、いくつかの余分なドキュメントを追加してくださいとお願いするドキュメントライターを指示します。

  • 新機能の場合は [feature] 。PRに良い説明を記入することは良いスタートとなるでしょう。

開発者はこれらのラベル(大小文字を区別しない)を使用してください、ドキュメントの作成者が作業する問題を持ち、するべきことの概要を持つように。しかし、また、いくつかのテキストを追加する時間をかけてください:コミットまたはドキュメント自体のいずれかで。

3.3.3. 適当な注意

QGISはGPLの下でライセンスされています。あなたは、矛盾する知的財産権によって妨げられないパッチを提出するよう、あらゆる努力をする必要があります。また、GPLの下で利用可能になって嬉しくないコードを提出しないでください。

3.4. GIT書き込みアクセス権の取得

QGISソースツリーへの書き込みアクセス権は招待によります。人はC ++とQGISコーディング規約の基本的な能力と理解を示し、いくつかの(ここには一定の数が存在しない)かなりのパッチを提出する場合、通常、PSCのメンバーや他の既存の開発者の一人は、書き込みアクセスを許可するためのPSCにその人を指名できます。推薦は、彼らがその人が書き込みアクセス権を取得すべきだと思う理由の基本的なプロモーション段落を与える必要があります。いくつかのケースでは、我々は、翻訳者とdocumentors用など非C ++開発者への書き込みアクセスを許可します。これらのケースでは、人はまだパッチを提出する能力を実証している必要があり、理想的に物事を壊すことなく、コードベースを変更することの理解を示し、いくつかのかなりのパッチなどを提出している必要があります

注釈

GITに移動するので、QGISをforkしてプル要求を発行することによってgithubの内のコードを共有することは簡単なので、新しい開発者に書き込みアクセスを許可する可能性は低いです。

常にすべてがコミット/プル要求を作成する前にコンパイルされることを確認してください。あなたのコミットは、人々が他のプラットフォーム上で構築するためのライブラリとの古い/新しいバージョンの原因となる可能性のある破損を認識するようにしてください。