CONTRIBUTING.md

本プロジェクトへの参加方法・ガイドライン

本サービスの開発・運営には、皆さまのご協力が不可欠です。

また、GitやGitHubを利用した共同開発の経験を積むための場所にもしたいと考えています(可能な限りサポートいたします)。

本プロジェクトへの参加方法

• GitHubで:star:を付ける
• 機能追加の要望や不具合を報告する
• ソースコードやドキュメントを修正する - 詳細は、後述の「プルリクエストの作成方法」を参照してください。
• GitHub スポンサーで寄付する

なお、GitやGitHubの利用が困難な場合は、@KATO-HiroまでDMをお願いいたします。

開発環境

バックエンド

• Supabase: BaaS

フロントエンド

• 開発言語
  • TypeScript
• JavaScriptのランタイム
  • Node.js: v24.x
• 汎用フレームワーク
  • Svelte: v5.x。Runes mode で運用中
  • SvelteKit: v2.x
• UIライブラリ
  • Flowbite Svelte - コンポーネントライブラリ
    • Flowbiteも利用可能
  • @dnd-kit/svelte - Svelte 5 ネイティブ対応のドラッグ&ドロップライブラリ（管理者向け: 問題集の並び順を管理するカンバンボードで使用。Flowbite Svelte では、同一のパネル内での並び替えができないことが判明したため）
  • Lucide - アイコンライブラリ
• テスティングフレームワーク
  • Vitest: 単体テスト (ユーティリティ、コンポーネント)
  • Playwright: e2eテスト
  • Nock: API 統合テスト用の HTTP モック
• 認証
  • 自前実装（セッション管理・パスワードハッシュ）。旧 Lucia v2 のセッション / パスワード形式に準拠（互換性維持のため、cookie 名・ハッシュ形式は安易に変更しないこと）
• ORM
  • Prisma
• バリデーション
  • Superforms
  • Zod
• パッケージマネージャ
  • pnpm
• 文法およびフォーマットチェッカー
  • oxlint: JS/TS ファイルの高速リンター（50–100x 高速）
  • ESLint: Svelte ファイル専用リンター（eslint-plugin-svelte）のみ使用
  • Prettier
  • lefthook: Git hooks 管理ツール（コミット前の自動フォーマット・リント）
• Search Engine Optimization (SEO) 対策
  • Svelte Meta Tags: メタタグ、Open Graph などの設定
  • super-sitemap: SvelteKit 専用の sitemap ジェネレータ
  • robots.txt: Webクローラーのアクセス制御に関する設定

インフラ

• Docker Desktop
• PostgreSQL: Relational DB

エディタと拡張機能

• Visual Studio Code (VS Code)
• Visual Studio Code Dev Containers

AI 支援ツール

• Claude Code（VS Code 拡張: anthropic.claude-code）
• Codex（VS Code 拡張: openai.chatgpt）
• RTK - AI コーディングアシスタント向けトークン最適化プロキシ
• CodeRabbit - AI コードレビュー

Claude Code と Codex は用途や利用可能な契約に応じて選択でき、同時利用は必須ではありません。共通規約は AGENTS.md、固有の設定は docs/guides/claude-code.md と docs/guides/codex.md を参照してください。Superpowers plugin はプロジェクトでは有効化せず、必要な場合に各自で導入します。

ホスティング、CI・CD関連

• Vercel
• GitHub Actions

プルリクエストの作成方法

GitHubアカウントを持っていない場合は?

有効なメールアドレス・ユーザ名・パスワードを用意して、アカウントの登録とGitHubでssh接続をしましょう

(初回のみ) 本レポジトリの内容をローカル環境にダウンロード

0. AtCoder NoviStepsにメンバー申請をします。@KATO-HiroにDMなどでご連絡いただければ、GitHubで登録しているメールアドレスに招待メールが届きますので、承認してください。

1. ターミナルなどを利用して、本レポジトリの内容をローカル環境にダウンロードします。

   git clone git@github.com:AtCoder-NoviSteps/AtCoderNoviSteps.git

   • HTTPS で clone 済みの場合は git remote set-url origin git@github.com:AtCoder-NoviSteps/AtCoderNoviSteps.git で SSH に切り替えてください。

2. 作業ディレクトリをAtCoderNovistepsに変更します。

3. 本レポジトリの最新情報を反映できるように、ご自身のリモートレポジトリに登録します。git remote -vで登録状況を確認できます。

   git remote add root_branch https://github.com/AtCoder-NoviSteps/AtCoderNoviSteps.git

(共通、Dockerのみ利用するユーザ向け) 開発環境のインストールとローカルの開発サーバを起動

手順

• Docker Composeのバージョンを確認します (動作チェックも兼ねています)。

  docker compose --version

• コンテナの利用状況を確認します。

  docker compose ps

• もしコンテナが起動している場合は、一度停止させます。

  docker compose down

• コンテナを起動し、webコンテナとdbコンテナが起動しているか確認します。

  docker compose up -d

  docker compose ps

