個人のPythonプロジェクトをリリース可能なライブラリに変える

私はプログラマーというよりは学者であり、研究をサポートするために、私自身が使用するPythonプログラムを長年書いています。私の最新のプロジェクトは、私だけでなく他の多くの人にとっても有用である可能性が高く、オープンソースのPythonライブラリとしてリリースすることを考えています。

ただし、機能している個人プロジェクトから、他の人が簡単にインストールして使用できるライブラリに移行するには、かなりのハードルがあるようです。この質問は、パブリックリリースに向けて作業を開始するために最初に実行する必要がある手順に関するものです。

現在、ライブラリとライブラリ自体を使用するコードを含む単一のgitリポジトリがあり、何かが壊れた場合に備えてgitを緊急の元に戻すボタンとして使用しています。これはすべて単一のユーザーには問題なく機能しますが、リリースしたい場合は明らかに適切ではありません。最後にしたいのは、ライブラリが別のリポジトリにあり、他の人がを使用してインストールできpip、安定したAPIがあることです。

setuptoolsなどを使用することを学習するのは、一度公開したいと思ったらそれほど難しいことではないでしょう。私の問題は、そのポイントに到達するためにどのように作業すべきかを知ることです。

だから私の質問は、公共の消費のためにPythonライブラリプロジェクトの準備を始めるためにとるべき最初のステップは何ですか？ライブラリの公開に向けて作業を開始するには、ディレクトリ構造、gitリポジトリなどをどのように再編成すればよいですか？

より一般的には、これを初めて試すときに役立つと知られているリソースがある場合、非常に役立ちます。ベストプラクティスや回避すべき間違いなどへのポインタも非常に役立ちます。

いくつかの明確化：現在の回答は、「Pythonライブラリを他の人が使用できるようにするにはどうすればよいですか？」という行に沿った質問に対処しています。これは便利ですが、私が尋ねるつもりの質問とは異なります。

私は現在、プロジェクトのリリースに向けて長い旅の始まりにいます。私の実装の中核は機能します（そして非常にうまく機能します）が、先の作業量に圧倒されており、プロセスをナビゲートする方法についてのガイダンスを探しています。例えば：

• 現在、私のライブラリコードは、それを使用する独自のドメイン固有のコードに結合されています。サブフォルダーに存在し、同じgitリポジトリーを共有します。最終的には、スタンドアロンのライブラリにして独自のリポジトリに配置する必要がありますが、その方法がわからないため、これを先延ばしにしています。（ライブラリを「開発モード」でインストールして編集できるようにする方法も、2つのgitリポジトリを同期させる方法もありません。）

• 私のドキュメント文字列は簡潔です。最終的にはSphinxまたは他のツールを使用する必要があることを知っているからです。しかし、これらのツールは学ぶのが簡単ではないようですので、これは主要なサブプロジェクトになります。

• ある時点で、setuptoolsまたは他のツールを使用してパッケージ化し、依存関係を追跡する方法を学ぶ必要がありますが、これは非常に複雑です。今すぐこれを行う必要があるかどうかはわかりませんが、ドキュメントは新しいユーザーにとって絶対的な迷路なので、後で行うことを決め続けています。

• 体系的なテストを行う必要はありませんでしたが、このプロジェクトには間違いなく取り組むので、（i）自分のプロジェクトに適した方法論を知るためにテストについて十分に学ぶ必要があります。（ii）選択した方法論で利用可能なツールを学習します。（iii）選択したツールの使用方法を学ぶ。（iv）プロジェクトにテストスイートなどを実装します。これはそれ自体がプロジェクトです。

• 他にもやらなければならないことがあるかもしれません。たとえば、jonrsharpeは、git-flow、tox、TravisCI、virtualenv、CookieCutterについての役立つリンクを投稿しました。（投稿は2013年からのものであるため、現在どれだけ残っているかを調べるためにいくつかの作業を行う必要があります。）

