貢献ガイドライン

概要

オープンソースプロジェクトであるため、次のガイドラインに従えば誰でも貢献できます :

  • コードを提供する前に、作者はすべてのテストが確実に行われるようにする必要があります。下記のテストの実行方法を参照してください
  • 開発されたコードは、linters によって強制される構文ガイドラインに従わなければなりません
  • コードは、以下に定義する分岐モデルと変更ログのポリシーに従って開発する必要があります
  • 新しい機能が追加された場合は、すでに作成されプロジェクトに含まれているものを参考にして単体テストを提供する必要があります

あなたの最初の貢献を通してさらにあなたを導くために、これらのバグに割り当てられた mentored というラベルを作成しました。このバグは、プロジェクトに初めて参加した人が解決できるほど単純で興味深いものです。お気軽に自分自身に割り当ててください。また、問題(issue)のコメントに主な開発者への言及を躊躇しないでください。 彼らはあなたを喜んで助けます。これは、@gtorodelvalle または @frbattid です。

貢献する方法

貢献を開始するには :

  1. このリポジトリをフォークするには、ページの右上にある "Fork" ボタンをクリックします。
  2. 先ほどフォークしたリポジトリをクローン :
    git clone https://github.com/your-github-username/fiware-sth-comet.git
  3. 主な fiware-sth-comet リポジトリを、fork したリポジトリにリモートとして追加します。メインの fiware-sth-comet リポジトリをリモートのリポジトリに追加します。リモートリポジトリにはどんな名前でも使うことができます。それは fi-sth-comet である必要はありませんが、次の手順で使用します:
    git remote add fiware-sth-comet https://github.com/telefonicaid/fiware-sth-comet.git

貢献を開始する前に、フォークされたリポジトリ内の master ブランチを、メインの fiware-sth-comet リポジトリ内の master ブランチと、次の手順に従って同期させてください :

  1. あなたのローカル master ブランチに変更します :
    git checkout master
  2. リモートの変更を取得します :
    git fetch fiware-sth-comet
  3. それらをマージします :
    git rebase fiware-sth-comet/master

これらのガイドラインに従った貢献は、master ブランチに追加され、次のバージョンでリリースされます。リリースプロセスについては、以下のリリース・セクションで説明します。

コーディング・ガイドライン

コーディング・ガイドラインは、提供された .jshintrc と .gjslintrc フラグファイルによって定義されます。後者は Python を必要とし、grunt-init を使用してプロジェクトスケルトンを作成する際にその使用を無効にすることができます。

ソースコード・スタイルを確認するには、次のように入力します : 

grunt lint

Checkstyle レポートは Jenkins と一緒に使用して、Checkstyle プラグインと Violations プラグインを使用してプロジェクト品質メトリックを監視することができます。report/lint/ で Checkstyle とJSLint のレポートを生成するには、次のように入力します : 

grunt lint-report

ブランチ・モデル

リポジトリには1つの特別なブランチがあります :

  • master : これは最後の安定した開発コードを含んでいます。新しい機能とバグ修正は、新しいリリースが作成され公開されるまで常に master にマージされます

以前のブランチとは別に、各リリースコードの最新バージョンが見つかる release/X.Y.Z と呼ばれる別のブランチセットがあります。この点に関して、X.Y.Z と呼ばれるリリースは、プロジェクトの新しいバージョンがリリースされるたびに作成され、対応する release/X.Y.Z リリースブランチの最新の状態を示します。

新しい機能やリファクタリングの開発を開始するには、次の命名規則に従って、ローカル分岐リポジトリに新しいブランチを作成する必要があります :

  • bug/<description>
  • feature/<description>
  • hardening/<description>
  • task/<description>

ワークの種類によって異なります。

最終的なコードがローカルのフォークされたリポジトリブランチで利用可能になると、最終的なランディングの前にレビュープロセスが開始されるときに、fiware-sth-comet リモートリポジトリの master ブランチにプルリクエストを送信する必要があります。プルリクエストを作成する前に、linters と tests の両方をチェックすることを忘れないでください。

チェンジログ

プロジェクトには、プロジェクトのルートにある、CHANGES_NEXT_RELEASEと呼ばれるバージョン変更ログファイルが含まれています。新しい機能やバグフィックスが master にマージされるたびに、このチェンジログファイルに新しいエントリを追加する必要があります。新しいエントリには、解決している問題の参照番号(存在する場合)が含まれているはずです。

新しいバージョンがリリースされると、チェンジログはクリアされ、そのバージョンの最後のコミット時に修正されたままになります。チェンジログの内容は、Github リリースのリリースの説明にも移動します。

これに関する詳細は、以下のリリース・セクションを参照してください。

テスト

