コンテンツにスキップ

Kage Developer Docs

コントリビューション

KTC-Security-Circle/Kage

Kage への貢献¶

このプロジェクトへの貢献に興味を持っていただき、ありがとうございます。バグ報告、機能提案、プルリクエストなど、あらゆる形の貢献を歓迎します。

開発ワークフロー¶

Issue の確認: まず、Issue Tracker を確認し、同様の Issue がないか確認してください。なければ新しい Issue を作成します。
リポジトリのフォーク: このリポジトリをフォークします。
ブランチの作成: 新しいブランチを作成します。ブランチ名はブランチ命名規則に従ってください。

# 例: 新機能の場合
git checkout -b feature/new-task-button

# 例: バグ修正の場合
git checkout -b fix/textarea-overflow

# 例: イシュー番号を含める場合
git checkout -b feature/123-task-filter

poethepoet のインストール: グローバルに poethepoet をインストールします（未インストールの場合）。

# poethepoetをグローバルにインストール
uv tool install poethepoet

環境セットアップ: poethepoet タスクランナーを使用した初回セットアップを実行します。

# 初回セットアップ（依存関係同期 + DB更新）
poe setup

コードの変更: コーディング規約に従って、コードの追加・修正を行います。
テストとコード品質チェック: 変更によって既存の機能が壊れていないことを確認します。

# 品質チェック（lint + format-check + type-check）
poe check

# 自動修正（lint-fix + format）
poe fix

# テスト実行
poe test

開発中の動作確認: アプリケーションを起動して動作を確認します。

# 開発モード（ホットリロード）
poe app-dev

コミット: 変更内容をコミットします。コミットメッセージは分かりやすく記述してください。
プルリクエストの作成: フォークしたリポジトリから、このリポジトリの main ブランチに対してプルリクエストを作成します。プルリクエストのテンプレートに従い、変更内容を説明してください。

詳細なタスクコマンドについてはタスクランナーガイドを参照してください。

コーディング規約¶

静的解析: ruff を使用した静的解析とフォーマットを適用します。pre-commitフックが自動で実行します。
命名規則:
クラス名: PascalCase
関数・変数名: snake_case
Docstring: クラスや公開関数には、Google スタイルの docstring を記述してください。

def my_function(param1: int, param2: str) -> bool:
    """関数の概要説明.

    Args:
        param1: 引数1の説明.
        param2: 引数2の説明.

    Returns:
        戻り値の説明.
    """
    # ...

型ヒント: すべての関数・メソッドの引数と戻り値に型ヒントを付けてください。
コメント: 複雑なロジックや重要な処理には、日本語で簡潔なコメントを記述してください。

ドキュメント規約¶

ドキュメントは MkDocs + Material を使用して管理されています。

ドキュメントの構造¶

ドキュメントファイルは docs/ ディレクトリ以下に配置
開発者向けドキュメントは docs/dev/ 以下に配置
画像ファイルは docs/images/ 以下に配置

Markdown 記述規則¶

内部リンク: 他のドキュメントへのリンクは相対パスで記述
```
[セットアップガイド](dev/setup.md)
```
画像: 画像へのリンクは相対パスで記述し、キャプションを付ける
```
![画像の説明](../images/image-name.png)
_画像のキャプション_
```
見出し: 階層構造を意識し、適切にレベル分けする
コードブロック: 言語指定をして読みやすく記述
```
# Python コードの例
def example():
    pass
```

ドキュメントのテスト¶

ドキュメントを変更した場合は、必ずローカルでビルドとプレビューを確認してください。

# ローカルプレビュー（推奨）
poe docs-serve

# ビルドテスト
poe docs-build

# 従来のコマンド
uv run mkdocs serve
uv run mkdocs build --strict

リンクチェック¶

内部リンクが正しく機能することを確認する
画像ファイルが存在し、適切に表示されることを確認する
ビルド時にエラーや警告が出ないことを確認する

ご協力に感謝します！