• 関連するパッケージのインストールとDBの初期設定を行います。

  docker compose exec web pnpm install

  docker compose exec -e DATABASE_URL=postgresql://db_user:db_password@db:5432/test_db?pgbouncer=true&connection_limit=10&connect_timeout=60&statement_timeout=60000 -e DIRECT_URL=postgresql://db_user:db_password@db:5432/test_db web pnpm prisma db push

  docker compose exec web pnpm prisma generate

• 開発サーバ(port番号: 5173)を起動します。その後、以下のリンクを順番にクリックしてください。

  • Note: 5173 番ポートが使用中なら、使用中のプロセスを停止してから起動してください。自動的に切り替わる 5174 番は Compose で公開していません。

  docker compose exec web pnpm dev --host

  http://localhost:5173/

• ホーム画面が起動し、ユーザの登録・ログインができれば、環境構築は完了です。

• Note: 後述の「(共通) ローカルの開発サーバを起動」の操作を実行したい場合は、該当コマンドの前にdocker compose exec web を追加してください。

(共通) 開発環境のインストール

ローカルサーバを起動するための準備をします。公式ドキュメントも併せてご参照ください。

1. DockerとVS Codeを起動します。
2. コマンドパレットから、**Dev Containers: Open Folder in Container...**を選択し、AtCoderNovistepsフォルダを開きます。
   • Mac: Cmd + Shift + P
   • Windows: Ctrl + Shift + P
3. ローカルサーバを動作させるために必要な環境が自動的に構築され、VS Codeの拡張機能もインストールされます。

エージェントはコンテナを境界として動くため、エージェント自身のログイン情報以外はコンテナに置きません。

• CONFIRM_API_URL はローカル開発では不要です（連携済みユーザーはシードで作れます）。ホストの .env とシェルに設定しないでください。本物の値で確認するときだけ設定して Rebuild し、エージェントを使わずに確認後、値を外して再度 Rebuild します。
• ホストの VS Code のユーザー設定に "dev.containers.gitCredentialHelperConfigLocation": "none" を追加し、GitHub のトークンをコンテナに共有しないようにします。
• コンテナ内の sudo はファイアウォール専用です。apt のパッケージや Playwright のブラウザは Dockerfile を変更して Rebuild します。
• インターネット向けの通信は init-firewall.sh の許可リストに限られ、Docker ネットワーク内では web から db:5432 への通信を許可します。許可リストの宛先が突然つながらないときは CDN の IP が変わった可能性があるので、コンテナを Rebuild します。スクリプトを変更した場合も Rebuild が必要です。宛先の追加は、持ち出し経路が増えるため必要なものだけにします。
• devcontainer.json に VS Code の拡張機能を追加したときは、init-firewall.sh の vscode_extension_publishers にも発行者 ID（esbenp.prettier-vscode なら esbenp）を追加します。

ホスト側で SSH の鍵を ssh-agent へ登録

秘密鍵はコンテナに mount せず、SSH agent forwarding でホストの ssh-agent に署名だけを依頼します。ホスト側で鍵が agent に載っていないと、コンテナ内の Git 操作が Permission denied (publickey) で失敗します。

ホストの ~/.ssh/config に次を書いておくと、ホストで ssh を使うたびに鍵が自動で agent に載ります。IdentityFile は実際の鍵の path に置き換えてください（ls -la ~/.ssh/ で確認。.pub が付かない方が秘密鍵）。

Host *
  AddKeysToAgent yes              # ssh-add 相当を自動実行する
  UseKeychain yes                 # macOS のみ。passphrase を Keychain から読む
  IdentityFile ~/.ssh/id_ed25519

この設定が有効になるのはホストで ssh を実行したときだけです。コンテナ内の ssh はホストの設定も鍵も読まず agent に問い合わせるだけなので、ホストで一度 ssh -T git@github.com を実行して agent に載せてください。以降は転送済みの socket 経由でコンテナからも見えます。ssh-agent はホスト側のプロセスなので、コンテナを rebuild するときには再登録不要です。

macOS では ssh-agent が launchd により自動起動するため、起動操作は不要です。Windows では ssh-agent サービスが既定で無効なため、初回だけ PowerShell で有効化します。

Set-Service ssh-agent -StartupType Automatic; Start-Service ssh-agent

(共通) ローカルの開発サーバを起動

• 新しいターミナルを開いてください。

• 依存関係にあるライブラリのインストールとデータベースの初期化を行い、開発サーバを起動します。

  pnpm install

  pnpm exec prisma db push

  pnpm dev

• 以下のリンクをクリックしてください。

  http://localhost:5173/

• また、開発サーバの起動と同時に新しいブラウザタブでアプリを開くこともできます。

  pnpm dev --open

• 先ほどとは異なるターミナルで以下のコマンドをそれぞれ実行すると、データベースの初期データ投入やローカル環境でのテーブル・サンプルデータが閲覧できます。

  pnpm db:seed

  • admin と guest は AtCoder アカウント連携済みになります（既存の DB も再実行で反映）。

  sh -lc "pkill -f 'prisma.*studio' || true"

  pnpm db:studio --port 5555