これをすべてまとめると、膨大な量の作業が必要になりますが、プラグインを続けて行けば、すべてを完了することができると確信しており、急いでいません。私の問題は、それを1つずつ実行できる管理可能な手順に分解する方法を知ることです。

言い換えれば、最終的にリリース可能な製品に到達するために、私が今取ることができる最も重要な具体的なステップはどれかを尋ねています。週末が空いている場合、これらのうちどれに焦点を当てるべきですか？他の作業とは別に（もしあれば）どの作業を行うことができますか？これらのことを学習する最も効率的な方法は何ですか？それで、プロジェクト自体に集中する時間を確保できますか？（これは基本的に趣味のプロジェクトであり、私の仕事ではないことを心に留めておいてください。）実際に行う必要のないことはありますか？したがって、膨大な時間と労力を節約できますか？

すべての回答は大歓迎ですが、これらのプロジェクト管理の側面に焦点を当てた回答、特に現代のPython開発に特に関連した回答を歓迎します。

ライブラリを使用する場合、必要ですが、setup.pyを追加することは最も重要なステップではありません。さらに重要なことは、ドキュメントを追加し、ライブラリを宣伝することです。2番目の点はライブラリに大きく依存しているため、ドキュメントの側面に焦点を当てましょう。

1. ライブラリに関するすべてを知っています。そして、これには問題があります。インストール方法と使用方法はすでに知っているので、多くのことは直感的であるか、または明白に思えるかもしれません。残念ながら、同じことは、ユーザーにとって直観的ではなく、明白でもないかもしれません。あなたがそれについて何も知らないかのようにあなたのライブラリを見てみてください、そしてより重要なことには、他の人にそれを使用するように頼み、彼らが持っていたすべての困難を見つけようとしてください。

2. あなたの図書館が何であるかについて、わかりやすい英語で説明してください。多くのライブラリは、誰もがそれらについて知っていると仮定しています。そうでない場合は、ライブラリの目的を把握するのが難しい場合があります。

3. 詳細な技術文書を作成しますが、ライブラリでいくつかのタスクを実行する方法を示す短いコードも忘れないでください。ほとんどの開発者は急いでおり、基本的なことを行う方法を理解しようとして何時間も費やす必要がある場合、他のライブラリに切り替える傾向があります。

4. 連絡先情報を含めてください。あなたのライブラリが成功した場合（そして、私自身の経験から、これはかなり未知のライブラリにも当てはまることが示されています）、人々はそれで問題に直面します：バグか、単にその一部を理解または使用するのが困難です。ライブラリを改善するためにフィードバックを受け取ると便利なことがよくあります。問題を報告したすべての人に対して、問題に遭遇したときに別のライブラリに切り替えることを好む人が何百人もいる可能性があります。

それに加えて：

1. ライブラリがPython 2または3、あるいはその両方で動作するかどうかを明確にしてください。

2. ライブラリがWindowsで動作しない場合は、そう言います。

3. 必ず公式の規則を使用してください（pep8を使用して確認してください）。そうでない場合は、明確に説明するか修正してください。

4. エッジケースの取り扱いに注意してください。間違ったタイプまたはサポートされていない値でライブラリが呼び出された場合、それは平易な英語で正確に何が間違っているかを言う必要があります。すべきではないことは、スタックの10レベル下で不可解な例外を発生させ、ユーザーに何が問題なのかを理解させることです。

長年にわたって成熟したライブラリよりもかなり少ないライブラリを使用してきたため、重要なアドバイスは、展開ツールを選択したら、次のことを実行することです。

ライブラリの依存関係を特定します。

ドケットコンテナまたはVMのいずれかのクリーンな環境への展開を試みます。多くの場合、問題を引き起こす個人環境について独特な何かがあるため、このステップは重要だと考えています。

将来、誰がライブラリを保守するのかを考えてください。誰かのペットプロジェクトであるライブラリを3、4年間見かけ、それを最新の状態に保つために必要な更新を取得しないライブラリに遭遇することほどイライラすることはありません。

