ガイドライン

プルリクエストのガイドライン

強く推奨したい理念は、

PRを作成する前に、issueを作成してください。

目的は、問題を可能な解決策から分離することです。

バグ修正: 小さなバグを修正するだけの場合は、すぐにプルリクエストを送信しても問題ありませんが、修正内容を詳しく説明した issue を登録することを強くお勧めします。これは、特定の修正を受け入れないが、問題を追跡したい場合に役立ちます。プロジェクトメンテナーは、受信したPRを受け入れるか拒否する権利を留保していることに留意してください。そのため、問題とそれを修正するためのコードを互いに分離することをお勧めします。場合によっては、プロジェクトメンテナーが、続行する前にPRから別のissueを作成するように要求することがあります。

リファクタリング: 小規模なリファクタリングについては、何をリファクタリングしているのか、なぜリファクタリングするのかを詳しく説明したスタンドアロンのPR自体で構いません。懸念事項がある場合は、プロジェクトメンテナーが、続行する前にPRに対して#SIPを作成するように要求することがあります。

機能/大規模な変更: パブリックAPIを変更したり、実装に重要な変更を加える場合は、#SIP（Superset改善提案）として新しい issue を登録する必要があります。これにより、あなたが多大な労力を費やす前に、あなたの提案について合意に達することができます。SIPと一緒にPRを送信することもできます（デモンストレーションに必要な場合もあります）が、SIPが承認されるまでコードをレビュー/マージすることはありません。

一般に、小さなPRは大きなPRよりもレビューが容易です。ベストプラクティスは、作業をより小さく独立したPRに分割し、同じ issue を参照することです。これにより、ターンアラウンド時間が大幅に短縮されます。

まだマージする準備ができていない作業を共有したい場合は、ドラフトPRを作成してください。これにより、メンテナーとCIランナーは、成熟したPRを優先的に処理できるようになります。

最後に、masterブランチを壊れた状態にするようなPRを送信しないでください。PRが大きな機能を完成させるための複数のPRの一部であり、単独では機能しない場合は、フィーチャーブランチを作成し、関連するすべてのPRをフィーチャーブランチにマージしてから、フィーチャーブランチからmasterへのPRを作成できます。

プロトコル

作成

PRテンプレートのすべてのセクションに記入してください。
次のセマンティックプレフィックスのいずれかを使用してPRのタイトルを付けます（Karmaに触発されました）。
- feat（新機能）
- fix（バグ修正）
- docs（ドキュメントの変更）
- style（フォーマット、セミコロンの欠落など。アプリケーションロジックの変更なし）
- refactor（コードのリファクタリング）
- test（欠落しているテストの追加、テストのリファクタリング。アプリケーションロジックの変更なし）
- chore（タスクの更新など。アプリケーションロジックの変更なし）
- perf（パフォーマンス関連の変更）
- build（ビルドツール、Docker構成の変更）
- ci（テストランナー、GitHub Actionsワークフローの変更）
- other（上記に該当しない変更-まれであるはずです！）
- 例
  - feat: チャートを ZIP ファイルとしてエクスポート
  - perf(api): API 情報のパフォーマンスを改善
  - fix(chart-api): キャッシュインジケーターが常に値がキャッシュされていることを示す
