貢献#

コントリビューター行動規範 Code Triage

私たちは貢献を心から歓迎し，このガイドがPyVistaコードリポジトリの理解を促進することを願っています．PyVistaソフトウェアパッケージはボランティアベースでメンテナンスされていることに注意してください．したがって，このソフトウェアをすべてのユーザにとって有用なツールにするために，ユーザの質問をサポートし，新しい機能を開発できるコミュニティを育成する必要があります．

このページでは，質問，懸念，機能のリクエスト，または貢献したいことから始めるべき概要を説明します．

尊敬の念を抱くこと#

他の人々，他のソフトウェア，そして（関連性のない）ツールを作るために熱心に働いてきたコミュニティに対して，共感と優しさを示してください．

Pull RequestsやIssuesなどで，他人やその作品を否定するような言い方をしないでください．

ソースリポジトリのクローン作成#

次のコマンドを実行して， pyvista/pyvista からソースリポジトリをクローンし，最新バージョンをインストールできます．

git clone https://github.com/pyvista/pyvista.git
cd pyvista
python -m pip install -e .

Codespacesを使ったクイックスタート開発#

Open in GitHub Codespaces

開発用コンテナが提供されており，すぐに使い始めることができます。デフォルトのコンテナには，リポジトリコードがお好みのブランチでチェックアウトされ，テスト依存関係を含むすべてのpyvista依存関係がプリインストールされています．さらに， desktop-lite feature を使用してライブインタラクションウィンドウを提供します．ライブインタラクションを使うには Connecting to the desktop の指示に従ってください．

また，OSMesaライブラリと vtk-osmesa を使用したオフスクリーンバージョンも利用できます．

質問#

プロジェクト，そのアプリケーション，またはソフトウェアの使用に関する一般的な質問については，コミュニティが共同であなたの質問に対処できる Discussions リポジトリにdiscussionを作成してください．

Slack に参加することも歓迎しますが，Slack は技術的な議論ではなく，その場限りの会話やコミュニティへの参加に使うべきです．

重要でハイレベルなプロジェクトサポートや関与については， info@pyvista.org まで電子メールをお送りください．

全ての技術的な会話については， issues ページ で議論を作成していただければ，すぐに対処いたします．ディスカッションのページに投稿することで，必要な専門知識を持つコミュニティメンバーが問題に対処でき，得られた情報は他のユーザーが見つけるのに引き続き利用できます．

バグの報告#

ここで配布されているコードの使用中にバグ，クラッシュ，または奇妙な点に遭遇した場合は，すぐに対処できるよう適切なラベルを付けて issues ページ に報告してください．問題を報告する際は，再現できるように，過度に記述してください．可能な限り，トレースバック，スクリーンショット，およびサンプルファイルを提供してください．

機能の要望#

PyVistaのコードベースを改善するためのアイデアを投稿することを推奨します． issuesページ に Feature Request ラベルをつけて改善を提案してください．説明的なタイトルを使用し，コミュニティがその機能を実装するのに役立つ十分な背景情報を提供してください．たとえば，特定のファイル形式のリーダーが必要な場合は，そのファイル形式のドキュメントへのリンクを提供し，操作するスクリーンショットを含むサンプルファイルを提供してください．問題のスレッドをディスカッションの場として使用し，フィードバックを提供します．

新しいコードの提供#

PyVistaを改善する方法についてアイデアがある場合は，まず機能リクエストとして問題を作成してください．これは，コントリビューションの実装方法を検討するためのスレッドとして使用できます．

PyVista用のコーディングと開発を始める準備ができたら，詳細については Development Practices セクションを参照してください．

ライセンス#

コントリビュートされたコードはすべて，リポジトリーにあるMITライセンスの下でライセンスされます．自分でコードを作成しなかった場合は，既存のライセンスに互換性があり，コントリビュートされたファイルに含まれていることを確認するか，元の作成者からコードを再ライセンスする許可を得る必要があります．

