ドキュメントの追加¶

世界最高のソフトウェアを持っていても、誰も使い方がわからなければ意味がありません。ドキュメントは常に改善の余地があります。皆さんのご協力が必要です！

書類様式¶

BeeWare's documentation is written using MkDocs and Markdown. We aim to follow the Diataxis framework for structuring documentation.

Diataxisフレームワークは、ドキュメントの4つの「形態」を次のように定義する：

チュートリアル - 特定のプロジェクト目標を伴う、ガイド付きの学習体験。
ハウツーガイド - 読者を特定の目標や結果へと導く手順書。
トピックガイド - 単一のアイデアについて、その根底にある概念が明確になるように説明した議論。
参照 - 特定のAPIやその他のインターフェースに関する技術的な説明。

ドキュメントへの貢献を始める前に、どの形式が最適かを特定することが重要です。多くのドキュメント提案は当初「Xに関するチュートリアル」の要求として説明されますが、実際にはハウツー記事、トピックガイド、あるいは改善されたリファレンス情報が必要とされるケースがほとんどです。

例として、クッキーの焼き方に関する説明文書を作成する作業を考えてみましょう。

チュートリアル¶

チュートリアルとは、特に初心者を対象とした入門ガイドであり、読者をゼロの状態から完成品まで導くことを目的とします。そのためには、非常に具体的な手順と、各ステップの背景を説明する詳細な解説が必要です。説明対象のツールに関する読者の知識は一切前提とせず、ただし基本的なPythonの習熟度はある程度想定しても差し支えありません。

チュートリアルには、読者が説明された内容を正しく実行できたことを確認できる定期的なチェックポイントを含めるべきである。各チェックポイントでは、成功基準を明確に示す必要がある。既知の失敗事例を明確に記述し、読者が遭遇する可能性のあるエラーや問題の説明を含めること。読者の操作によって変化する要素は、たとえ自明に思えるものであっても指摘すべきである。特にベストプラクティスや共通プロセスを確立しようとする場合は、繰り返しを推奨します。内部構造の説明や、同じ結果に至る代替手順は避けるべきです。

クッキーの焼き方チュートリアルは単なるレシピ以上のものです。チュートリアルの手順は、これまで一度も焼いたことがない人（例えば子供）にも理解できるものでなければならず、経験豊富なベーカーが当然と思うようなこと——砂糖とバターをクリーム状に混ぜる方法、オーブンの予熱プロセス、クッキーを食べる前にどれくらい冷ますべきかなど——も説明する必要があります。チュートリアルの目的はクッキーを作ることではなく、焼き菓子の基本を伝えることです。出来上がったクッキーこそが、そもそもチュートリアルに挑戦する動機となる美味しいご褒美なのです。

ハウツーガイド¶

ハウツーガイドは、理論的な説明ではなく、特定の現実的な使用事例と実践的な成果に焦点を当てるべきです。チュートリアルとは異なり、既存のツールに関する一定の知識があることを前提とできます。読者はガイドを最初から最後まで追って目標に到達できるべきですが、そのためには既存の知識が必要な場合があります。ガイドの目標を達成するために従うべき具体的な手順や論理的なステップのセットを含めるべきです。

料理本のレシピは、ハウツーガイドの良い例です。チョコチップクッキーのレシピは数多く存在し、それらは共通の特徴を共有していますが、特定のレシピは最初から最後まで確実に実行可能であり、一貫した結果をもたらす必要があります。優れたチョコチップクッキーのレシピは、砂糖や小麦粉の種類ごとの相対的な利点について脱線したり、基本的な技術や工程について詳細な指示を与えたりすることはありません。読者がベーキングの基本的な知識を持っていることを前提に、クッキーを焼くための材料と手順のみを記載するものです。

トピックガイド¶

トピックガイドは単一の主題や概念を説明します。サンプルコードや手順を含めることもありますが、全体的な概念の概要を提示することに重点が置かれます。意見や異なる視点を含めることもありますが、ガイドの特定のトピックに焦点を当て続ける必要があります。

