Ionicへの貢献

Ionic Frameworkへの貢献にご興味をお持ちいただきありがとうございます！

貢献のエチケット

行動規範については、貢献者行動規範をご覧ください。

issueの作成

• フレームワークの使用方法について質問がある場合は、Ionicフォーラムでお尋ねください。

• 発生している問題を再現するために必要な手順を明確に記述する必要があります。できる限りユーザーを支援したいと考えていますが、明確な再現手順がない問題の診断には非常に時間がかかり、単に持続可能ではありません。

• Ionicリポジトリのissueリストは、バグレポートと機能リクエスト専用です。適合しないissueはすぐにクローズされます。

• 再現手順が明確でないissueはトリアージされません。「needs: reply」ラベルが付いたissueに対して、issueの作成者から14日間以上返信がない場合は、クローズされます。

• バグを見つけたと思われる場合、または新しい機能のアイデアがある場合は、まずそれがすでに報告されていないことを確認してください。既存のissueを検索して、同様のものが報告されているかどうかを確認できます。解決策とともにクローズされた可能性があるため、クローズされたissueも含めてください。

• 次に、問題を詳細に説明する新しいissueを作成してください。issueを送信する前に、入力済みのissueフォームにご記入ください。

優れたコード再現の作成

コード再現とは？

コード再現とは、特定の問題をデモンストレーションするために構築された小さなアプリケーションです。コード再現には、問題を再現するために必要な最小限のコードを含める必要があり、単一の問題に焦点を当てる必要があります。

なぜ再現を作成する必要があるのですか？

発生している問題のコード再現により、問題の原因をより適切に特定できます。これは、バグを修正するための重要な最初のステップです！

信頼できるコード再現がないと、問題を解決できない可能性が高く、クローズにつながります。言い換えれば、問題のコード再現を作成することで、私たちがあなたを助けることができます。

再現の作成方法

• スターターテンプレートのいずれかを使用して、新しいIonicアプリケーションを作成します。 `blank`スターターアプリケーションは、このための優れた選択肢です。次のIonic CLIコマンドを使用して作成できます。 `ionic start myApp blank`
• 発生している問題を再現するために必要な最小限のコードを追加します。問題の再現に必要ないものは含めないでください。これには、インストールしたサードパーティのプラグインが含まれます。
• アプリケーションをGitHubに公開し、issueを作成する際に、アプリケーションへのリンクを含めてください。
• 問題を再現する手順を含めてください。これらの手順は明確で、従うのが簡単でなければなりません。

再現を作成するメリット

• **Ionicの最新バージョンを使用する：**新しいIonicアプリケーションを作成することで、フレームワークの最新バージョンに対してテストしていることを確認できます。発生している問題は、フレームワークの新しいバージョンで既に解決されている場合があります！
• **最小限の表面積：**問題の再現に必要ないコードを削除することで、問題の原因を特定しやすくなります。
• **秘密のコードは不要：**問題の最小限の再現を作成することで、プロジェクトで使用されている独自のコードを公開する必要がなくなります。
• **問題の修正に関するヘルプを得る：**問題を確実に再現できれば、問題に対処できる可能性が高くなります。

プルリクエストの作成

• 貢献のお時間をいただきありがとうございます！プルリクエストを送信する前に、バグまたは機能リクエストを説明するissueを作成し、プルリクエストを作成する予定であることをお知らせください。issueが既に存在する場合は、そのissueにコメントして、プルリクエストを送信したいことをお知らせください。これは、プルリクエストを追跡し、重複した作業がないことを確認するのに役立ちます。

• 修正するissueをお探しですか？ help wantedラベルが付いたissueを確認してください！

セットアップ

1. Node.jsのLTSバージョンのインストーラーをダウンロードします。これは、npmをインストールするのにも最適な方法です。
2. Ionicリポジトリをフォークします。
3. フォークをクローンします。
4. 変更のためにmasterから新しいブランチを作成します。
5. 変更するパッケージ（core、angularなど）のディレクトリに移動します。
6. `npm install`を実行して、このパッケージの依存関係をインストールします。
7. 以下の特定のパッケージの手順に従ってください。

Core

コンポーネントの変更

1. `core/src/components/`内にある変更するコンポーネントを見つけます。
2. Stencilドキュメントと他のコンポーネントを見て、これらのコンポーネントの実装を理解します。
3. コンポーネントに変更を加えます。変更が過度に複雑であるか、通常とは異なる場合は、変更を理解できるようにコメントを追加してください。
4. 変更をローカルでプレビューします。
5. 必要に応じて、ドキュメントを変更します。
6. ディレクトリでlintを実行し、エラーがないことを確認します。
7. プロジェクトをビルドします.
8. ビルドが完了したら、変更をコミットします。すべてのコミットでコミットメッセージの形式に従ってください。
9. 変更のプルリクエストを送信します。