開発手法#

この節では，PyVistaリポジトリで開発を行う方法について説明します．このリポジトリに直接コントリビュートする場合は，ここで説明するプラクティスに従ってください．

ガイドライン#

配列への直接アクセスと直感的なPythonプロパティを介したVisualization Toolkit (VTK) への直接アクセスにより，VTKライブラリ全体をあらゆる分野の研究者が容易にアクセスできるようにしたいと考えています．PyVistaをVTKの価値あるPythonインターフェースにするためには，さらに改善するために皆さんの助けが必要です．

1つか2つの興味深い解析アルゴリズムをフィルタとして追加したい場合，新しいプロットルーチンを実装したい場合，あるいは1-2のタイプミスを修正したい場合，あなたの努力は大歓迎です．

私たちが信じている3つの一般的なコーディングパラダイムがあります．

  1. 直感的な操作． PyVistaの目標は，直感的で使いやすいインターフェースをVTKライブラリーに戻すことです．すべての新機能には，初心者ユーザがライブラリの大部分にアクセスできるように，直感的な命名規則と明示的なキーワード引数が必要です．

  2. すべてをドキュメント化します ．少なくとも，追加されたメソッドまたはクラスのdocstringを含めます．何をしているのかを説明するのではなく，なぜそうしているのかを説明し，新しい機能の簡単な例を示します．

  3. テストを続ける． 高いテストカバレッジを目指します．詳細については， テストを参照してください．

著作権に関する2つの重要なガイドラインがあります．

  1. ライセンスが利用できない，または商用使用が禁止されているデータセットは含めないでください．それらはすべてのプロジェクトのライセンスを損なう可能性があります．

  2. ライセンスが利用できないコードスニペット(Stack Overflowなど )や商用使用が禁止されているコードスニペットは使用しないでください．それらはすべてのプロジェクトのライセンスを損なう可能性があります．

私達の Code of Conduct もご覧ください．

GitHub経由でPyVistaにコントリビュートする#

新しいコードをpyvistaに送信するには，まず pyvista GitHub リポジトリ をフォークし，フォークしたリポジトリをあなたのコンピュータにクローンします．次に，ローカルリポジトリの Branch Naming Conventions Section に基づいて新しいブランチを作成します．

次に，新しい機能を追加し，ローカルでコミットします．特に変更が複雑な場合は，過去のコミットに戻すことが役立つことが多いので，頻繁にコミットするようにしてください．また，頻繁に検査をしてください．テストの自動化については，以下の テストのセクション を参照してください．

コードをサブミットする準備ができたら， Creating a New Pull Request section の手順に従ってプルリクエストを作成します．

コーディングスタイル#

行幅が79文字を超えて99文字コードまで許されることを除き，可能な限り PEP 8 に準拠します．これは標準ではなく，むしろ例外となる傾向があるはずです．スタイルの不一致によるエネルギーの浪費を防ぐために， black によって統一されたコードスタイルが強制されます．

docstringについては，PEP 8 Maximum Line Length で規定されているガイドラインに従って，1行あたり72文字に制限してください．これは指令に従います．

チームによっては，より長い行数を強く希望する場合もあります．この問題に関して合意に達することができるチームによってのみ，または主にメンテナンスされているコードについては，コメントとdocstringを72文字で折り返すことを条件に，行の長さの制限を99文字まで増やしてもかまいません．

PEP 8以外でコーディングする場合は， PEP 20 - The Zen of Python を考慮してください．

import this

PyVistaは pre-commit を使用して，PEP8やその他のスタイルを自動的に強制します．詳しくは スタイルチェックのセクション を参照してください．

ドキュメンテーションスタイル#

PyVistaは，以下の例外を除き， Google Developer Documentation Style に従っています．

  • 一人称の代名詞を許可します．これらの代名詞（例えば "We"）は "PyVista Developers" を指し，PyVistaに貢献するすべての人を指すことができます．

  • 未来形も可．

