Skip to content

development-guide.md

Latest commit

 

History

History
160 lines (103 loc) · 8.63 KB

development-guide.md

File metadata and controls

160 lines (103 loc) · 8.63 KB
Raw

Language: English | 日本語

KHI開発環境のセットアップ

本ドキュメントは、KHIのコード開発に貢献するために開発環境をセットアップする手順を記載しています。 まずは Contribution Guide をお読みいただいた上で、本ドキュメントに沿って開発環境をセットアップしてください。

KHIをビルドする

ビルドに必要な依存関係

初回セットアップ

  1. このリポジトリをダウンロードまたはクローンします。
    例: git clone https://github.com/GoogleCloudPlatform/khi.git
  2. プロジェクトルートに移動します。
    例: cd khi
  3. プロジェクトルートから make setup を実行します。 (この Make ターゲットは、npm パッケージのインストール、自動生成コードの生成、git フックの設定を行います)

KHI のビルドと実行

  1. gcloud で認証します。
    例: ユーザーアカウントの認証情報を使用する場合は、gcloud auth login を実行します。
  2. make build を実行します。
  3. 生成された実行ファイル ./khi を実行します。
  4. http://localhost:8080 を開き、KHI の使用を開始してください！

開発環境のセットアップ

KHIレポジトリをforkする

KHIレポジトリに直接新しいブランチを作成することはできません。あなたのアカウントにKHIレポジトリをforkしてください。

コミット署名の設定

こちらのドキュメント の手順に沿って、コミットに署名を付与するように設定してください。コミット署名なしのコミットは受付できません。

バージョン管理とコミット前フックについて

本プロジェクトではバージョン管理ツールとして git よりも Jujutsu (jj) の使用を推奨しています。

git を使用する場合、make setup を実行することで git の pre-commit フックがインストールされます。このフックはコミット前にライセンスヘッダの有無、コードの自動フォーマット、linterの実行を自動的に行い、フォーマット等のミスによるCIの失敗を防ぎます。

一方、jj を使用する場合、ネイティブの自動フック機能が現状サポートされていないため、make setup ではフックはインストールされません。jj を利用する場合は、コミット作成前（またはプッシュ前）に手動で make pre-commit を実行するか、jj のエイリアス機能等を用いて make pre-commit を自動化させてください。

AI アシスタント (Gemini CLI / Antigravity) のサポート

本リポジトリには、gemini-cli や Antigravity などの AI アシスタントツールを前提とした設定が整備されています。 プロジェクトルートや各ディレクトリに配置された GEMINI.md、および .agents フォルダ内のルール定義を活用することで、AI アシスタントがプロジェクト固有のコーディング規約やコンテキストを自動的に認識し、開発を効果的にサポートします。AI アシスタントを利用した開発を行う際は、これらの設定ファイルが読み込まれていることを確認してください。

VSCodeの設定

このレポジトリにはVSCodeの設定ファイルが用意されています。VSCodeでKHIサーバーを起動する方法や、フロントエンドのコードに設定されたbreakpointを機能させるためのChromeの起動設定が含まれています。

  • .vscode/launch.json:
    • Start KHI Backend: KHIのバックエンドサーバを起動します。ポート8080で起動します。
    • Launch KHI Frontend (Chrome): KHIのフロントエンドサーバを起動しChromeで開きます。ポート4200で起動します。 4200/api宛のリクエストは8080にプロキシされます。
    • Launch Storybook (Chrome): KHIのStorybookを起動しChromeで開きます。ポート6006で起動します。
    • Launch Karma (Chrome): KHIのフロントエンドのテスト環境のKarmaを起動しChromeで開きます。ポート9876で起動します。

フロントエンドサーバーの実行

フロントエンドの開発を実施する際、下記のコードを実行すると開発環境のAngularサーバーを4200番ポートで実行できます。

make watch-web

KHIの開発環境のAngularサーバーはリクエストを localhost:4200/api からlocalhost:8080にプロキシします(the proxy config)。 localhost:8080ではなく localhost:4200 にてKHIにアクセスできます。 開発環境のAngularサーバーは自動的にビルドされ、フロントエンドのコードの変更が自動で適用されます。

テストの実行

下記を実行すると、フロントエンドとバックエンドのコードのテストが実行されます。

make test

バックエンドのテストをCloud Loggingと一緒に実行したい場合は下記のコードを実行してください。

go test ./... -args -skip-cloud-logging=true

Storybookの起動

フロントエンドの開発を実施する際、下記のコードを実行すると開発環境のStorybookサーバーを6006番ポートで実行できます。

make watch-storybook

Storybookは自動的にビルドされ、フロントエンドのコードの変更が自動で適用されます。

自動生成コード

バックエンドコードから自動作成されるフロントエンドコード

下記のフロントエンドのコードは、バックエンドのコードから自動生成されます。

  • /web/src/app/generated.scss
  • /web/src/app/generated.ts

上記のファイルは scripts/frontend-codegen/main.go Golang codesにて、Golang側の一部の定数からテンプレートをもとに生成されます。

マークダウンリンター

KHIではmarkdownlint-cli2を使用して、Markdownファイルにおけるキュメントのスタイルを構成します。

markdownlint-cli2の使用

KHIプロジェクトは markdownlint-cli2 をディペンデンシーとして含んでいるため、下記をインストールする必要があります。

npm install

下記のコマンドでリンターが実行されます:

make lint-md

マークダウンを自動的に修正するには下記を実行します:

make format-md

コンテナイメージのリリース

KHIはコンテナイメージのデプロイプロセスを自動化しています。 GitHubでリリースを作成すると、専用のタグが自動的に生成されます。この操作がトリガーとなり、コンテナが自動的にビルドされ、リポジトリにプッシュされます。

  • プレリリース
    • tagを vx.y.z-betaとして命名すると、 下記のアドレスとしてデプロイされます。
      • gcr.io/kubernetes-history-inspector/release:beta
      • gcr.io/kubernetes-history-inspector/release:vx.y.z-beta
  • リリース
    • tagをvx.y.z として命名すると、 下記のアドレスとしてデプロイされます。
      • gcr.io/kubernetes-history-inspector/release:vx.y.z
      • gcr.io/kubernetes-history-inspector/release:latest

Note

リリースの作成後にデプロイプロセスが開始されます。イメージがリポジトリにプッシュされるまで1時間ほどかかる場合があります。

プルリクエストのコードに対するオンデマンドビルドの使用

レポジトリ管理者は、プルリクエストに対して github-deploy-ondemand チェックを実行できます。これによりイメージがgcr.io/kubernetes-history-inspector/develop:$SHORT_SHAにデプロイされます。

Note

このイメージは、最後のチェックのためだけのものです。まず、あなたの環境でコードが正しいことを確認してください。 ビルドには1時間かかる場合があります。