テスト環境は、テストの実行中にグローバルに利用可能な chai.expect と `chai.should()'、および Sinon-Chai プラグインの BDD テストスタイルに従い、Chai assertion libraryと Sinon spies, stubs 等をサポートする Mocha Test Runner を実行するように事前設定されています。

テスト中のモジュールモッキングは、proxyquireで行うことができます。

テストを実行するには次のように入力します : 

grunt test

テストレポートは、Jenkins と一緒に使用して、TAP または XUnit プラグインを使用してプロジェクト品質メトリックを監視することができます。report/test/unit_tests.tap に TAP レポートを生成するには、次のように入力します : 

grunt test-report

継続的なテスト

ソースファイルまたはテストが変更されたときにテストが実行されるように、継続的なテストのサポートが提供されています。

連続テストの場合は、次のように入力します : 

grunt watch

コードカバレッジ

非常に良い習慣は、テストのコードカバレッジを測定することです。

site/coverage/ パスの下に HTML カバレッジレポートを生成し、サマリを出力するには、次のように入力します : 

# Use git-bash on Windows
grunt coverage

Cobertura プラグインを使用して Jenkins と一緒にプロジェクト品質メトリクスを監視するために使用できる report/coverage/cobertura-coverage.xmlに、Cobertura レポートを生成するには、次のように入力します : 

# Use git-bash on Windows
grunt coverage-report

コードの複雑さ

別の非常に良い習慣は、コードの複雑さを分析することです。

Plato の使用をサポートし、生成されたレポートを site/report/ パスに保存します。この機能は、DocLinks プラグインを使用して Jenkins と一緒に使用できます。

コード複雑さレポートを生成するには、次のように入力します : 

grunt complexity

ソースコードのドキュメント

site/doc/ パスの下に HTML コードのドキュメントを生成することができます。DocLinks プラグインを使用して Jenkins と一緒に使用することができます。

ソースコードのドキュメントをコンパイルするには、次のように入力します : 

grunt doc

リリースする

リリースを行うプロセスは、以下の手順で構成され、メインリポジトリの所有者または管理者のいずれかが作成する必要があります :

  1. 上記の貢献方法のセクションに示されているように、ローカルのフォークされたリポジトリ内の master ブランチを、リモートの fiware-sth-comet リポジトリの masterブランチの最新バージョンに同期させます
  2. ローカルのフォーク・リポジトリの更新された master ブランチから、新しいタスクブランチを作成して、package.json ファイル(現在、-next サフィックスを含める必要があります)内の開発バージョン番号をリリース(X.Y.Z、たとえば、プレフィックスなし)する新しいバージョンに変更します
  3. このタスクブランチから fiware-sth-comet リモートリポジトリの `master' ブランチにプルリクエストを作成し、追加のプロジェクト管理者のいずれかにそれを見直してランドさせるよう依頼してください
  4. fiware-sth-comet メインリポジトリで、対応するバージョン番号を使用して master ブランチの最新バージョンから、release/X.Y.Z と名前が付けられたリリースブランチを作成します
  5. fiware-sth-comet メインリポジトリで、新しいリリースブランチ release/X.Y.Z からタグバージョンをX.Y.Z に設定する新しいリリースを作成し、それを公開します
  6. 上記の貢献方法のセクションに示されているように、ローカルのフォークされたリポジトリ内の master ブランチを、リモートの fiware-sth-comet リポジトリの master ブランチの最新バージョンに同期させます 7.ローカルのフォーク・リポジトリの更新された master ブランチから、新しいタスクブランチを作成し、package.json ファイル内の現在のバージョン番号に -next サフィックスを追加して(これを開発バージョンとして通知します)、チェンジログ・ファイル CHANGES_NEXT_RELEASE の内容を削除します。
  7. この新しいタスクブランチからリモートの fiware-sth-comet リポジトリの masterブランチにプルリクエストを作成します。

バージョン/リリース番号

バージョン番号は、次の規則に従って各リリースごとに変更されます :

  • すべてのバージョン番号は常に共通のパターンに従います : X.Y.Z
  • X は、リリースの互換性を変更する変更があった場合、またはコンポーネントの機能セットに非常に重 な変更がある場合にのみ変更されます。X が変化した場合、Y は0に設定する必要があります。
  • Y は、新しいバージョンがリリースされるたびに変更されます。Y だけが変更された場合、いくつかの新機能やバグ修正がリリースされたことを意味しますが、コンポーネントは現在のメジャー(X)リリースの改良版です。
  • Z はメジャー(X)とマイナー(Y)リリースごとに新しいバグ修正が検出され、修正されると、その値を増やします。

リリース間では、master ブランチのバージョン番号が X.Y.Z-next (X.Y.Z は最新の安定版リリース)であり、開発バージョンであることを示します。