クッキーの焼き方に関するトピックガイドでは、焼き菓子としてのクッキーの歴史を掘り下げたり、工業化プロセスが手作りクッキーと異なる種類のクッキーを生み出す仕組みを探ったり、クッキーをバランスの取れた食事に取り入れる方法を提案したりするかもしれません。クッキーを焼きたい場合にそのまま従うにはあまり有用な資料とは言えませんが、焼き菓子に詳しい人が既存のクッキーレシピをうまくアレンジするための背景知識を提供することはできるでしょう。

参照¶

リファレンスドキュメントは情報指向であり、ツールライブラリの動作の詳細を記述する。コード自体から生成されることも多いが、優れたAPIドキュメントには追加の説明や文脈が必要となる場合がある。使用例を含むこともあるが、詳細な説明は避けるべきである。

製菓の参考ガイドでは、使用可能な砂糖の種類や、製菓におけるそれらの特性を詳細に説明することがある。砂糖に関する事実を記述するが、砂糖の種類を選ぶ際のより広範な議論は、ハウツーガイドやトピックガイドの主題となるべきである。ほとんどの包装食品に記載されている栄養情報は、参考資料と見なされる。

ドキュメントスタイル¶

BeeWare's documentation follows the guidelines outlined in the documentation style guide. This guide includes basic style and formatting, and the process for the spelling check. It also covers various Markdown syntax details, such as reference link syntax, tips for working with code blocks, and image handling.

貢献ドキュメント¶

新しいドキュメントの提案

BeeWareの改善案をお持ちですか？そのアイデアをどのように提案すれば検討してもらえますか？

調査を行ってください¶

最初のステップは、BeeWareの課題トラッカーで既存の機能課題（「enhancement」タグ付き）、ドキュメント課題（「documentation」タグ付き）、またはディスカッションスレッドを検索し、そのアイデアが以前に提案されていないか確認することです。既に存在する場合、新たな情報またはアイデアを追加できる場合は、既存のスレッドにそれらを含めてください。調査の支援が必要な場合は、BeeWare Discordの#devチャンネルでお尋ねください。既存スレッドの方向性を示したり、ご存知ないかもしれない背景情報を提供したり、一見関連性がないと思われる別のアイデアとあなたのアイデアを結びつけることができるかもしれません。

その考えについて話し合う¶

既存のアイデアに関する参照が見つからない場合は、ディスカッションスレッドを開始してください。アイデアの目的とユースケースについて概要を説明してください。実装された場合の機能の外観に関する考え（APIの一般的な形状、機能の視覚的表現、追加されるドキュメントなど）も記載してください。該当する場合は、アイデアが異なるプラットフォームでどのように実現されるかについての調査結果も記載してください。

ディスカッションスレッドが開設されると、BeeWareチームとコミュニティの他のメンバーが対応します。コアチームは、ご提案いただいたアイデアについて、少なくとも2営業日以内に最初の印象を提供することを目指します。アイデアが特に複雑な場合、より詳細な分析には最大1週間かかる可能性があります。休日やカンファレンスなどのイベントにより、これらのスケジュールが若干遅れる場合があります。

これはあなたのアイデアについて議論に参加する機会です。詳細や背景情報の提供をお願いする場合があります。コミュニティの他のメンバーも議論に加わり、異なる視点や提案、対案を提示することがあります。この議論の結果が今後の進め方を決定します。

すべてのアイデアが受け入れられるわけではないことを理解することが重要です。このプロセスが提案から始まるのは、変更が受け入れられない理由があるのに気づくまで、すべての作業を無駄にさせないためです。

これは良いアイデアではなかったという意味ではありません！技術的な理由で実装できない場合もあるのです。例えば、次のような理由でアイデアを却下する可能性があります：

すべてのサポート対象プラットフォームで確実に実装することは困難、あるいは不可能である；または
維持が困難であるか、あるいはその維持には広く普及していない技術やソフトウェアへのアクセスが必要となる。
特定のユーザー層にサービスを提供するが、他のユーザーに大きな負担を強いる。