変更のプレビュー

1. `core`ディレクトリ内で`npm start`を実行します。
2. ブラウザが`https://#:3333/`で開きます。
3. ここから、コンポーネントのテストのいずれかに移動して、変更をプレビューします。
4. 変更内容を示すテストが存在しない場合は、新しいテストを追加するか、既存のテストを更新してください。
5. RTLモードでテストするには、目的のコンポーネントのテストに移動したら、URLの末尾に `?rtl=true` を追加します。例： `https://#:3333/src/components/alert/test/basic?rtl=true`。

Lint による変更のチェック

1. TypeScript と Sass の Lint を実行するには、`npm run lint` を実行します。
2. Lint エラーがある場合は、`npm run lint.fix` を実行してエラーを自動的に修正します。手順 1 を繰り返してエラーが修正されたことを確認し、修正されていない場合は手動で修正します。
3. TypeScript エラーのみを Lint し、修正するには、それぞれ `npm run lint.ts` と `npm run lint.ts.fix` を実行します。
4. Sass エラーのみを Lint し、修正するには、それぞれ `npm run lint.sass` と `npm run lint.sass.fix` を実行します。

ドキュメントの変更

1. コンポーネントのディレクトリにある `readme.md` ファイルを探します。
2. このファイルの `<!-- Auto Generated Below -->` という行の**上**にあるドキュメントを変更します。
3. その行の下にある自動生成されたドキュメントを更新するには、以下の場所で関連する変更を行います。

• `Usage`：コンポーネントの `usage/` ディレクトリにあるコンポーネントの使用例を更新します。
• `Properties`、`Events`、または `Methods`：コンポーネントの TypeScript ファイル（`*.tsx`）を更新します。
• `CSS Custom Properties`：コンポーネントのメイン Sass ファイル（`*.scss`）を更新します。

テストの変更

1. コンポーネントのディレクトリにある `test/` フォルダー内で変更するテストを探します。
2. テストが存在する場合は、修正された問題または追加された機能を再現する例を追加してテストを変更します。
3. 新しいテストが必要な場合は、コンポーネントの `test/` ディレクトリから `basic/` ディレクトリをコピーし、名前を変更して、`index.html` ファイルと `e2e.ts` ファイルの両方の内容を編集するのが最も簡単な方法です（このファイルの詳細については、スクリーンショットテスト を参照してください）。
4. `preview/` ディレクトリは、ドキュメントでデモとして使用されます。テストにバグがある場合、または API に変更があり、テストで更新されていない場合にのみ、このテストを更新してください。

スクリーンショットテスト

1. スクリーンショットにテストが存在する場合、テストのディレクトリに `e2e.ts` という名前のファイルがあります。
2. スクリーンショットテストは、このファイルを含め、`page.compareScreenshot()` の呼び出しを含む 1 つ以上の `test()` 呼び出しを追加することで追加できます。Stencil のエンドツーエンドテスト と `core/` にある既存のテストを例として参照してください。
3. **重要：** 各 `test()` には、スクリーンショット（`page.compareScreenshot()`）の呼び出しが 1 つだけ**または**各テストの最後に期待値をチェックする必要があります。不一致がある場合、テストは失敗し、テストの残りの部分が実行されなくなります。つまり、最初のスクリーンショットが失敗した場合、残りのスクリーンショットの呼び出しは、別のテストにない限り、またはすべての期待値が最後に呼び出されない限り、呼び出されません。
4. スクリーンショットをローカルで実行するには、次のコマンドを使用します： `npm run test.screenshot`。
   • 特定のテストのスクリーンショットを実行するには、テストへのパスまたは検索する文字列を渡します。
   • たとえば、すべての `alert` テストを実行するには： `npm run test.screenshot alert`。
   • または、基本的な `alert` テストを実行するには： `npm run test.screenshot src/components/alert/test/basic/e2e.ts`。

変更のビルド

1. すべての変更が行われ、ドキュメントが更新されたら、`core` ディレクトリ内で `npm run build` を実行します。これにより、必要に応じて、自動生成されたファイルに変更が追加されます。
2. 変更を確認し、すべてが正しければ、コミットします。
3. コミットする前にビルドが完了していることを確認してください。ドキュメント、プロパティ、メソッド、または生成ファイルの更新が必要なその他の変更を行った場合は、これをコミットする必要があります。
4. 変更がプッシュされた後、ブランチを公開し、プルリクエストを作成します。

プルリクエストの送信