あなたまたはあなたのチームが、ライブラリのテストと文書化を継続することを約束するかどうかを検討してください（ユニットテストとCIパイプラインは、ここから方程式の一部になり始めます）。

おそらく、あなたの分野で成熟したOSSプロジェクトを見つけて、そのプロジェクトにコードを提供できますか？次のようないくつかの利点があります。

• 貢献度を最大化できます。実際、多くの「趣味」のOSSプロジェクトは潜在的に価値がありますが、コミュニティではほとんど使用されていません（@ReaddyEddyの回答を参照）。最初にプロジェクトを最初からスクラッチするようにしてから、それを維持し、宣伝し、適切な例やドキュメントを提供するなど、多くの努力が必要です。
• あなたが言及した技術的な問題の多くは、成熟したプロジェクトですでに解決されています。
• ライブラリがOSSプロジェクトに価値を加える場合、その貢献者はコードをプロジェクト標準に引き上げるのを助けることができます。したがって、労力を節約し、経験を積むことができます。また、Sphinx、TravisCI、CookieCutter、およびその他の技術的側面に関する具体的な回答も得られます。

あなたが好きでおそらく使用している関連するOSSプロジェクトがある場合、問題やプルリクエストを開いたり、メンテナーと連絡を取ってみませんか？（開始する良い方法は、既存の問題を解決することです。）

2019年です。最新のツールから始めることを強くお勧めします。を必要としません。これsetup.pyはPythonコミュニティの人々が取り除きたいものであり、最終的にはそうなると信じています。

詩を試してください、あなたはそれを後悔しません。

これはあなたが尋ねている複雑な質問であり、私はArseniの答えに完全に同意します。適切なドキュメントは非常に重要な側面です。いくつかの簡単な手順でライブラリを立ち上げて実行できない場合は、すぐにドロップします（実際に試してみたいと思わない限り）。

あなたが間違いなく考慮するいくつかのこと

• ライブラリをバージョン管理する方法を考えてください。あるレベルへの後方互換性と、ルートに沿ったバグ修正も必要です。セマンティックバージョニングについて読む
• gitを比較的直線的な方法で使用しています（元に戻すため）。gitでの分岐に精通していますか。それは本当にそれほど難しくなく、人生を楽にします。枝に慣れたら。リポジトリに分岐モデルを適合させます。この分岐モデルの関連する部分を選択します。また、これを使用しているリポジトリのブランチと比較してください。
• ライセンス：ライブラリのライセンスを提供する必要があります。私はこの問題に関する法律専門家ではないため、これへのリンクのみを共有できます、共通ライセンス間の比較ます。この選択を軽視しないでください。
• バグトラッカー。そのユーザーがバグレポートを提供できるようにしたい。これにより、コードの品質を改善できます。解決するバグごとに、テストフレームワークにテストを追加します。これにより、将来バグが発生しないことが保証されます（回帰テスト）。バグ追跡システムは、機能のリクエストに使用できます。
• ユーザーの貢献。ユーザーの貢献が必要ですか？これがオープンソース製品で通常どのように機能するかはわかりませんが、ユーザーに機能ブランチの作成を許可できると想像できます。githubを介して、プルリクエストを介してこれを制御できるようです

Pythonに関連する経験はないので、その方向についてのヒントを提供することはできません。ただし、リモートリポジトリでの各コミットによってトリガーされるすべてのテストを自動化することは可能です（つまり、Jenkinsを使用）。ただし、これを延期することをお勧めします。事前の経験がなくても設定するのは大変な作業です。

これらは素晴らしい質問です。

リリース可能なライブラリに向けた重要な具体的な増分手順について：