• 以下のリンクをクリックしてください。

  http://localhost:5555/

(共通) ソースコードやドキュメントの加筆・修正

注: 2024年4月以降、ブランチを以下のように分けています。

staging : 開発・運営チームの検証用環境です(デフォルトブランチ)。

main: 一般公開用の環境です。バグの修正のような緊急性の高い作業ときのみ指定します。

本レポジトリの最新の状態を反映させる方法

1. 本レポジトリの最新の内容を取得します。

   git fetch root_branch

2. 取得した内容をご自身のローカル上のブランチにマージします。stagingの部分を変えれば、別のブランチにすることも可能です。

   git merge root_branch/staging

3. ご自身のリモートブランチを更新します。

   git push origin staging

作業用のブランチ作成からプルリクエスト作成まで

1. 作業用のブランチを作成します。

   git checkout -b <your-new-branch-for-working> origin/staging

   例: GitHubのIssue番号や機能名・ドキュメントやバグの種類などを表すキーワードを使います。

   git checkout -b "#998244353" origin/staging

   git checkout -b "feature/feature-name" origin/staging

   git checkout -b "docs/docs-name" origin/staging

   git checkout -b "bugfix/bug-name" origin/staging

2. ソースコードやドキュメントの加筆・修正を行います。以下のコマンドを実行し、アプリが意図した通りに動作するか確認してください。

• 本レポジトリの最新の状態を取り込み、開発サーバが起動するか確認

  git pull origin staging

  pnpm install

  pnpm dev

• フォーマットの自動修正と、全PRで必須の機械的検証

  pnpm format

  pnpm lint

  pnpm check

  pnpm test:unit

• アプリの製品バージョンの作成と動作確認

  pnpm build

  pnpm preview

3. 2.の内容をレポジトリに反映します。コミットメッセージは、加筆・修正した内容を端的に表したものであることが望ましいです。

   git add .

   git commit -m "your-commit-message (#IssueID)"

   例:

   git commit -m "feat: Add new feature (#998244353)"

   git commit -m "docs: Update README (#1333)"

   git commit -m "chore: Fix typo (#10007)"

4. プルリクエストを作成する前に、加筆・修正した内容を確認します。

   git diff origin <your-current-branch>

   CI の build、lint、check、unit test は全PRで必須です。AI 主導の非軽微な変更では、30ファイル以上の編集、認証・認可・秘密情報、DB schema・migration・データ変換、共通 architecture・公開 interface のいずれかを変更した場合に、実装した agent とは別の agent でレビューします。この条件に該当しない軽微な変更のAIレビューは任意です。別 agent を利用できない場合は coderabbit review --plain で代用できます。指摘は自動修正せず、対応項目を選んでから修正します。

5. 本レポジトリに更新内容を反映させます。

   git push origin <your-current-branch>

6. プルリクエストを作成します。

Git Hooks（フォーマット・リント）

本プロジェクトでは、lefthookを使用して、コミット前に自動的にコードの書式チェック・フォーマットを行います。

• Pre-commit Hook: ステージ済みファイルのみに対して以下を実行
  • prettier --write: コード書式の自動修正（JavaScript、TypeScript、Markdown、Svelte）
  • oxlint: JS/TS ファイルのリント（JavaScript、TypeScript）
  • eslint: Svelte ファイルのリント（.svelte のみ）

Hook は自動的にセットアップされるため、特別な操作は不要です。

Hook を実行したくない場合

環境変数 LEFTHOOK=0 を設定して commit してください。

LEFTHOOK=0 git commit -m "コミットメッセージ"

(既存ユーザ向け) husky から lefthook への移行

husky でセットアップ済みの開発環境で新しい PR をマージした場合、以下を実行してください：

git config --unset core.hooksPath
pnpm exec lefthook install

これにより、古い husky の設定をクリアして lefthook に切り替わります。

トラブルシューティング

• エラー: コンテナ内の git fetch / git push が Permission denied (publickey) で失敗する

  • 原因: ホストの ssh-agent に鍵が未登録。コンテナ内の ssh-add -l が The agent has no identities を返すかで判別できる
  • 対処方法: ホストで ssh -T git@github.com を一度実行する。手順と注意点は「(SSH で GitHub を利用する場合) ホスト側で鍵を ssh-agent へ登録」を参照

• エラー: ローカル環境で開発用サーバを立ち上げても、ブラウザに表示されない

  • 前提条件: Docker Desktop 4.30.0 以上、かつ、VSCode DevContainer で Vite を動かす場合。Windows、macOS で発生する
  • 原因: Dockerで、ホストが IPv4 のみを使用している場合でも、::1 を返すようになったため
  • 対処方法: vite.config に、server の host を追記する
  • 参考資料
    • Docker の Issues
    • Vite の Issues
    • Zenn の記事
    • 本プロジェクトでの対処状況

• エラー: Docker Desktop で Vite を利用したときに Segmentation Fault が発生

  • 対処方法: Docker Desktopで「Use Visualization Framework」のチェックを外す
  • 参考資料: https://qiita.com/naoto24kawa/items/160aad0ca58642216a0a