Incusにコントリビュートするには

Pull Request、GitHubレポジトリでのイシュー、f フォーラムでの議論や質問を通してプロジェクトに貢献していただけることをIncusチームは感謝します。

プロジェクトへ貢献する前に、以下のガイドラインを確認してください。

Code of Conduct

コントリビュートする際には、行動規範を遵守しなければなりません。行動規範は、以下のサイトから入手できます。https://github.com/lxc/incus/blob/main/CODE_OF_CONDUCT.md

ライセンスと著作権

デフォルトで、このプロジェクトに対するいかなる貢献も Apache 2.0 ライセンスの下で行われます。

変更の著者は、そのコードに対する著作権を保持します (著作権の譲渡はありません)。

Pull Request

このプロジェクトへの変更は、GitHubのhttps://github.com/lxc/incusでPull Requestとして提案してください。

提案された変更はそこでコードレビューを受け、承認されればメインブランチにマージされます。

コミット構成

コミットを次のように分類する必要があります。

  • API拡張（doc/api-extensions.mdとinternal/version/api.goを含む変更に対してapi: Add XYZ extension）

  • ドキュメント（doc/内のファイルに対してdoc: Update XYZ）

  • API構造（shared/api/の変更に対してshared/api: Add XYZ）

  • Goクライアントパッケージ（client/の変更に対してclient: Add XYZ）

  • CLI（cmd/の変更に対してcmd/<command>: Change XYZ）

  • Incusデーモン（incus/の変更に対してincus/<package>: Add support for XYZ）

  • テスト（tests/の変更に対してtests: Add test for XYZ）

同様のパターンがIncusコードツリーのほかのツールにも適用されます。 そして複雑さによっては、さらに小さな単位に分けられるかもしれません。

CLIツール（cmd/）内の文字列を更新する際は、テンプレートを更新してコミットする必要があります。

make i18n
git commit -a -s -m "i18n: Update translation templates" po/

API（shared/api）を更新する際は、swagger YAMLも更新してコミットする必要があります。

make update-api
git commit -s -m "doc/rest-api: Refresh swagger YAML" doc/rest-api.yaml

このようにすることで、コントリビューションに対するレビューが容易になり、安定ブランチへバックポートするプロセスが大幅に簡素化されます。

開発者の起源の証明

このプロジェクトへの貢献の追跡を改善するために、DCO 1.1を使用しており、ブランチに入るすべての変更に対して「サインオフ」手順を使用しています。

サインオフとは、あなたがそのコミットを書いたことを証明する、そのコミットの説明の最後にある単純な行です。 この行は、自分が書いたものであることを証明したり、オープンソースとして渡す権利があることを証明したりします。

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

有効なサインオフラインの例は以下の通りです。

Signed-off-by: Random J Developer <random@developer.org>

実名と有効な電子メールアドレスを使用してください。 残念ながら、ペンネームや匿名での投稿はできません。

また、それぞれのコミットには作者が個別に署名する必要があります。 大きなセットの一部であってもです。git commit -sが役に立つでしょう。

開発を始める

開発環境をセットアップし、Incus の新機能に取り組みを開始するには以下の手順に従ってください。

依存ライブラリのビルド

依存ライブラリをビルドするにはIncusをソースからインストールするの手順に従ってください。

あなたのforkのremoteを追加

依存ライブラリをビルドし終わったら、GitHub の fork を remote として追加できます。

git remote add myfork git@github.com:<your_username>/incus.git
git remote update

次にこちらに切り替えます。

git checkout myfork/main

Incusのビルド

最後にリポジトリ内でmakeを実行すればこのプロジェクトのあなたの fork をビルドできます。

この時点で、あなたが最も行いたいであろうことはあなたの fork 上にあなたの変更のための新しいブランチを作ることです。

git checkout -b [name_of_your_new_branch]
git push myfork [name_of_your_new_branch]

Incusの新しいコントリビュータのための重要な注意事項

  • 永続データはINCUS_DIRディレクトリーに保管されます。これはincus admin initで作成されます。 INCUS_DIRのデフォルトは/var/lib/incusです。

  • 開発中はバージョン衝突を避けるため、Incus のあなたの fork 用にINCUS_DIRの値を変更すると良いでしょう。

  • あなたのソースからコンパイルされる実行ファイルはデフォルトでは$(go env GOPATH)/binに生成されます。

    • あなたの変更をテストするときはこれらの実行ファイル（インストール済みかもしれないグローバルのincus adminではなく）を明示的に起動する必要があります。

    • これらの実行ファイルを適切なオプションを指定してもっと便利に呼び出せるよう~/.bashrcにエイリアスを作るという選択も良いでしょう。

  • 既存のインストール済み Incus のデーモンを実行するためのsystemdサービスが設定されている場合はバージョン衝突を避けるためにサービスを無効にすると良いでしょう。