• ライブラリになるファイルをプロジェクトの残りの部分から分離します。
  • ライブラリは独自のgitリポジトリに配置する必要がありますが、現在のリポジトリ内の別の最上位ディレクトリに配置するための便利な中間ステップであることがわかります。別のリポジトリにする場合は、プロジェクトの残りの部分に隣接して保存し../library、pipパッケージ化と開発モードの手順に進むまで経由して参照できるようにします。
  • プロジェクトの残りの部分からこのライブラリへのすべてのアクセスは、そのパブリックAPIを経由する必要があります。相互依存関係を解き明かすかもしれません。
• ライブラリのAPIを文書化するために、docstringを段階的に作成します。
  • 最終的にはドキュメンテーション文字列がドキュメントツールに送られますが、重要な作業は、APIを他の人に簡潔かつ十分に説明するテキストを書くことです。一度にすべてを一度に記入する方が簡単です。また、ラフなドラフトを作成し、後でより良い説明や例が思い浮かんだときに戻ってくると、はるかに良くなります。
  • APIの一部を文書化するのが難しい場合は、APIのその部分に改善の余地があるかどうかを尋ねてください。もっと簡単にできますか？もっとレギュラー？一般的すぎますか？専門的すぎる？もっと身近な名前を使用できますか？
  • docstringsは、ツールがチェックできる構造化されたコメントを使用して、引数タイプを文書化できます。私はまだそれに関する本当のドキュメントを見つけていませんが、PyCharm IDEはそれらのdocstringsを構築するのを助け、メソッド呼び出しを編集しながらすぐに引数の型をチェックします。
  • そういえば、PyCharmは開発者の時間を節約し、コード品質を改善するための素晴らしいツールです。「検査」を実行して、編集中にコードをチェックします。可能な場合はタイプをチェックし、欠落および未使用のインポートをチェックし、メソッドを複製し、PEP 8スタイルのミスなどをチェックします。
• を使用して単体テストの作成を開始します pytestます。リリースを行うずっと前に、ユニットテストは、コーナーケースのバグを発見し、コードの変更が物事を壊さないという自信を提供することで、あなた自身の開発で成果を上げます。繰り返しますが、時間の経過とともにこれを構築できます。始めるのはとても簡単です。
• GitHubの既存のオープンソースライブラリ（ほぼ同じサイズ）を熟読して、ファイルとリリースを整理する方法を確認します。彼らがどのようにバグ/問題追跡を行い、リクエストをプルするかを見てください。経験がない場合は、これらの1人以上に貢献して、これらの多人数プロジェクト組織プロセスの経験を積んでください。GitHubには、これらのプロセスに適したツールがあります。それは素晴らしいことをしますREADME.md最上位レベルのディレクトリと任意のディレクトリにあるドキュメントファイル、およびライセンスファイルを使用して、ます。
• ライブラリ、そのAPI、およびドキュメントに関するフィードバックを得るために、コラボレーターの参加を検討してください。
  • リリースすると、休暇中にバグを修正したり、ユーザーの質問に答えたり、コードレビューでプルリクエストを実行したり、ライブラリを解放するタスクを分割したりするために、1人以上の協力者がいると役立ちます。プロジェクト管理とライブラリ設計の追加の経験をもたらします。
• これまで、直線的なgitコミット履歴を作成してきました。最終的には、特定の修正と変更に「発行ブランチ」を使用し、リリースへの制御された準備段階に「リリースブランチ」を使用し、マージする準備ができていない複数の人の進行中の作業に「開発ブランチ」を使用すると便利ですマスターブランチに。そのため、これらのgitスキルに依存する必要が生じる前に、これについて学習するために1日か2日は取っておき、練習を始めてください。gitは非常に柔軟で便利ですが、ユーザーインターフェースは複雑になります。
  • gitブランチとその使用について読む場所の1つは、Pro Gitブックです。ブランチを使用する多くの方法のうち、「ブランチの発行」から始めます。
  • GitHubデスクトップアプリは、ブランチを管理するための優れたツールです。また、すべての変更を確認しながらコミットメッセージを簡単に作成できるため、コミットの作成にも最適です。