これらのルールはすべてのテキストファイル（例えば *.md, *.rst ）に適用され，Pythonのソースファイルには部分的に適用されます．

これらのルールは，GitHub Actionsを介して Vale を使用することで強制され，Valeをローカルで実行することができます．

pip install vale
vale --config doc/.vale.ini doc pyvista examples ./*.rst --glob='!*{_build,AUTHORS.rst}*'

LinuxやmacOSであれば，実行可能です:

make docstyle

Docstrings#

PyVistaでは，Python docstringsを使用して，Python APIのリファレンスドキュメントを作成しています．Docstringsは，開発者や対話型のPythonユーザー，そしてオンラインドキュメントの読者に読まれます．このセクションでは，PyVista用のdocstringの書き方について説明します．

PyVistaはdocstringのスタイルとして numpydoc に従っています．以下を除き，すべて numpydoc Style Guide に従ってください．

  • すべてのパブリックメソッドの Parameters と Returns を必ず記述してください．

  • Exampleのセクションを追加することを強くお勧めします．PyVistaは，ビジュアルなライブラリなので，プロットを示す例を追加することは，ユーザーが個々のメソッドが何を行うかを理解するのにとても役立ちます．

  • オプションのパラメータで， None の代わりにデフォルト値がある場合は， optional の代わりに default: <value> を使用します．

サンプル docstring は以下の通りです:

def slice_x(self, x=None, generate_triangles=False):
    """Create an orthogonal slice through the dataset in the X direction.

    Parameters
    ----------
    x : float, optional
        The X location of the YZ slice. By default this will be the X center
        of the dataset.

    generate_triangles : bool, default: False
        If this is enabled, the output will be all triangles. Otherwise the
        output will consist of the intersection polygons.

    Returns
    -------
    pyvista.PolyData
        Sliced dataset.

    Examples
    --------
    Slice the random hills dataset with one orthogonal plane.

    >>> from pyvista import examples
    >>> hills = examples.load_random_hills()
    >>> slices = hills.slice_x(5, generate_triangles=False)
    >>> slices.plot(line_width=5)

    See :ref:`slice_example` for more examples using this filter.

    """

    pass  # implementation goes here

以下のことに注意してください:

  • generate_triangles のパラメータ定義では， default: False を使用し， docstring の "description" セクションにデフォルトを含めません．

  • 各パラメータの間には改行が入ります．これは numpydoc のドキュメントで，パラメータの docstring の間に空白行がないのとは異なります．

  • この docstring には，リターンセクションとサンプルセクションも含まれています．

  • 関数の戻り値が1つの場合，リターンセクションにはパラメータ名を含めません．複数の戻り値(図示せず)には，入力パラメータと同じ形式で，各戻り値に対して説明的なパラメータ名を付ける必要があります．

  • サンプルセクションは，ギャラリーの "完全なサンプル" が存在する場合，それを参照します．

これらの標準は numpydoc-validate を使って pre-commit で実施され，エラーは次のように報告されます:

+-----------------+--------------------------+---------+-------------------------------------------------+
| file            | item                     | check   | description                                     |
+=================+==========================+=========+=================================================+
| cells.py:85     | cells.create_mixed_cells | RT05    | Return value description should finish with "." |
+-----------------+--------------------------+---------+-------------------------------------------------+
| cells.py:85     | cells.create_mixed_cells | RT05    | Return value description should finish with "." |
+-----------------+--------------------------+---------+-------------------------------------------------+
| features.py:250 | features.merge           | PR09    | Parameter "datasets" description should finish  |
|                 |                          |         | with "."                                        |
+-----------------+--------------------------+---------+-------------------------------------------------+

もし，何らかの理由で関数のルールに例外を設ける必要がある場合は， pyproject.toml の [tool.numpydoc_validation] セクションに例外を追加するか，インラインコメントを追加して特定のチェックを除外してください．例えば，セッターのドキュメント文字列を強制せず，GL08のチェックをスキップします．

@strips.setter
def strips(self, strips):  # numpydoc ignore=GL08
    if isinstance(strips, CellArray):
        self.SetStrips(strips)
    else:
        self.SetStrips(CellArray(strips))

numpydoc Validation で利用可能なバリデーションチェックを参照してください．

非推奨の機能またはその他の後方互換性のない変更#

PyVistaで後方互換性のない変更を実装するときは，ユーザーに新しい変更に適応する機会を与えるよう注意する必要があります．後方互換性のない変更は，次の手順で進める必要があります．

  1. 古い動作を保持し，使用すべき新しいインターフェイスを示す PyVistaDeprecationWarning を発行します．

  2. 古い動作を保持しますが，使用しなければならない新しいインターフェイスを示す pyvista.core.errors.DeprecationError を発行します．

  3. 古い動作を削除します．

可能な限り，PyVistaの開発者は，ユーザーがソフトウェアやスクリプトを更新できるように，少なくとも3つのマイナーバージョンの後方互換性を確保するように努めるべきです．

これはある関数のソフト非推奨の例です． PyVistaDeprecationWarning の警告と .. deprecated のSphinxディレクティブの両方を使用していることに注意してください．

import warnings
from pyvista.core.errors import PyVistaDeprecationWarning

def addition(a, b):
    """Add two numbers.

    .. deprecated:: 0.37.0
       Since PyVista 0.37.0, you can use :func:`pyvista.add` instead.

    Parameters
    ----------
    a : float
        First term to add.

    b : float
        Second term to add.

    Returns
    -------
    float
        Sum of the two inputs.

    """
    # deprecated 0.37.0, convert to error in 0.40.0, remove 0.41.0
    warnings.warn(
        '`addition` has been deprecated. Use pyvista.add instead',
        PyVistaDeprecationWarning
    )
    add(a, b)


def add(a, b):
    """Add two numbers."""

    pass  # implementation goes here

上記のコード例では，3つのマイナーリリースでエラーに変換し，次のマイナーリリースで完全に削除するためにコメントが作られていることに注目してください．重要な変更の場合はこれを長くし，些細な変更の場合は短くすることができます．

以下は，非推奨の警告メッセージを出すエラーテストコードを追加する例です．

with pytest.warns(PyVistaDeprecationWarning):
    addition(a, b)
    if pv._version.version_info >= (0, 40):
        raise RuntimeError("Convert error this function")
    if pv._version.version_info >= (0, 41):
        raise RuntimeError("Remove this function")

上記のコード例では，古いテストコードはv0.40とv0.41でエラーを発生させます．これによって，バージョンアップ時に非推奨を削除し忘れることを防ぐことができます．

既存のメソッドや関数に追加のパラメータを追加する場合には， .. versionadded というsphinxディレクティブを使用することが推奨されます．例えば:

def Cube(clean=True):
    """Create a cube.

    Parameters
    ----------
    clean : bool, default: True
        Whether to clean the raw points of the mesh.

        .. versionadded:: 0.33.0
    """

ブランチの命名規則#

開発を効率化するために，ブランチの命名には次の要件があります．これらの要件は，コア開発者がコードを調べる前に，あるブランチがどのような種類の変更を導入しているかを知るのに役立ちます．

  • fix/ ， patch/ ， bug/ : マイナーなバグ修正，パッチ，または実験的な変更

  • feat/: 新しい特徴または重要な追加を導入する変更

  • junk/: 古くなったら削除できる実験的な変更について

  • maint/: リポジトリまたはCIルーチンの一般的な保守用

  • doc/: 文書のみに関連する変更の場合

  • no-ci/: CIルーチンをトリガーしてはならない影響の少ないアクティビティの場合

  • testing/: テストの改善または変更

  • release/: リリース(下記参照)

  • breaking-change/: 後方互換性を破壊する変更

テスト#

変更を行った後，プルリクエストを作成する前にローカルで変更をテストしてください．コミットまたはプルリクエストの後に次のテストが実行されます．変更から新しい問題を追跡するには，ローカルで次の手順を実行してください．

総合的な単体テストを実行するには， requirements_test.txt と requirements_docs.txt にリストされているすべての依存関係をインストールします:

pip install -r requirements_test.txt
pip install -r requirements_docs.txt

すべてをインストールしたら，さまざまなテストスイートを実行できます．

ユニットテスト#

プライマリテストスイートを実行し，カバレッジレポートを生成します．

python -m pytest -v --cov pyvista

ユニットテストには時間がかかることがあります．高速化したい場合は， n フラグでプロセッサの数を設定してください．これは pytest-xdist を使用して，複数のプロセスを利用するものです．使用例です．

python -m pytest -n <NUMCORE> --cov pyvista

ドキュメンテーションテスト#

docstring内のすべてのコード例を実行します．

python -m pytest -v --doctest-modules pyvista

スタイルチェック#

PyVistaは， コーディングスタイルのセクション で説明されているようにPEP8標準に従っており， pre-commit を使ってスタイルチェックを実装しています．

コードが最小限のコードスタイリング基準に適合していることを確認するために，以下を実行してください．

pip install pre-commit
pre-commit run --all-files

もし pre-commit をインストールする際に setuptools に関連する問題が発生した場合は， pre-commit Issue #2178 comment で解決できる可能性がありますので参照してください．

また，pre-commit hookとして次のように実行することでインストールすることもできます．

pre-commit install

こうすれば，スタイルチェックに失敗したコードをプッシュすることは不可能になります．例えば，各コミットでスタイル要件を満たしているかどうかが自動的にチェックされます:

$ pre-commit install
$ git commit -m "added my cool feature"
black....................................................................Passed
isort....................................................................Passed
flake8...................................................................Passed
codespell................................................................Passed

実際の環境のインストールは， pre-commit install に続く最初のコミットの前に行われます．これは少し時間がかかりますが，それ以降のコミットでは実際のスタイルチェックが行われるだけです．

上記の作業を実施していない，または実施できる状況であっても，プルリクエストに pre-commit.ci autofix とコメントすることで，手動で自動修正をトリガーすることができます．

イメージ回帰テストに関する注意事項#

PyVista は基本的に描画モジュールなので，何らかの回帰テストで生成した画像を実際にチェックする必要があります．実際には，これはかなりの作業になります．

  • OpenGLソフトウェアとハードウェアレンダリングでは，レンダリングされるイメージがわずかに異なります．

  • CI (仮想フレームバッファを使用します)をデスクトップイメージ(ハードウェアアクセラレーションを使用します)と一致させたいと考えています．

  • OSによってレンダリングされるイメージは異なります．

各プラットフォームと環境では，Linuxと比較してわずかに異なるイメージをレンダリングするため(これらの画像は)，すべてのOSでこれらのテストを実行するのは最適ではありません．プロットを実際に見ることなく，プロットによって何か根本的な変化があったかどうかを知る必要があります(dev.pyvista.comのドキュメントのように)．

これらの点に基づいて，イメージ回帰テストはLinux CIでのみ行われ，マルチサンプリングは，ソフトウェアベースのレンダリングとハードウェアベースのレンダリングの最大の違いの1つと思われるため，無効になっています．

画像キャッシュは ./tests/plotting/image_cache としてここに保存されます．

大きな画像でgitを汚したくないので，画像解像度は400x400で低く保たれます．バージョンや環境によって多少の違いがあることが予想されるため， error < IMAGE_REGRESSION_ERROR は許容されます(警告としてログに記録されます．)が，この値を超えるとエラーが発生します．

pytest には，画像リグレッションテストを制御する2つのメカニズム， --reset_image_cache と --ignore_image_cache があります．

pytest tests/plotting --reset_image_cache

--reset_image_cache を実行すると， tests/plotting/test_plotting.py の各テストに対して新しいイメージが作成されます．テストや，メジャーまたはマイナーリリースの可能性がある場合を除き，推奨されません．Linux上で実行していて，リグレッションテストを一時的に無視したい場合は， --ignore_image_cache を使用することができます．CIテストでは，回帰テストが引き続き行われることを理解してください．

現在のところ，画像は tests/plotting/test_plotting.py にあるテストからのみキャッシュされます． デフォルトでは， Plotter.show を使用するテストは，自動的に画像をキャッシュします． 画像のキャッシュをスキップするには， verify_image_cache フィクスチャを使用します．

def test_add_background_image_not_global(verify_image_cache):
    verify_image_cache.skip = True  # Turn off caching
    plotter = pyvista.Plotter()
    plotter.add_mesh(sphere)
    plotter.show()
    # Turn on caching for further plotting
    verify_image_cache.skip = False
    ...

これにより，プロッタを閉じる直前に，現在のレンダリングウィンドウがCI内のイメージに対して検証されます．イメージが存在しない場合は，必ず次を使用して結果のイメージを追加してください．

git add tests/plotting/image_cache/*

ユニットテスト中に，画像のリグレッションに失敗して，ローカルに生成された画像をリグレッションテストスイートと比較したい場合， pytest-pyvista が --generated_image_dir フラグを使って新しい生成画像をすべてローカルディレクトリに書き込めるようにします．

例えば，以下は tests/plotting にある，関数名に volume が含まれるテストについて， pytest が生成したすべての画像を debug_images/ に書き込むものです．

pytest tests/plotting/ -k volume --generated_image_dir debug_images

詳しくは pytest-pyvista を参照してください．

ドキュメントの作成#

LinuxまたはMac OSでドキュメントをビルドします．

make -C doc html

Windows でドキュメントをビルドします．

cd doc
python -msphinx -M html source _build
python -msphinx -M html . _build

生成されたドキュメントは doc/_build/html ディレクトリにあります．

最初にローカルでドキュメントをビルドするときは，すべてのサンプルをビルドする必要があるため，しばらく時間がかかるでしょう．最初のビルドの後は，ドキュメントの作成にかかる時間はほんのわずかなものになるはずです．

ローカルビルドのクリア#

ローカルにビルドしたドキュメントをクリアする必要がある場合は，実行してください．

make -C doc clean

これは，ギャラリーの例を含むすべてをクリアします．もしギャラリーのサンプル以外をクリアしたいだけなら，実行します．

make -C doc clean-except-examples

これにより，すべてのサンプルを強制的に再構築することなく，キャッシュをクリアすることができます．

ドキュメントの並列ビルド#

以下でLinuxやMac OSでのドキュメントのビルド時間を改善することができます．

make -C doc phtml

これは効果的に SPHINXOPTS=-j を呼び出し，特にマルチコアコンピュータで有用です．

ドキュメンテーションへの貢献#

PyVistaのドキュメントは，3つのソースから作成されています:

  • pyvista のクラス，関数，モジュールから， sphinx.ext.autodoc を使用して，Docstringを取得します．

  • doc/ からテストを再構築

  • examples/ からのギャラリー例

一般的な使い方やAPIの説明は doc/api と docstrings に記述してください． 完全なギャラリーのサンプルは examples に置いてください．

新しい例の追加#

PyVistaのサンプルには2つの形式があります．個々のメソッドの機能を示す基本的なコードスニペットと，1つまたは複数のコンセプトを表示する完全なギャラリーの例です． 小さなコードサンプルやスニペットは doc/api ディレクトリやドキュメント文字列に含まれています．一方，完全なギャラリーサンプルは，ダウンロード可能なスクリプトとして実行するために，このリポジトリのルートにある examples ディレクトリに含まれています．

本格的なスタンドアロンサンプルを追加するには，PyVista Repository のルートディレクトリにある examples ディレクトリに，該当するサブディレクトリのいずれかにあなたのサンプルを追加してください． もし，既存のディレクトリがあなたのサンプルのカテゴリと一致しない場合は，新しいディレクトリを作成し，新しいカテゴリを記述した README.txt を記述してください． さらに，これらのサンプルはsphinx gallery 拡張を使って作成されていますので， Sphinx-Gallery が定めるコーディングガイドラインに従ってください．

詳しくは 新しいギャラリーを追加する例 を参照してください．

新しいサンプルファイルの追加#

もしギャラリーのサンプルに必要なデータセットがあれば，それを pyvista/vtk-data に追加し，そこにある指示に従ってください．それから，データセットをダウンロードする pyvista/examples/downloads.py ための新しい関数を追加する必要があります．これは以下のように簡単です．

def download_my_dataset(load=True):
    """Download my new dataset."""
    return _download_and_read('mydata/my_new_dataset.vtk', load=load)

以下を可能にします:

>>> from pyvista import examples
>>> dataset = examples.download_my_dataset()

新規Pull Requestの作成#

ブランチをローカルでテストしたら，mainにマージする際に pyvista GitHub でpull requestを作成します．これにより，継続的インテグレーション (CI) テストが自動的に実行され，変更が複数のプラットフォームで機能することが検証されます．

他のユーザーがコードをレビューできるようにするには，pyvistaコントリビュータグループの他の少なくとも1人のメンバーが，コードがコミュニティの標準を満たしているかどうかをレビューして検証する必要があります．承認後，書き込み権限があればブランチをマージすることができます．書き込みパーミッションがない場合，レビュー担当者または書き込みパーミッションを持つ別のユーザーがブランチをマージし，PRブランチを削除します．

ブランチをカレントリリースブランチ(下記参照)とマージする必要があるかもしれませんので， fix/ ブランチであれば削除しないでください．

ドキュメントをプレビューする#

Pull Requestを作成します．プルリクエストに github-actions preview とコメントすることで，ドキュメントをプレビューすることができます．このコマンドは @pyvista/developers にしか使えないので，新しい貢献者はコマンドをコメントするよう親切にお願いします．これは，潜在的に有害なコミットからデプロイサイトを守るために不可欠です．

ブランチモデル#

このプロジェクトは，安定性を犠牲にすることなく機能の迅速な開発を可能にする分岐モデルを持っており， Trunk Based Development アプローチに厳密に従います．

ブランチモデルの主な特徴は次のとおりです．

  • main ブランチは主要な開発ブランチです．すべてのフィーチャー，パッチ，およびその他のブランチをここにマージする必要があります．すべてのPRは適用可能なCIチェックをすべてパスする必要がありますが，変更によって予期しない副作用や単体テストで検出されなかったバグが発生する可能性があるため，このブランチは機能的に不安定になる可能性があります．

  • マイナーリリース(例えば release/0.24 )をベースにした release/ ブランチがいくつかあり，そこには PyPI/ にも反映される安定版のコードベースが含まれています． fix/ ブランチの修正パッチは，mainブランチとこれらのブランチの両方にマージする必要があります．新しいパッチリリースを作成する必要がある場合，これらのリリースブランチの pyvista/_version.py が更新され，セマンティックバージョン(例えば v0.24.1 )がタグ付けされます．これによりCIはPyPIにプッシュし，テストされていない機能を気にすることなく，過去のバージョンの pyvista のホットフィックスを迅速にプッシュすることができます．

  • マイナーリリース候補が準備できたら， main から新しい release ブランチが作成され，次のマイナーバージョン(例えば  release/0.25 )がインクリメントされ，徹底的にテストされます．安定していると判断された場合，リリースブランチにはバージョン(この場合の v0.25.0 )のタグが付けられ，必要に応じて変更が加えられた場合にはmainとマージされます． main で機能開発が継続され，ホットフィックスはこのリリースに統合されます．必要に応じてパッチを適用できるように，古いリリースブランチは削除しないでください．

マイナーリリース手順#

マイナーリリースは， pyvista の機能と安定性を改善する機能およびバグリリースです．マイナーリリースが作成される前に，次のことが発生します．

  1. main ブランチから release/MAJOR.MINOR という名前の新しいブランチを作成します(例: release/0.25 )．

  2. pyvista/_version.py の開発バージョン番号を更新し，コミットします(例: 0, 26, 'dev0')．ブランチをGitHubにプッシュし，mainにマージする今回のリリースの新しいPRを作成します．リリースに注力している間は，mainへの開発はこの時点では制限されるべきです．

  3. テストのセクション で概説されているように，すべてのテストをローカルで実行し，すべてが合格していることを確認します．

  4. リンクが古くなっていないことを確認するために，リンクチェックを行いながらドキュメントをローカルにテストしてビルドします．また， make clean を実行して，結果がキャッシュされていないことを確認してください．

    cd doc
make clean  # deletes the sphinx-gallery cache
make doctest-modules
make html -b linkcheck

  5. ドキュメントをビルドしたら，ローカル・ビルドを開き，サンプル・ギャラリーで明らかな問題がないか調べてください．

  6. 新しいリリースを機能的にテストするのは pyvista コミュニティの責任です．このブランチをローカルにインストールして運用環境で使用することをお勧めします．検出されたバグについては，ホットフィックスをこのリリースブランチにプッシュする必要があります．

  7. このブランチが安定版として一般公開されると，PR は main にマージされます． release/MAJOR.MINOR ブランチのバージョン番号を更新した後， release/MAJOR.MINOR ブランチは vMAJOR.MINOR.0 リリースというタグが付けられます．リリースブランチは削除されません．次のようにリリースにタグを付けます:

    git tag v$(python -c "import pyvista as pv; print(pv.__version__)")

  8. タグが正しく作成されたことを再度確認し，ブランチとタグをプッシュしてください．

    git push origin HEAD
git push origin --tags

  9. リリースのすべての変更のリストを作成します． GitHub's compare feature を活用して，最後のタグや main ブランチとの違いを確認することは，しばしば役に立ちます．特定の貢献者が新機能に感謝したい場合は，GitHubのユーザー名と適切な場所の記載で，新しい貢献者を必ず確認してください．

  10. 前の手順のリリースノートを GitHubの新リリース の説明に入れてください．

  11. ビール，コーヒー，水を飲みに行って， @regro-cf-autotick-bot がconda-forge PyVista feedstock のプルリクエストを開くのを待って，そのプルリクエストをマージします．

  12. Discussions ページで新リリースを発表し，お祝いしましょう．

パッチリリース手順#

パッチリリースは重要なバグフィックスのためのもので，マイナーリリースまで待つことはできないものです．パッチリリースの手順は

  1. 必要な(複数の)バグフィックスを該当するリリースブランチにプッシュします．これは通常，最新のリリースブランチ(例 release/0.25)です．

  2. 次のパッチ増分で pyvista/_version.py を更新し(例: v0.25.1 )，コミットし，リリースブランチとマージするPRをオープンします．これにより， pyvista コミュニティはバグ修正リリースを検証し，承認する機会を得ます．追加のホットフィックスは，このPRの範囲外でなければなりません．

  3. 承認されたら，リリースブランチとマージしますが， main ブランチのバージョンを増やす理由がないため， main とはマージしません．次に，リリースブランチから適切なバージョン番号(正しい手順については上記を参照してください．)のタグを作成します．

  4. 必要に応じて，リリースノートページを作成します．また，condaからPRを開き，マイナーリリースセクションの手順10の指示に従います．