もしあなたのアイデアが適切でないと判断した場合でも、必ずしもそのアイデアを諦める必要はありません。特定のアイデアを却下する一方で、プラグインインターフェースやその他の拡張ポイントを追加することで、同じ機能を外部ライブラリとして維持できるようにする案には、はるかに柔軟に対応できる可能性があります。そうすれば、その機能自体は維持しつつ、特定のメンテナンス上の懸念や、機能がプロジェクト自体の制約となるような制限を回避できるのです。

正式な機能リクエストに変換する¶

機能の形式について議論が合意に達したら、beeware課題管理システムで新しい機能リクエスト課題を作成し、議論を要約するとともに、背景説明として議論へのリンクを記載してください。

ご自身の機能提案を必ずしもご自身で実装する必要はありません。提案内容の詳細を記載したイシューを開くことができます。ただし、単にイシューを投稿したからといって、それが必ず実装されるわけではありません。同じ機能に関心を持つ他のコミュニティメンバーやコアチームメンバーが取り上げてくれる可能性を待つ必要があります。ただし、それが必ず実現する保証はありません。確実に実装したい場合は、ご自身で実装するか、他の人に実装を依頼する必要があります。

開発環境を構築する

BeeWareへの貢献には、開発環境のセットアップが必要です。

前提条件¶

以下の前提条件をインストールする必要があります。

macOSLinuxWindows

BeeWare は Python 3.10+ が必要です。また、仮想環境を管理する手法（例：venv）も必要です。

インストール済みのPythonのバージョンを確認するには、次のコマンドを実行します：

$ python3 --version

複数のPythonバージョンがインストールされている場合、python3を特定のバージョン番号（例：python3.13）に置き換える必要がある場合があります。

最近リリースされたバージョンのPython（例：3.14.0のような「.0」または「.1」のマイナーバージョン番号を持つバージョン）の使用は避けることを推奨します。これは、macOS上でPythonをサポートするために必要なツールが、通常、最近リリースされた安定版のPythonバージョンでは利用できない場合が多いからです。

BeeWare は Python 3.10+ が必要です。また、仮想環境を管理する手法（例：venv）も必要です。

インストール済みのPythonのバージョンを確認するには、次のコマンドを実行します：

$ python3 --version

複数のPythonバージョンがインストールされている場合、python3を特定のバージョン番号（例：python3.13）に置き換える必要がある場合があります。

Pythonの最近リリースされたバージョン（例：3.14.0のような「.0」または「.1」のマイナーバージョン番号を持つバージョン）の使用は避けることを推奨します。これは、Linux上でPythonをサポートするために必要なツールが、通常、最近リリースされた安定版Pythonバージョンでは利用できない場合が多いからです。

BeeWare は Python 3.10+ が必要です。また、仮想環境を管理する手法（例：venv）も必要です。

インストール済みのPythonのバージョンを確認するには、次のコマンドを実行します：

C:\...>py -3 --version

複数のバージョンのPythonがインストールされている場合、-3を特定のバージョン番号（例：-python3.13）に置き換える必要がある場合があります。

Pythonの最近リリースされたバージョン（例：3.14.0のような「.0」または「.1」のマイナーバージョン番号を持つバージョン）の使用は避けることを推奨します。これは、Windows上でPythonをサポートするために必要なツールが、通常、最近リリースされた安定版Pythonバージョンでは利用できない場合が多いからです。

開発環境を設定する¶

BeeWareの開発環境を設定する推奨方法は、仮想環境を使用し、その後BeeWareの開発版とその依存関係をインストールすることです。

BeeWare リポジトリをクローンする¶

次に、GitHub上のBeeWareページに移動し、まだ行っていない場合は、リポジトリをフォークして自分のアカウントに追加してください。次に、フォークしたリポジトリの「<> コード」ボタンをクリックします。お使いのコンピュータにGitHubデスクトップアプリケーションがインストールされている場合は、「GitHub Desktopで開く」を選択できます。そうでない場合は、表示されたHTTPS URLをコピーし、コマンドラインを使用してリポジトリをコンピュータにクローンします：

macOSLinuxWindows

BeeWare リポジトリをフォークし、その後：