レビューの準備ができていない場合は、タイトルにプレフィックス[WIP]を追加します（WIP = 進行中の作業）。最初に[WIP]付きでPRを作成し、CIテストに合格し、少なくとも1回コードの変更を読み終えたら削除することをお勧めします。
PRが潜在的な破壊的な変更をもたらすと考える場合は、PRタイトルのセマンティックプレフィックスの後ろ、コロンの前に!を付けます。例：feat!: barにfoo機能を追加しました
スクリーンショット/GIF: ユーザーインターフェースの変更には、変更前/変更後のスクリーンショット、またはインタラクションを示すGIFが必要です
- 推奨されるキャプチャツール (Kap, LICEcap, Skitch)
- スクリーンショットが提供されていない場合、コミッターはPRにneed:screenshotラベルを付け、スクリーンショットが提供されるまでレビューしません。
依存関係: 新しい依存関係を追加する際には注意し、不必要な依存関係は避けてください。
- Python の場合は、pyproject.toml に特定の制限を記述し、アプリケーションビルドが決定論的であることを保証するために、requirements.txt に特定のバージョンで固定して含めます。
- TypeScript/JavaScript の場合は、package.json に新しいライブラリを含めます。
テスト: プルリクエストには、 doctest、ユニットテスト、またはその両方としてテストを含める必要があります。すべてのエラーとテストの失敗を解決してください。テストの実行方法については、テストを参照してください。
ドキュメント: プルリクエストが機能を追加する場合は、同じPRの一部としてドキュメントを更新する必要があります。
CI: レビュー担当者は、すべてのCIテストに合格するまでコードをレビューしません。場合によっては、不安定なテストが発生する可能性があります。PRを閉じて開き、CIテストを再実行できます。問題が解決しない場合は報告してください。CIの修正がmasterにデプロイされたら、PRをリベースしてください。
コードカバレッジ: コードカバレッジが低下しないようにしてください。
レビューの準備ができたら[WIP]を削除します。承認後すぐにマージされる可能性があるため、PRがマージする準備ができていることを確認し、承認後の編集に時間をかけないようにしてください。
PRがレビューの準備ができておらず、> 30日間非アクティブだった場合、非アクティブのためクローズされます。作成者は、再オープンして更新することができます。

レビュー

レビューを書くときは、建設的なトーンを使用してください。
変更が必要な場合は、PRが承認される前に何を行う必要があるかを明確に述べてください。
プルリクエストをいくつかの変更で更新するように求められた場合は、新しいプルリクエストを作成する必要はありません。変更を同じブランチにプッシュしてください。
コミッターは、PRを拒否する権利を留保しており、場合によっては作成者にissueを登録するように要求する場合があります。

テスト環境

Apache GitHub組織のメンバーは、/testenv upコマンド（のみ）を含むコメントを作成することにより、プルリクエストで直接一時的なテスト環境を起動できます。
- この検証を正しく機能させるには、組織メンバーシップが公開されている必要があることに注意してください。
コマンドの後にフラグ名（FEATURE_をプレフィックスとする）と値を指定することにより、テスト環境のフィーチャーフラグを設定できます。
- 形式: /testenv up FEATURE_<フィーチャーフラグ名>=true|false
- 例: /testenv up FEATURE_DASHBOARD_NATIVE_FILTERS=true
- 複数のフィーチャーフラグは、空白で区切って1つのコマンドで設定できます
一時的な環境のアドレスとログイン情報が、ワークフロースクリプトによって作成されたコメントに表示されます。
テスト環境は、PRのDockerビルドCIワークフローが正常に完了すると作成できます。
テスト環境は現在、新しいコミットがプルリクエストに追加されたときに自動的に更新されません。
テスト環境は現在、非同期ワーカーをサポートしていませんが、これは計画されています。
テスト環境の実行は、プルリクエストを閉じるとシャットダウンされます。

マージ

PRをマージするには、少なくとも1つの承認が必要です。
PRは通常、マージする前に少なくとも24時間オープンにしたままにします。
PRがマージされたら、対応するissueをクローズしてください。

マージ後の責任

プロジェクトメンテナーは、PRによって新しい問題が発生した場合、PRの作成者に連絡する場合があります。
プロジェクトメンテナーは、マスターブランチCIを壊すなどの重大な問題が見つかった場合、変更を元に戻す場合があります。

issueとPRの管理

受信するissueとPRを処理するために、コミッターはissue/PRを読み、ラベルでフラグを立てて分類し、コントリビューターがどこでアクションを起こすべきかを特定できるようにします。コントリビューターは通常、異なる専門知識を持っているためです。

トリアージの目標

issueの場合: 分類、issueのスクリーニング、作成者からの必須アクションへのフラグを設定します。
PRの場合: 分類、作成者からの必須アクションへのフラグを設定します。PRがレビューの準備ができている場合は、レビュー担当者からの必須アクションにフラグを設定します。

まず、カテゴリラベル（別名ハッシュラベル）を追加します。すべてのissue/PRには、1つのハッシュラベルが必要です（スパムエントリを除く）。#で始まるラベルは、issue/PRタイプを定義します