1. `master` ブランチを `base` として新しいプルリクエストを作成します。変更を見つけるには、`compare across forks` をクリックする必要がある場合があります。
2. 詳細については、GitHub ヘルプ記事のフォークからのプルリクエストの作成を参照してください。
3. 提供されているプルリクエストテンプレートにできる限り記入し、関連する問題を含めてください。

コミットメッセージのガイドライン

Git コミットメッセージのフォーマット方法について、非常に厳密なルールがあります。これにより、プロジェクト履歴を確認するときに、読みやすく、理解しやすいメッセージが作成されます。また、Git コミットメッセージを使用して、変更ログを生成します。私たちのフォーマットは、Angular のコミットメッセージガイドラインと非常によく似ています。

コミットメッセージのフォーマット

私たちは、Conventional Commits specificationに従います。コミットメッセージは、**ヘッダー**、**本文**、**フッター**で構成されます。ヘッダーには、**タイプ**、**スコープ**、**件名**があります。

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

**ヘッダー**は必須で、ヘッダーの**スコープ**はオプションです。

Revert

コミットが以前のコミットを元に戻す場合、`revert: ` で始まり、その後に元に戻されたコミットのヘッダーが続きます。本文には、`This reverts commit <hash>.` と記載する必要があります。ここで、ハッシュは元に戻されるコミットの SHA です。

タイプ

プレフィックスが `feat`、`fix`、または `perf` の場合、変更ログに表示されます。ただし、破壊的変更がある場合、コミットは常に変更ログに表示されます。

以下のいずれかである必要があります。

• **feat**：新機能
• **fix**：バグ修正
• **docs**：ドキュメントのみの変更
• **style**：コードの意味に影響を与えない変更（空白、フォーマット、セミコロンの欠落など）
• **refactor**：バグを修正したり、機能を追加したりしないコード変更
• **perf**：パフォーマンスを向上させるコード変更
• **test**：不足しているテストの追加
• **chore**：ビルドプロセスまたはドキュメント生成などの補助ツールとライブラリの変更

スコープ

スコープは、コミット変更の場所を指定する任意の値にすることができます。通常はコンポーネントを指しますが、ユーティリティを指すこともできます。たとえば、`action-sheet`、`button`、`css`、`menu`、`nav` などです。同じコンポーネントに対して複数のコミットを行う場合は、このコンポーネントの名前を統一してください。たとえば、ナビゲーションに変更を加え、最初のコミットが `fix(nav)` の場合、ナビゲーションに関連するコミットには `nav` を引き続き使用する必要があります。一般的なルールとして、コンポーネントを変更する場合は、フォルダーの名前を使用します。

件名

件名には、変更の簡潔な説明が含まれています。

• 命令形、現在形を使用します。「変更済み」や「変更」ではなく「変更する」を使用します。
• 最初の文字は大文字にしません。
• 末尾にピリオド `.` を付けないでください。
• コミットメッセージ全体の長さは50文字を超えてはいけません。
• コミットが関連する問題または修正する問題ではなく、コミットの内容を説明します。
• **簡潔でありながら、記述的にする** - 件名を読むことで、コミットの内容をよく理解できる必要があります。

本文

**件名**と同様に、命令形、現在形を使用します。「変更済み」や「変更」ではなく「変更する」を使用します。本文には、変更の動機と、以前の動作との違いを含める必要があります。

フッター

フッターには、**破壊的変更**に関する情報を含める必要があり、このコミットが**閉じる** GitHub の問題を参照する場所でもあります。

**破壊的変更**は、`BREAKING CHANGE:` という単語で始まり、その後にスペースまたは2つの改行が続きます。残りのコミットメッセージは、これのために使用されます。

例

生成された変更ログには表示されません。

docs(changelog): update steps to update

「機能」ヘッダー、トーストサブヘッダーの下に表示されます。

feat(toast): add 'buttons' property

問題 #28 へのリンクとともに、「バグ修正」ヘッダー、スケルトン textsubheader の下に表示されます。

fix(skeleton-text): use proper color when animated

closes #28

「パフォーマンスの向上」ヘッダーと、「破壊的変更」の下に破壊的変更の説明とともに表示されます。

perf(css): remove all css utility attributes

BREAKING CHANGE: The CSS utility attributes have been removed. Use CSS classes instead.

破壊的変更の説明とともに「破壊的変更」の下に表示されます。

refactor(animations): update to new animation system

BREAKING CHANGE:

Removes the old animation system to use the new Ionic animations.

次のコミットとコミット `667ecc1` は、同じリリースの下にある場合、変更ログに表示されません。そうでない場合、revert コミットは「Reverts」ヘッダーの下に表示されます。

revert: feat(skeleton-text): add animated property

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

ライセンス

ionic-team/ionic GitHub リポジトリにコードを提供することにより、MIT ライセンスの下でコントリビューションをライセンスすることに同意したことになります。