ドキュメントへのコントリビュート

私たちは Incus をできるだけ簡単に使えるようにしたいと考えています。 ですので、Incus を使用するユーザーが必要とする（よくある使い方すべてをカバーし、典型的な質問に答えるような）情報を含んだドキュメントを提供を目指しています。

いろいろな方法でドキュメントにコントリビュートできます。 あなたのコントリビュートを感謝します！

コントリビュートする典型的な方法は以下のとおりです。

  • コードにあなたがコントリビュートする新機能や機能改善についてのドキュメントを追加あるいは更新します。私たちはドキュメントの更新をレビューし、あなたのコードとともにマージします。

  • Incus を使っているときに感じた疑問点を明確にするようなドキュメントを追加あるいは更新します。それらの修正は Pull Request またはフォーラムのTutorialsセクションへの投稿で送ってください。新しいチュートリアルはドキュメントへ含める（リンク経由で参照あるいは実際のコンテンツをインクルード）ことを検討します。

  • ドキュメントの修正を依頼するために、GitHubでドキュメントに関するイシューを作成します。

  • 質問や提案をフォーラムに投稿してください。 私たちはイシューを評価し、適切にドキュメントを更新します。

  • IRCの#lxcチャンネルで質問したり提案してください。IRC の動的な性質のため、IRC の投稿に回答や反応することを保証はできませんが、チャンネルを注視して受け取ったフィードバックにもとづいてドキュメントを改善するつもりです。

ドキュメントのフレームワーク

Incus のドキュメントはSphinxでビルドされます。

ドキュメントはMarkdownとMySTの拡張で書かれています。 構文のヘルプやガイドラインについては、ドキュメントチートシート (ソース)を参照してください。

構成に関しては、このドキュメントではDiátaxisアプローチを採用しています。

ドキュメントのビルド

ドキュメントをビルドするには、リポジトリのルートディレクトリーからmake docを実行します。このコマンドは必要なツールをインストールして、出力をdoc/html/ディレクトリーにレンダリングします。 変更されたファイルのみを対象に（ツールを再インストールすることなく）ドキュメントを更新するには、make doc-incrementalを実行します。

Pull Request をオープンする前に、ドキュメントが警告なしでビルドできることを確認してください（警告はエラーとして扱われます）。 ドキュメントをローカルでプレビューするには、make doc-serveを実行しhttp://localhost:8001をブラウザで開いてください。

Pull Request をオープンすると、ドキュメントのプレビュー出力が自動的にビルドされます。

ドキュメントの自動チェック

GitHub はドキュメントのスペル、リンク先が正しいか、Markdown ファイルのフォーマットが正しいか、差別用語を使用していないか、を自動的にチェックします。

ローカルでも以下のコマンドでこれらのチェックができます（してください！）。

  • スペルをチェックする：make doc-spellcheck

  • リンクの有効性をチェックする：make doc-linkcheck

  • Markdown のフォーマットをチェックする：make doc-lint

  • 差別用語を使っていないかをチェックする：make doc-woke

上記を実行するためには、以下のものが必要です:

  • Python 3.8以降

  • venv pythonパッケージ

  • スペルチェック用にaspellツール

  • mdl markdown lintツール

ドキュメントの設定オプション

注釈

現在ドキュメントの設定オプションをコード内のコメントに移行中です。 現時点では、一部の設定オプションはこのアプローチに沿っていません。

ドキュメントの設定オプションは Go コード内のコメントから抽出されます。 コード内のgendoc:generateで始まるコメントを参照してください。

設定オプションを追加または変更する際は、それに必要なドキュメントのコメントを含めるようにしてください。

次にmake generate-configを実行してdoc/config_options.txtファイルを再生成してください。更新されたファイルはチェックインしてください。

ドキュメントでは、設定オプションのグループを表示するために、doc/config_options.txtの一部をインクルードしています。 たとえば、コアのサーバーオプションをインクルードするには以下のようにします。

% Include content from [config_options.txt](config_options.txt)
```{include} config_options.txt
    :start-after: <!-- config group server-core start -->
    :end-before: <!-- config group server-core end -->
```

既存のグループに設定を追加した場合は、ドキュメントファイルを更新する必要はありません。 新しいオプションは自動的に取り込まれます。 新しいグループを追加した場合のみ、ドキュメントファイルにインクルードを追加する必要があります。