ラベル	issueの場合	PRの場合
`#bug`	バグレポート	バグ修正
`#code-quality`	コード、アーキテクチャ、または生産性の問題を説明します	リファクタリング、テスト、ツール
`#feature`	新しい機能のリクエスト	新しい機能の実装
`#refine`	パディングの調整やUIスタイルの改良など、新機能、バグ修正、リファクタリングを除く改善を提案します。	パディングの調整やUIスタイルの改良など、新機能、バグ修正、リファクタリングを除く改善の実装。
`#doc`	ドキュメント	ドキュメント
`#question`	トラブルシューティング：インストール、ローカルでの実行、何かを行う方法を尋ねます。後で`#bug`に変更できます。	N/A
`#SIP`	Superset改善提案	N/A
`#ASF`	Apache Software Foundationのポリシーに関連するタスク	Apache Software Foundationのポリシーに関連するタスク

次に、必要に応じて他の種類のラベルを追加します。

説明的なラベル（別名ドットラベル）: .で始まるこれらのラベルは、.ui、.js、.install、.backendなど、issue/PRの詳細を説明します。各issue/PRには、ゼロまたは複数のドットラベルを設定できます。
必須ラベル: これらのラベルにはneed:xxxのパターンがあり、need:rebase、need:update、need:screenshotなど、進捗に必要な作業を説明します。
リスクラベル: これらのラベルはrisk:xxxというパターンを持ち、risk:db-migrationのように、その作業を採用する際の潜在的なリスクを記述します。その意図は、影響をより良く理解し、より厳格なテストが必要なPRに対する意識を高めることです。
ステータスラベル: これらのラベルは、ステータス（abandoned、wontfix、cant-reproduceなど）を表します。完了せずに却下またはクローズされたIssue/PRには、1つ以上のステータスラベルが付いている必要があります。
バージョンラベル: これらはv0.28のようなvx.xというパターンを持ちます。Issueのバージョンラベルは、バグが報告されたバージョンを表します。PRのバージョンラベルは、そのPRが含まれる最初のリリースを表します。

コミッターは、作成者が提供したタイトルが十分に説明的でない場合、Issue/PRの内容を反映するようにタイトルを更新することもできます。

PRがCIテストに合格し、need:ラベルが何も付いていない場合、レビューの準備ができています。reviewやdesign-reviewラベルを追加してください。

Issue/PRが30日以上非アクティブな場合、クローズされます。ステータスラベルが何も付いていない場合は、inactiveを追加します。

PRを作成する際、特定のリリースに含めることを目指す場合は、バージョンラベルでタグ付けしてください。たとえば、Superset 1.1への包含を検討する場合、v1.1ラベルを使用します。

Revertガイドライン

masterブランチで問題を引き起こしている変更を元に戻すことは、開発プロセスにおいて正常かつ想定される部分です。オープンソースコミュニティでは、変更の影響を常に完全に理解できるわけではありません。それを念頭に置いて、元に戻すことを検討する際に留意すべきいくつかの考慮事項を以下に示します。

PR作成者の可用性: 元のPR作成者またはコードをマージしたエンジニアが非常に可用性が高く、妥当な時間枠で修正を提供できる場合、これは元に戻すことを妨げるでしょう。
問題の深刻度: masterでの問題はどの程度深刻ですか？プロジェクトの進捗を妨げていますか？ユーザーへの影響はありますか？何パーセントのユーザーが問題に遭遇しますか？
元に戻す変更のサイズ: 単一の小さなPRを元に戻すことは、大規模な複数PRの変更を元に戻すよりもはるかにリスクの低い提案です。
元に戻す変更の経過時間: 最近マージされたPRを元に戻すことは、古いPRを元に戻すよりも受け入れられやすいでしょう。古いPRで発見されたバグが広範囲に深刻な問題を引き起こしている可能性は低いです。
元に戻すことに内在するリスク: 元に戻すことで、クリティカルな機能が壊れますか？治療は病気よりも危険ですか？
修正の作成の難易度: 明確な解決策がある問題の場合、元に戻すのではなく、修正を実装してマージする方が望ましい場合があります。

元に戻すことが望ましいと判断した場合、元に戻すを実行するコントリビューターの責任は以下のとおりです。