$ git clone https://github.com/<your username>/beeware.git

(あなたのGitHubユーザー名をここに置き換えてください)

BeeWare リポジトリをフォークし、その後：

$ git clone https://github.com/<your username>/beeware.git

(あなたのGitHubユーザー名をここに置き換えてください)

BeeWare リポジトリをフォークし、その後：

C:\...>git clone https://github.com/<your username>/beeware.git

(あなたのGitHubユーザー名をここに置き換えてください)

仮想環境を作成する¶

仮想環境を設定し、pip をアップグレードするには、以下を実行してください：

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

プロンプトには現在、前に (.venv) プレフィックスが付いているはずです。

インストール BeeWare¶

ソースコードを入手したので、開発環境に(https://setuptools.pypa.io/en/latest/userguide/development_mode.html)を[編集可能なインストール]BeeWareできます。次のコマンドを実行してください：

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

コミット前の検証を有効にする¶

BeeWareでは、単純な問題の特定やコードフォーマットの標準化のためにpre-commitというツールを使用しています。これは、gitフックをインストールすることで実現され、gitコミットを確定する前に一連のコードリンターを自動的に実行します。pre-commitを有効にするには、以下を実行してください：

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

さあ、BeeWareのハッキングを始めましょう！

ブランチから作業する

変更作業を始める前に、必ずブランチを作成してください。デフォルトでは、リポジトリのフォークをクローンすると、main ブランチがチェックアウトされます。これは BeeWare の main ブランチの直接コピーです。

main ブランチからプルリクエストを送信することは可能ですが、そうしない方が望ましいです。ほぼ正しいプルリクエストを送信した場合、レビュー担当のコアチームメンバーは、小さな変更を求めるフィードバックを与える代わりに、必要な修正を加えられる可能性があります。しかし、main ブランチからプルリクエストを送信すると、レビュー担当者は修正を加えられなくなります。

メインブランチで作業すると、最初のプルリクエストを完了した後のあなた自身にとっても困難になります。2つ目のプルリクエストに取り組む場合、2つ目の貢献の基盤となるアップストリームプロジェクトのメインブランチの「クリーンな」コピーが必要になります。最初の貢献をmainブランチから行った場合、そのクリーンなバージョンはもはや利用できません。

Instead, you should make your changes on a feature branch. A feature branch has a simple name to identify the change that you've made. For example, if you're fixing a bug that causes build issues on Windows 11, you might create a feature branch fix-win11-build. If your bug relates to a specific issue that has been reported, it's also common to reference that issue number in the branch name (e.g., fix-1234).

fix-win11-build 機能ブランチを作成するには、次のコマンドを実行します:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

スコープクリープを避ける

スコープクリープとは、単一の貢献によって解決される問題や実装される機能のリストが、作業開始時に想定していた範囲を大幅に超えて膨張する現象を指す。単純な問題から着手し、密接に関連する問題を発見してその修正も追加し、さらに第三の問題が…気がつくと、5件の問題を解決し3つの新機能を追加するプルリクエストが完成している。そこには数十ものファイルが含まれているのだ。

スコープクリープは誰にでも起こり得る。経験豊富な開発者にとってはおなじみの概念であり、誰もが何度も経験し、それに伴うあらゆる問題に直面してきた。

スコープクリープを避けるべき非常に現実的な理由があります。貢献が大きくなるほど、扱いが難しくなります。エッジケースや潜在的な問題を特定するのが困難になり、貢献の全体的な品質が低下する可能性があります。また、レビュアーが複数の、おそらく関連性のないコンテキストを扱う必要がある場合、レビュー作業もより困難になります。貢献が大きくなるほどレビューコメントも増え、貢献者として複数のレビュースレッドを追うのが難しくなる可能性があります。GitHubの操作体験さえも損なわれます——プルリクエストのサイズが大きくなるにつれてGitHubのUIは遅くなり、GitHubインターフェースを通じてファイルをナビゲートしたりレビューコメントを残そうとしたりすることが次第に困難になるのです。

貢献内容に、元の提案やバグ報告に明示的に含まれていない要素を追加する理由を見つけた場合は、スコープクリープに陥っていないか検討すべきです。別々に実装可能な2つの独立した機能はありませんか？既知の制限やバグを抱えた状態で機能を実装し、後続のプルリクエストでそのバグを修正することは可能ですか？バグ修正の一部は他の部分と独立していませんか？変更の一部を省略しても元の貢献内容が変わらない場合、おそらく省略すべきです。

ソフトウェア開発は常に段階的な改善のプロセスです。個々の貢献はマージの結果としてコードベースをより良い状態にすべきですが、バグや機能の一部を将来の改善課題として残すことは全く問題ありません。そのためにはプルリクエストを独立してレビュー可能な複数の部分に分割したり、誰かが調査・解決できるよう問題を記録したりすることが考えられます。

各投稿の範囲を限定することは、関係者全員、あなた自身も含めて有益です。査読者も、そしてあなた自身も、そのことを高く評価するでしょう。

建築文書

BeeWareのドキュメントに変更を加える前に、既存のドキュメントをビルドできることを確認しておくことが有用です。

Python 3.13 インタプリタがインストールされ、パス上で利用可能であることが必須です（つまり、python3.13 は Python 3.13 インタプリタを起動する必要があります）。

BeeWare はドキュメント作成に tox を使用します。以下の tox コマンドは、プロジェクトのルートディレクトリにある tox.ini ファイルと同じ場所から実行する必要があります。

ライブドキュメントプレビュー¶

ドキュメントの迅速な編集をサポートするため、BeeWareには「ライブプレビュー」モードが備わっています。

ライブプレビューは警告付きでビルドされます！

ライブサーブはドキュメント更新の反復作業に利用可能です。更新作業中にマークアップの問題が発生する可能性があります。WARNINGで囲まれた問題は標準ビルドを失敗させますが、ライブサーブはコンソール出力に警告を表示しつつビルドを継続するよう設定されています。これにより、ライブプレビューを再起動せずに反復作業が可能です。

WARNING は ERROR とは異なります。ERROR とみなされる問題が発生した場合、ライブサーバーは失敗し、再起動が必要となります。WARNING の問題が解決されるまで、サーバーは再起動しません。

ライブサーバーを起動するには：

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

これにより、ドキュメントがビルドされ、ドキュメントを提供するWebサーバーが起動され、ドキュメントソースの変更をファイルシステムで監視します。

サーバーが起動すると、コンソール出力に以下のような内容が表示されます：

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

ブラウザを開き、提供されたURLにアクセスしてください。これでドキュメントの反復作業を開始できます。変更が検出されると、ドキュメントが再構築され、変更されたページを表示しているブラウザは自動的に更新されます。

docs-liveは最初のステップです

docs-liveを実行してライブサーバーと連携するのは初期段階の反復作業を目的としています。プルリクエストを送信する前には必ずローカルビルドを実行してください。

ローカルビルド¶

反復処理が完了したら、ドキュメントのローカルビルドを実行する必要があります。このビルドプロセスは、マークアップに問題がある場合に失敗するよう設計されています。これにより、ライブサーバーでは見逃していた可能性のある問題を検出できます。

ローカルビルドの生成¶

ローカルビルドを生成するには：

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

このビルドの出力は、プロジェクトのルートディレクトリにある _build ディレクトリに配置されます。

ローカル翻訳ビルドの生成¶

BeeWare'sのドキュメントは複数言語に翻訳されています。英語版ドキュメントの更新は、他の言語版ビルドに問題を引き起こす可能性があります。プルリクエストを送信する前に、すべてのビルドが正常に動作することを確認することが重要です。

利用可能なすべての翻訳のビルドを生成するには：

macOSLinuxWindows

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

各言語ビルドの出力は、関連付けられた_build/html/<languagecode>ディレクトリに配置されます。ここで<languagecode>は、特定の言語に関連付けられた2文字または5文字の言語コードです（例：フランス語はfr、イタリア語はitなど）。

単一のビルドに問題が見つかった場合、tox -e docs-<languagecode> を実行することでその個別のビルドを単独で実行できます。例えば、フランス語のドキュメントのみをビルドするには、以下を実行します：

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

単一言語ビルドの出力は _build ディレクトリに配置されます。

ドキュメントのリンティング¶

ビルドプロセスではMarkdownの問題を検出しますが、BeeWareはスタイルや書式に関する追加チェック（いわゆる「リンティング」）を実行します。リンティングチェックを実行するには：

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

これにより、ドキュメントに以下の内容が含まれていないことが検証されます：

無効なハイパーリンク
誤字

単語の正しい綴りが誤りとして検出された場合、その単語をdocs/spelling_wordlist内のリストに追加してください。これにより、その単語がスペルチェッカーの辞書に追加されます。このリストに追加する際は、以下の点に注意してください：

米国式スペルを優先しますが、プログラミング特有の慣用表現（例：「apps」）や名詞の動詞化（例：「scrollable」）については一部例外を認めます。
製品名への言及は、製品が推奨する大文字表記を使用してください（例：「macOS」、「GTK」、「pytest」、「Pygame」、「PyScript」）。
ある用語が「暗号として」使用されている場合、辞書に追加するのではなく、リテラル（like this）として引用すべきである。

ドキュメントの作成

BeeWareへのドキュメント貢献を書くための手順は以下の通りです。

既存のドキュメントの更新¶

既存のドキュメントを編集する場合は、/docs/enディレクトリ内のファイルを特定する必要があります。ファイル構造はページ構造に準拠しているため、ドキュメントURLからファイルを特定できます。

新しいドキュメントの追加¶

新しいドキュメントを追加する場合は、さらにいくつかの手順が必要です。

docs/enディレクトリ内の適切な場所にドキュメントを作成する必要があります。説明のため、ファイル名new_doc.mdの新しいドキュメントを追加すると仮定します。

次に、新しいファイルを含めるためにdocs/en/SUMMARY.mdファイルを更新する必要があります。SUMMARY.mdは基本的にdocs/enディレクトリ構造を反映するように構成されていますが、より重要なのは左サイドバーの構造を直接決定する点です。new_doc.mdを含めたいセクションを見つけたら、ワイルドカードパスが記載されている場合はSUMMARY.md内で何も変更する必要はありません。例：

- ./path/to/directory/*

new_doc.mdを含めようとするセクションが個別のMarkdownリンクのリストである場合、明示的なリンクを追加する必要があります。例：

- [My new document](new_doc.md)

ドキュメントの作成¶

目的のファイルをエディタで開いて、書き始めることができます。

BeeWareのドキュメント作成に関するガイドラインをまとめたドキュメントスタイルガイドを用意しています。

変更メモを追加する

多くのBeeWareツールでは、各リリースのリリースノート作成を支援するためにtowncrierを使用しています。該当するツールのいずれかにプルリクエストを送信する際には、変更ノートを含める必要があります。この変更ノートは、行われた変更を説明するリリースノートの項目となります。

すべてのプルリクエストには、changes/ディレクトリ内に少なくとも1つのファイルを含める必要があります。このファイルには、プルリクエストで実装された変更内容の簡潔な説明を記載してください。変更ノートはMarkdown形式で、<id>.<fragment type>.mdという形式の名前を持つファイルに記述します。提案する変更が既存の課題番号を持つバグ修正または機能実装である場合、IDはそのチケット番号となります。変更に対応するイシューが存在しない場合、プルリクエスト番号をIDとして使用できます。このプルリクエスト番号はプルリクエストをプッシュするまで確認できません。そのため、最初のCIパスではtowncrierチェックが失敗します。変更ノートを追加し、プルリクエストを更新してプッシュすると、CIは通過するはずです。

断片タイプは5種類あります：

feature: このプルリクエストは、以前には不可能だった新しい動作や機能を追加します（例：新しいパッケージング形式のサポート追加、または既存のパッケージング形式における新機能の追加）。
bugfix: このPRは既存の実装におけるバグを修正します；
PRはドキュメントの大幅な改善です；
removal; このPRはBeeWare APIにおける後方互換性のない変更を表しています; または
misc; リリースノートで発表する必要のない、軽微な変更または管理上の変更（例：誤字の修正、言語の軽微な明確化、依存関係のバージョン更新など）。

この変更ノートの説明は、ユーザー視点からの変更内容に関する高レベルの「マーケティング」要約であるべきであり、深い技術的説明や実装の詳細ではない。これはコミットメッセージとは異なる。コミットメッセージは、将来の開発者が変更の理由を追跡できるように、何が行われたかを記述するものである。一方、変更ノートは内部知識を持たない可能性のあるユーザーのために記述される説明である。

たとえば、プロジェクトの命名に関するバグを修正した場合、コミットメッセージは次のように記述できます：

プロジェクト名が数字で始まることを禁止するため、より強力な正規表現チェックを適用する。

対応する変更ノートは次のような内容になります：

プロジェクト名は数字で始まることはできなくなりました。

一部のプルリクエストでは、複数の機能導入やバグ修正、あるいは複数の後方互換性のない変更が行われる場合があります。その場合、PRには複数の変更ノートファイルが存在する可能性があります。同じIDを持つ2つのフラグメントタイプを関連付ける必要がある場合は、数値のサフィックスを追加できます。例えば、PR 789がチケット123で説明される機能を追加し、チケット234で説明されるバグを修正し、さらに2つの後方互換性のない変更を行った場合、4つの変更ノートファイルが存在することになります：

123.feature.md
234.bugfix.md
789.removal.1.md
789.removal.2.md

towncrierおよびフラグメントタイプの詳細については、ニュースフラグメントを参照してください。また、changesリポジトリのBeeWareディレクトリ内に既存のニュースフラグメントの例があります。このフォルダが空の場合、BeeWare が最近新バージョンをリリースしたためと考えられます。変更履歴ファイルは削除され、各リリースごとにリリースノートの更新に統合されます。必要なコメントのスタイルを確認するにはそのファイルを参照してください。変更ノートのフォーマット方法については、最近マージされたプルリクエストを参照してください。

プルリクエストを送信する

すべての変更をコミットしたところで、プルリクエストを送信する準備が整いました。スムーズなレビュープロセスを確保するため、いくつかの手順を踏む必要があります。

プレコミットとの連携¶

変更をコミットする際、pre-commitが自動的に実行されます。コミットに問題が検出された場合、コミットは失敗します。可能な限り、pre-commitは検出した問題を修正するために必要な変更を加えます。以下の例では、ruffチェックによってコードのフォーマット問題が検出されました：

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

この場合、ruffによって問題が自動的に修正されました。したがって、プリコミットチェックの結果変更されたファイルを再度追加し、変更を再コミットできます。ただし、一部のチェックでは手動での修正が必要になる場合があります。それらの変更を加えた後は、変更されたファイルを再度追加し、再コミットしてください。

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

すべてが完了すると、コミットが確定したことを示すメッセージが表示され、git log でそのコミットが最新の追加として確認できます。これで GitHub へのプッシュ準備が整いました。

変更を GitHub にプッシュし、プルリクエストを作成してください¶

GitHubに初めてプッシュすると、新しいプルリクエストを作成するためのGitHubページに直接移動するURLが提供されます。そのURLにアクセスしてプルリクエストを作成してください。

以下は、URLが強調表示された状態でpushに表示される内容の例です。

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

現在のブランチを以前にGitHubにプッシュしたことがある場合、URLは再度送信されません。ただし、PR作成URLにアクセスする他の方法があります：

アップストリームリポジトリに移動し、「プルリクエスト」をクリックした後、「新しいプルリクエスト」を選択し、プルリクエストを送信したいブランチを選択してください。
最近プッシュした場合は、アップストリームリポジトリに移動し、ファイル一覧の上部に表示される「最近プッシュがあった」ことを示すバナーを見つけ、「比較してプルリクエスト」ボタンをクリックしてください。
GitHub CLI gh pr create コマンドを使用し、プロンプトに従って入力してください。
GitHub CLI gh pr create --web コマンドを使用して、PR作成ページにウェブブラウザを開きます。

これらのいずれかのオプションを選択することで、新しいプルリクエストを作成できます。

GitHub CLI: gh

GitHubはGitHub CLIを提供しており、これによりターミナルからghコマンドを通じてGitHubの多くの機能にアクセスできます。すべての機能についてはGitHub CLIドキュメントを参照してください。

プルリクエストの内容¶

プルリクエストのタイトルは、情報豊富で明確かつ簡潔である必要があります。可能な限り短く保つよう心がけましょう。ただし、必要に応じて長いタイトルも許容されます。優れたPRタイトルは、文脈を知らない人でも、そのPRでどのバグ修正や機能が実装されているかを十分に理解できるものでなければなりません。

プルリクエストの説明文は、PRの変更内容を明確に反映しなければなりません。文脈を知らない人が説明文を読んだだけで、変更の理由を比較的完全に理解できる必要があります。冗談、慣用句、口語表現、および大文字のみの使用や過剰な句読点といった不要な書式設定は避けてください。これはPRで何が起こっているかを率直に説明するものであり、こうした要素を排除することで説明文の理解しやすさが向上します。

PRに既に含まれていない再現ケースやテスト手順がある場合は、それらを説明しPRに含める必要があります。説明には、それらの実行方法と、望ましい結果を再現するための手順を含めるべきです。

プルリクエストが issue #1234 を解決する場合、プルリクエストの説明に Fixes #1234 というテキストを含める必要があります。これにより、プルリクエストがマージされると自動的に issue が閉じられます。他のディスカッション、issue、プルリクエストも同様の #1234 構文で参照できます。異なるリポジトリの issue を参照するには、番号の前に - を付加します。例えば python/cpython#1234 は CPython リポジトリの issue 1234 を指します。

継続的インテグレーション¶

継続的インテグレーション（CI）とは、プルリクエストに対して自動化されたチェックを実行するプロセスです。これには、コードが正しくフォーマットされていることを確認するといった単純なチェックが含まれますが、テストスイートの実行やドキュメントのビルドも含まれます。

CIの失敗を引き起こす変更は数多く存在します。大まかに言えば、CIを通過していないプルリクエストはレビューしません。プルリクエストを作成してCIが失敗した場合、通過するまでレビューを開始しません。変更が失敗の原因となった場合、その理由を調査し問題を解決するのはあなたの責任です。

CIが失敗した場合、失敗したリンクはPRページの下部、「一部のチェックが成功しませんでした」という見出しの下に表示されます。失敗したチェックの一覧が表示され、合格したチェックがある場合でも、この失敗チェックは全チェックリストの最上部に表示されます。失敗リンクをクリックするとログが表示されます。ログには失敗の原因を特定するために必要な情報がほぼ全て記載されています。ログを読み込み、失敗の原因を特定した上で、必要な対応を行ってください。

時折、CIチェックが変更内容とは無関係な理由で失敗することがあります。これはCIチェックを実行するマシン側の問題、あるいはCIチェック自体が不安定であることが原因です。失敗を確認し、それが変更内容と無関係であると確信できる場合は、その旨をプルリクエストにコメントとして追加してください。調査いたします。

新しいCI実行をトリガーするには、ブランチに新しい変更をプッシュする必要があります。

CIを通過させるのに助けが必要な状況に陥った場合は、プルリクエストにコメントを残してその旨をお知らせください。できる限りのサポートをいたします。

pre-commit および towncrier チェック

pre-commit または towncrier のいずれかのチェックが失敗した場合、残りのほとんどの CI チェックの実行がブロックされます。チェックの全セットを実行するには、該当する問題を解決する必要があります。

CIリソースには限りがあります。ブランチにプッシュするたびにCIが開始されることを理解することが重要です。複数の変更を加える場合は、ローカルで変更を加え、まとめてプッシュすることをお勧めします。CIはバッチ内の最新コミットのみを実行するため、CIシステムへの負荷を最小限に抑えられます。

PRの提出プロセスは、CIを通過するか、または通過しない理由を説明できるまで完了しません。