広聴AIへの貢献

広聴AIの改善にご協力いただきありがとうございます！ 🎉

このドキュメントは、広聴AIプロジェクトに参加したい方のためのガイドです。コードの実装に加え、感想・質問・事例の共有や動作確認もプロジェクトの改善につながります。

AIエージェントを使う方は、AIエージェントを使ったコントリビュートで読む順番と作業導線を確認してください。

セキュリティ上の問題は公開Issueへ投稿せず、セキュリティポリシーに記載された非公開の報告先へ連絡してください。

コードを書かずに参加する

環境構築やプログラミングの経験がなくても参加できます。まずは次の中から一つ選んでください。

やってみること	残す内容と場所
自分も困っているIssueに👍を付ける	Issue一覧で近い話題を探し、リアクションを付けます。優先順位の判断材料になります。
レポートを読んで感想・質問を伝える	分からなかった言葉や操作、便利だった点を、関連IssueかSlackの「開発_広聴AI」に残します。「理由は分からないけど読みにくい」でも役立ちます。
説明書を読み、つまずいた箇所を伝える	説明書のURL、読んだ箇所、期待したことと実際に起きたことを、関連Issueか新しいIssueに記載します。文章の修正案だけでも歓迎します。
活用事例や使ってみたいデータを紹介する	活用事例は#564へ、公開された出典URLと用途を添えます。データの提案は関連IssueかSlackへ、入手元と利用条件を添えます。
募集中の動作確認に協力する	Issueに書かれた対象・手順・必要な環境を確認し、結果をそのIssueに残します。実APIを使う確認はAPI利用料が発生する場合があるため、キーが不要な作業から選ぶこともできます。
ラベルや説明のA/B比較に回答する	比較の募集があるとき、提示された同じ意見・文脈をもとに「A / B / 同程度 / 判断できない」と理由を回答します。まだ比較案がない場合は、関連Issueで協力できる旨を伝えてください。
体験をブログやSNSで紹介する	レポートを読んだ感想やコミュニティで感じたことを書き、関連IssueやSlackで記事URLを共有します。

感想・質問の書き方

全部を埋める必要はありません。個人情報や非公開データ、APIキーは貼らず、公開してよい範囲で記載してください。

見たページ・説明書のURL：
やろうとしたこと：
分かりにくかった点／便利だった点：
期待していたこと：
（不具合の場合）端末・ブラウザ、再現する操作：

同じ話題のIssueがあればコメントを追加し、見つからなければ新しいIssueを作れます。GitHubでの投稿に迷う場合はSlackで質問してください。作業を引き受ける場合のassignee指定は下の「Issueへの着手」を参照してください。感想・質問・リアクションのために作業を引き受ける必要はありません。

このプロジェクトについて

• ブロードリスニングを実現するためのソフトウェア「広聴AI」PJのリポジトリです。

開発への参加方法について

• 本PJは、開発者の方からのコントリビュートを募集しています！ぜひ一緒に日本のデジタル民主主義を前に進めましょう！
• 開発に参加する方は、一般ユーザーと異なり、GitHubからリポジトリをクローンして作業します。
• プロジェクトについてのやりとりは、原則デジタル民主主義2030のSlackの「開発_広聴AI」チャンネルまでお願いします。
• コントリビュートにあたっては、本リポジトリのrootディレクトリにあるCLA.md（コントリビューターライセンス）へ同意が必要です。
• 同意する手順は、Pull Requestのテンプレートに記載があります。
• タスク管理はgithub projectsを利用しています。詳細はこちらを参照してください。

Issue管理とPull Requestについて

レビュアー向けのガイドラインはこちら

Issueの作成と参加

• Issueはどなたでも起票いただけます。ツール利用時に感じた改善点やバグについてぜひIssueを作成してください
• 解決されると自分に役立つIssueには👍リアクションを付けてください
• リアクションの件数はIssueの優先度を決める重要な指標となります

Issueへの着手

• 重複作業を避けるため、Issueに取り組む際はご自身をassigneeに指定してください
• /assign コメントを記載するとIssueのassigneeとして登録されます
• 権限の関係で一部のコントリビューターを除きアサイン機能が使えないため、このような運用をしています
• 割当解除には /unassign コメントをご利用ください
• 初めての貢献に適したタスクにはgood first issueラベルが付いています

コードの貢献プロセス

数行以上のコードを提供する場合は、実装に着手する前に以下のステップをお願いします： 1. 関連するIssueがない場合は、まず新たにIssueを作成してください 2. 実装計画を投稿し、メンテナや他の開発者からの賛同（リアクション）を得てから着手してください 1. 特に、軽微なバグやUIの修正ではなく、新機能の追加や大規模なアーキテクチャの変更を行う場合には、メンテナーのリアクションを得てから開発に着手してください 2. このプロセスは必須ではありません。ただし、コミュニティでは事前に合意が得られているPRを優先的に確認します。また、事前に合意が得られていない変更はマージされない可能性がある点をご理解ください。

このプロセスにより： - 同じ問題への重複した取り組みを防止できます - プロジェクトの方針と一致した実装となります - API、UI、アーキテクチャの変更が十分に検討されます

注意: 事前承認なしに新機能を追加するPRはマージされにくい傾向があります。新機能追加にはAPI設計や将来の保守など多くの負担が伴うためです。

コードのフォーマットについて

• コードをコミットする前に、コードのフォーマットを整えてください
• api については、以下のコマンドでフォーマットのチェックと自動整形を実施できます
  • チェック: make lint/api-check
  • 整形: make lint/api-format
• public-viewer / admin については Biome で lint, format のチェックを実施できます
  • チェック: pnpm run lint
  • 整形: pnpm run format
  • Pull Request では CI（client build / client-admin build）が biome ci を実行し、lint・format のエラーがあると失敗します。push 前に pnpm run format をかけてください
  • Lefthook で git push 時に Biome のチェックをかける設定をしています
  • プロジェクトルートの lefthook-local.sample.yml を参考に、lefthook-local.yml を用意してください

Pull Requestのプロセス

1. 最新のmainブランチからフィーチャーブランチを作成してください
2. プルリクエストを作成し、変更の詳細を説明してください
3. コードレビューを受け、必要に応じて変更を加えてください
4. メンテナーのapproveを得ると、変更がマージされます

現在のメンテナー（2025/04/26時点）

• @nanocloudx
• @nishio
• @nasuka
• @shingo-ohki
• @mtane0412
• @tokoroten

上記のうち1名がapproveした場合にmainへのマージを行います。メンテナーは将来的に増やしていく予定です。

CLAへの同意

本リポジトリへのコントリビュートには、コントリビューターライセンス契約（CLA）に同意することが必須です。Pull Requestを提出する際に、テンプレートに従ってCLAへの同意を示してください。

困ったときは

質問や問題がある場合は、デジタル民主主義2030のSlackの「開発_広聴AI」チャンネルで質問してください。コミュニティのメンバーが喜んでお手伝いします。

ご貢献ありがとうございます！