関係者への連絡: PRの作成者と作業をマージしたエンジニアの両方に連絡を取り、元に戻すことを通知する必要があります。
簡潔な再現手順の提供: 問題がPRの元の作成者によって明確に理解され、再現できることを確認します。
コードレビューによる元に戻す: 元に戻すことは、別のコミッターによって承認される必要があります。

デザインガイドライン

大文字化ガイドライン

センテンスケース

UI内のすべてのもの（これらの**を除く）にセンテンスケースの大文字化を使用します。

センテンスケースは、主に小文字です。最初の単語の最初の文字と、以下のような大文字化が必要な他の単語のみを大文字化します。

固有名詞。 プロダクト内のオブジェクトは固有名詞とはみなされません。例: ダッシュボード、チャート、保存されたクエリなど。独自の機能名、例: SQL Lab、Preset Managerは固有名詞とみなされます。
頭字語 (例: CSS、HTML)
センテンスケースから大文字化されたUIラベル（例: ページタイトル - ダッシュボードページ、チャートページ、保存されたクエリページなど）を参照する場合。
UIに反映されるユーザー入力。例: ユーザーが名前を付けたダッシュボードタブ

センテンスケースとタイトルケース: タイトルケース: "A Dog Takes a Walk in Paris" センテンスケース: "A dog takes a walk in Paris"

なぜセンテンスケース？

一般的に、最も速く読める形式として受け入れられています。
一般名詞と固有名詞を区別する最も簡単な形式です。

UI要素を参照する方法

UI要素について記述する場合は、UIで使用されているのと同じ大文字化を使用します。

たとえば、入力フィールドに「Name」というラベルが付いている場合、これを「Name入力フィールド」と参照します。同様に、ボタンに「Save」というラベルが付いている場合、「Saveボタン」と参照するのが正しいです。

製品ページに「Settings」というタイトルが付いている場合、これを文章で次のように参照します。「Settingsページで個人情報を編集します」。

多くの場合、製品ページには、その中に含まれるオブジェクトと同じタイトルが付いています。この場合、UIに表示されるページを参照し、オブジェクトを一般名詞として参照します。

ダッシュボードページにダッシュボードをアップロードする
ダッシュボードに移動
ダッシュボードを表示
すべてのダッシュボードを表示
CSSテンプレートページにCSSテンプレートをアップロードする
保存したクエリは、保存されたクエリページに表示されます
SQL Labでカスタムクエリを作成し、ダッシュボードを作成します

センテンスケースの例外

入力ラベル、ボタン、UIタブはすべて大文字です
ユーザー入力値（例: 列名、SQL Labタブ名）は、元のケースである必要があります

プログラミング言語の規約

Python

config.pyのパラメーター（Flask app.configディクショナリを介してアクセス可能）は、常に定義されていると想定されるため、以下のように直接アクセスする必要があります。

blueprints = app.config["BLUEPRINTS"]

以下のようにアクセスするのではなく。

blueprints = app.config.get("BLUEPRINTS")

後者は型付けの問題を引き起こすため、同様にアクセスすることも避けるべきです。前者はList[Callable]型ですが、後者はOptional[List[Callable]]型です。

型付け/型ヒント

明確さ、一貫性、すべての読みやすさを確保するために、すべての新しい関数は型ヒントを使用し、ドキュメント文字列を含める必要があります。

PEP-484に従って、明示的に発生する例外をリストするための構文は提案されていないため、この情報をドキュメント文字列に入れることを推奨します。つまり、

import math
from typing import Union


def sqrt(x: Union[float, int]) -> Union[float, int]:
    """
    Return the square root of x.

    :param x: A number
    :returns: The square root of the given number
    :raises ValueError: If the number is negative
    """

    return math.sqrt(x)

TypeScript

TypeScriptは完全にサポートされており、すべての新しいフロントエンドコンポーネントを作成するための推奨言語です。既存の関数/コンポーネントを変更する場合、TypeScriptへの移行は推奨されますが、必須ではありません。関数/コンポーネントをTypeScriptに移行する例は、#9162と#9180にあります。

プルリクエストのガイドライン​

プロトコル​

作成​

レビュー​

テスト環境​

マージ​

マージ後の責任​

issueとPRの管理​