diff --git "a/docs/\350\262\242\347\214\256\350\200\205\343\202\254\343\202\244\343\203\211\343\203\251\343\202\244\343\203\263.md" "b/docs/\350\262\242\347\214\256\350\200\205\343\202\254\343\202\244\343\203\211\343\203\251\343\202\244\343\203\263.md" new file mode 100644 index 0000000000..73756ff03d --- /dev/null +++ "b/docs/\350\262\242\347\214\256\350\200\205\343\202\254\343\202\244\343\203\211\343\203\251\343\202\244\343\203\263.md" @@ -0,0 +1,283 @@ +# 貢献者ガイドライン + +## 始めに + +まず初めに、VOICEVOXプロジェクトに関心を寄せて頂きありがとうございます。 +私たちは、あなたが積極的に参加してくれることを歓迎します。 + +実際に参加しようとすると、どんなコミュニティにもルールが存在し、そこを理解しないとハードルを高く感じてしまうこと +があります。 + +このガイドラインは、その部分を出来るだけ分かりやすく文章として残し、コミュニティへ参画しやすい環境を提供するために執筆されました。 + +## 担当 + +|役割 | 担当 | +|---------------|-------------| +|プロダクトオーナ|@Hiroshiba | +|メンテナー |@Hiroshiba
@y-chan | + +## 参加の心得 + +VOICEVOXプロジェクトは、いわゆる集団開発型のオープンソースソフトウェアにあたります。参加を望む方は、下記のことに注意して参加する必要があります。 + +* [VOICEVOXの目標](ミッション・バリュー・ビジョン.md)に照らし合わせて提案を行うと会話がスムーズです。 + +* 実施する中身については、コミュニティ内で会話をしながら合意を取っていく必要があります。また、プロジェクト方針により採用が拒絶されるケースがあります。 + +* 集団開発では、会話をしながら物を作っていくことが1つの醍醐味でもあります。一人で作品を作る時に比べて丁寧なコミュニケーションが必要です。会話相手に対して常に敬意を払ってください。 + +* プロジェクトへの参画に当たっては、年齢、国籍、境遇、性別などは関係ありません。これらの差別を行うことをプロジェクトは容認しません。 + +* プロジェクトは著作者や著作物を尊重します。常に他者の権利やライセンスを順守するように意識しています。プロジェクトへの貢献にあたっては、盗用したプログラムの提出は行わないでください。 + +* コントリビューターとして提供したプログラムは、プロジェクトが定義するライセンスで取り扱われる事に注意してください。 + +* プライバシーに関わる実装や、コンピュータに危害を与える可能性がある実装に関しては慎重な議論が必要です。実装を先におこなうのではなく、必ず合意形成をしてください。 + +## 貢献の仕方 + +このドキュメントでは、主にプログラムの改良を手伝ってくださる方に向けた、「参加の仕方」をガイドします。 + +VOICEVOXには、下記のような貢献の仕方があります。 + +* ユーザとして使う +* 記事や動画を公開して広める +* プログラムの改良を手伝う +* ドキュメントなどを書く + +プログラムは3部構成に分かれているので、該当する部分に該当するプロジェクトに参加しましょう。 + +|種類 |ページ |役割 | +|---------------|-------------|-------------| +|VOICEVOX |[プロジェクト](https://github.com/VOICEVOX/voicevox/)|主にユーザインタフェイス(エディタ)部分| +|VOICEVOX_ENGINE|[プロジェクト](https://github.com/VOICEVOX/voicevox_engine/)|主にAPI実装や音声合成を行う部分| +|VOICEVOX_CORE|[プロジェクト](https://github.com/VOICEVOX/voicevox_core/)|主に推論する部分| + +なお、全体構成を学びたい場合は、[こちら](全体構成.md)が参考になることでしょう。 + + +## 初心者歓迎タスク + +あなたがプログラム開発を学んだり、オープンソース開発コミュニティで活動することを実践したい場合は、既にコミュニティのIssuesで提案されている「初心者歓迎タスク」に参加することをお勧めします。 + +「初心者歓迎タスク」は、VOICEVOXプロジェクトとしては「難易度が比較的低い案件であるが、必要とされているもの」となっており、比較的一通りの工程をスマートに学びながら貢献することができます。 + +|種類 |ページ | +|---------------|-------------| +|VOICEVOX |[初心者歓迎タスク](https://github.com/VOICEVOX/voicevox/issues?q=is%3Aissue+is%3Aopen+label%3A%E5%88%9D%E5%BF%83%E8%80%85%E6%AD%93%E8%BF%8E%E3%82%BF%E3%82%B9%E3%82%AF)| +|VOICEVOX_ENGINE|[初心者歓迎タスク](https://github.com/VOICEVOX/voicevox_engine/issues?q=is%3Aissue+is%3Aopen+label%3A%E5%88%9D%E5%BF%83%E8%80%85%E6%AD%93%E8%BF%8E%E3%82%BF%E3%82%B9%E3%82%AF)| +|VOICEVOX_CORE|[初心者歓迎タスク](https://github.com/VOICEVOX/voicevox_core/issues?q=is%3Aissue+is%3Aopen+label%3A%E5%88%9D%E5%BF%83%E8%80%85%E6%AD%93%E8%BF%8E%E3%82%BF%E3%82%B9%E3%82%AF)| + +## 事前準備 + +ここからはWindowsをお使いの方が、VOICEVOX(エディタ)の環境を作るケースを想定し、話を進めます。まず、テスト版VOICEVOXの環境を構築しましょう。 + +#### 1)製品版VOICEVOXを導入する + +* まず。VOICEVOXの製品版を導入します。これによりすぐ使えるVOIECVOXエンジンを手に入れることができます。 + +#### 2)開発環境の構築 + +* 必須ツール + * [node.js](https://nodejs.org/en/download/releases/) + + [こちら](https://github.com/VOICEVOX/voicevox/blob/main/.node-version)に記載されているバージョンのインストーラを入手し、インストールします。 + +* 必要に応じて + * [Visual Studio Code](https://code.visualstudio.com/) + * [Tortoise Git](https://tortoisegit.org/download/) + * [Git](https://git-scm.com/downloads) + * [typos](https://github.com/crate-ci/typos#install) + +#### 3) フォークする + * 自分のワークスペースにソースを複製して作業準備をする作業をフォークと言います。[こちら](https://github.com/VOICEVOX/voicevox/fork)を押して、フォークを実施します。  + +#### 4) ソースコードを手に入れる + * 自分のワークスペースにあるソースコードを複製(クローン)をします。 + * Gitコマンドや Tortoise Gitなどのツールを用いて作業します。 + * Gitコマンド例としては、`git clone https://github.com/(個人ID)/voicevox.git`となります。 + +#### 5) 必要なプログラムをダウンロードする + * 手順4で手に入れたフォルダを開いて、コマンドプロンプトを開きます。 + * 環境を準備するコマンド ``npm ci`` を実行してください。自動的にダウンロードされます。 + +#### 6) エンジンを指定する + * `.env.production`というファイルがありますので、コピーして、名前を.envにします。 + * ファイルをエディタでひらいて、`DEFAULT_ENGINE_INFOS`内の`executionFilePath`に手順1のフォルダ名をいれます。たとえば、`D:\VOICEVOX0.14.1`に製品版をインストールしている場合は、下記のように書き換えて保存します。 + ``` + DEFAULT_ENGINE_INFOS=`[ + { + "uuid": "074fc39e-678b-4c13-8916-ffca8d505d1d", + "name": "VOICEVOX Engine", + "executionEnabled": true, + "executionFilePath": "D:/VOICEVOX0.14.1/run.exe", + "executionArgs": [], + "host": "http://127.0.0.1:50021" + } + ]` + VUE_APP_GTM_CONTAINER_ID=GTM-DUMMY + VV_OUTPUT_LOG_UTF8=1 + ``` +#### 7)始動してみる + * `npm run electron:serve`を実行します。 + * 設定が正しければ、開発環境が起動するはずです。 + +## 作業手順 + +### 1.提案と調整 + +まず、下記のことがあれば、Issueとして登録をしましょう。 + +* プログラムの仕様を変更したい +* 新機能を追加したい +* バグを確認した。 + +その際、VOICEVOXのどの部分に関して提案をしたいのかを考えて提案しましょう。そのとき、個人がわかる範囲で、良くなることや背反事項を書いて登録します。 + +この段階では、関係者と実装に関しての制約や影響範囲、プロジェクト方針として優先度や実施してよいかをすり合わせます。 + +### 2.ブランチを作る + +* 自分の作業フォルダ内に、今回加工するために作業エリアを作ります。 +* いくつかの案件を並走するなら、この手順でブランチをいくつか作ります。 +* ブランチ名は、自分のわかりやすいもので構いません。 + +### 3.プログラムを加工する + +実際にプログラムを書きます。プログラムを書くにあたっては、いくつかの流儀があります。 + +* 関数名や変数名は極力キャメルケースで命名する必要があります。何かしらの制約上キャメルケースで命名出来ない場合は、コメントを残します。 + ``` + // FIXME:●●のため、キャメルケースが採用できない。今後修正する + ``` +* 今回コーディングするが、構造制約などで「本来ありたい構造と異なる」場合にも、コメントを残します。 + ``` + // TODO:●●を使わずに、●●となる実装にしたい + ``` +* 変数名や型名の命名にあたっては、その仕組みで一般的に使われる命名則があれば、それらを優先して採用します。 +* 関数名は、動詞+役割となるように設定をします。 + |命名例 |役割 | + |-----------|----------------------------| + |setVolume()|音量を設定 | + |getVolume()|音量を取得 | + |isMute |ミュート状態の取得(boolean) | +* 変数や関数名につける英語は極力省略しないようにします。 +* コードは分かりやすさや単純さを保つようにしてください。 +* 不必要な定義や、作業中のコードは、コード提出までに除去しましょう。 + +### 4.事前テスト + +* 記述コードがコーディングルールに沿っていることを確認します。(特に今回の作業によって警告やエラーが増えていないかどうかに注目してください) + ``` + npm run lint + npm run fmt + ``` + +* TypeScriptの型チェックを行います。 + ``` + npm run typecheck + ``` + ※なお、現時点でエラーが大量に出るため採用されていませんが、今後下記のチェック方法に統一されていく予定です。 + ``` + npm run typecheck:vue-tsc + ``` + +* Markdownの記述が正しいことを確認します。 + ``` + npm run markdownlint + ``` + +* 命名に使っている英語が誤っていないことを確認します。 + ``` + typos + ``` + +* 個人環境でVOICEVOXを実行し、提出前に、一通り動くことを確認します。 + ``` + npm run electron:serve + ``` + +* 使用するライブラリが増減した場合は、ライセンス情報を更新します。 + ``` + # get licenses.json from voicevox_engine as engine_licenses.json + + npm run license:generate -- -o voicevox_licenses.json + npm run license:merge -- -o public/licenses.json -i engine_licenses.json -i voicevox_licenses.json + ``` + +* 同時にVOICEVOX-ENGINE側のAPIを変更した場合は、API定義も更新します。 + ``` + curl http://127.0.0.1:50021/openapi.json >openapi.json + + npx openapi-generator-cli generate \ + -i openapi.json \ + -g typescript-fetch \ + -o src/openapi/ \ + --additional-properties "modelPropertyNaming=camelCase,supportsES6=true,withInterfaces=true,typescriptThreePlus=true" + + npm run fmt + ``` + +### 5.コードの提出(プルリクエスト) +  +* 凡そ問題ないと判断できたら、提出します。この先は共同作業になるので、今一度問題ないか確認をしてください。 + +* 個人のリポジトリにコミットします。この時、コメントに「手順1で提案したIssue番号」を併記します。これにより追跡が行いやすくなります。 + ``` + ●●の機能を追加(ref #1190) + ``` +* コミットしたら、プルリクエストを発行します。これにより、VOICEVOXのプルリクエストに登録されます。 + +* プルリクエスト時、Issue番号と異なる追跡番号が付きますが、問題ありません。 + * Issueは実現したい事についての手段や実装方法を議論をします。 + * プルリクエストは記述されたコードについてのレビューや議論をします。 + +### 6.コードレビュー + +* レビュー担当やコミュニティメンバーによってソースの査読が行われます。課題が発見された場合には、記述修正の提案がおこなわれます。 + +* 納得できれば「提案通りに直す」方法もありますが、課題があると感じていれば、議論を行い最良点を探してください。 + +* この段階では、既にプルリクエストが出されていますので、自分のリポジトリに修正分をプッシュするだけで自動的に追跡されます。 + +* 現在のVOICEVOXのマージルールでは、基本的に2名以上の査読が必要となっています。 + +### 7.コンフリクト対応 + +* レビューが終ると、マージ(取り込み)準備が始まります。 + +* 作業中に他の修正が取り込まれている場合には、修正箇所が重なる「コンフリクト」という現象が発生します。 + +* コンフリクトが発生した場合には、プルリクエストの議論ページに「コンフリクトが発生している」と表示されるので、次の手順で修正を行います。 + + 1. 自分の作業リポジトリにプルします。プル元は、自分のGitHub領域ではなく、[VOICEVOXのリポジトリ](https://github.com/VOICEVOX/voicevox.git)を指定します。 + + 2. 自分の作業リポジトリにプッシュします。この時、「コンフリクトが発生したい」と表示されますが、そのまま続行します。 + + 3. 変更差分をみながら、修正がぶつかっている部分を正しい実装に修正します。 + + 4. 変更がすべて終わったら、手順4にあった「事前テスト」を改めて実施します。 + + 5. 問題なければ、コミットします。 + + 6. VOICEVOXのプルリクエスト議論ページで自動検査処理が走ります。この画面で「コンフリクトが発生した」という表示が消えたことを確認してください。 + +### 8. マージ処理 +* お疲れさまでした。この工程までいけば、貢献者の仕事はおわりです。 +* マージ担当者が確認後、マージ処理をします。 +* マージが終われば、個人のブランチは削除できます。 + +## 参考情報 + +* 実装時のデザインに関しては、[UX・UIデザインの方針](UX・UIデザインの方針.md)を参考に実装してください。 + +* 設計詳細については、[細かい設計方針](細かい設計方針.md)を参考にしてください。 + +* VOICEVOXは、様々な技術を使って実装しており、技術の理解が無いと読みづらい部分があります。全体の構造については、[コードの歩き方](コードの歩き方.md)を参考にしてみてください。 + +* 色については、[色の実装](色について.md)についてのドキュメントを参考にしてみてください。 + +* VOICEVOXで使用するフォントは、[フォントについて](フォントについて.md)に生成方法などが書いてあります。 + +