まとめ

オープンソース ライブラリをリリースする場合は、次の特性があることを確認してください。

• 明確な依存関係とインストール手順
• 少なくとも 1 つの簡単なドキュメント ガイドが必要です。
• ログとリポジトリのタグを変更する
• サポートされている言語、ランタイム環境、ツールのバージョン、プロジェクトの成熟度に関する情報。
• ユーザーが質問したりコミュニケーションしたりできるメール リスト。

これらの要素のいずれかが欠けていると、一部のユーザーに怒りや不満が生じ、当然、時間の無駄にもなります。

オープンソースプロジェクトをより良くする方法

毎年、独自のライブラリを公開したり、オープンソース化したりする人が増えています。ここでは、ユーザーがライブラリに満足できるよう、私たちの経験をいくつかご紹介します。

経験則は次のとおりです。

次のようにも理解できます。

さあ、この目標を達成するために努力してみましょう。

実用的なREADMEを作成する

プロジェクトのウェブサイトが素晴らしいものであっても、潜在的なユーザーはまずREADMEファイルを読んでそのウェブサイトに出会う可能性が高いです。READMEファイルが優れたものであり、有用な情報が含まれていることを確認する必要があります。

依存関係情報を提供する

オープンソースプロジェクトを公開するということですね。それはあなたがとても賢くて、本当に素晴らしいという証です！残念ながら、誰もがあなたのような人ではありません。あなたが構築している言語やシステムを全く理解していない人もいます。つまり、あなたにとっては当たり前のことが、彼らには全く当たり前ではないということです。

1 つの問題は、依存関係やインストール手順が不足していることです。これをインストールする方法をもっと明確に説明してもらえませんか?

これはすぐにユーザーの怒りを買う可能性があります。ソースコード内でパッケージやコンポーネントの名前を探すのは面倒ですし、プロジェクトによっては、リポジトリに全く合わないような巧妙なコンポーネント名が使われていることもあります。

ユーザーをこうした混乱から解放しましょう。問題は依存関係をどのように追加するかです。理想的には、小さなコードをコピー＆ペーストするだけで済むはずです。

例が必要な場合は、Welle をクリックしてください。

プロジェクトの成熟度レベルを明確に説明します。

このプロジェクトを本番環境で数か月使用していますか？まだ不完全だと感じていますか？次のバージョンでAPIが完全に刷新されることを期待していますか？要求の厳しい古いプロジェクトでも、プロジェクトは安定して安全ですか？

これらの点を明確に説明しましょう。次回は、プロジェクトの成熟度に関する情報が全く提供されていない、質の低いプレゼンテーションのせいで、プロジェクトに1週間を無駄にしてしまうようなことはなくなるでしょう。短い文章が大きな影響を与える可能性があることに気づくでしょう。

ランタイム、言語、ツールのバージョンに関するドキュメントのサポート

Clojureは後方互換性に関して優れた実績を誇っています。信じられないほど優れています。1.2から1.3以降へのアップグレードは、ほとんどのプロジェクトにとって単なる置き換えで済みます。同様に、1.2以降のプロジェクトでは、ほとんどの場合、最新の安定バージョンが使用されています。

しかし、必ずしもそうとは限りません。Clojureの将来のバージョンでは互換性ルールに違反するケースもあります。ユーザーの怒りを抑えるにはどうすればよいでしょうか？READMEにサポートされているバージョンを明記すればいいのです。

たった1行のテキストを書くだけで済みます。こうすることで、公開した週に苦情が減り、初心者のトラブルも大幅に軽減されます。

例が必要な場合は、Welle の例を参照してください。

使用しているライセンスについて説明してください。

あなたはライセンスをあまり気にしないかもしれませんが、あなたのライブラリを使いたい大企業の人たちは気にします。彼らには知っておく必要があります！彼らはClojure/Node.js/Scala/Goなどを使いたい時に、あなたのライブラリが使えないかもしれないのですから。

したがって、ライセンスを明確に記載してください。また、正当な理由がない限り、商用ライセンスを使用してください。Apache Public License 2.0やEclipse Public Licenseなどは良い選択肢です。MITライセンスなど、一部のライセンスは非常に商用ライセンスとして普及していますが、特許保護が提供されないため、現在の法的環境においては無視すべきではありません。

最後に、APL2/GPLv2のように、完全にライセンス中立であれば、デュアルライセンスを使用できることを覚えておいてください。そうすれば、ユーザーは自分に最適なライセンスを選択できます。

疑問がある場合は、概要を参照してください。法的ライセンスとオープンソース ライセンスが平易な言葉で要約されています (ただし、これを法的アドバイスとして受け取らないでください)。

どうやって台無しにしたんですか？

ユーザーを詐欺したい場合は、次のことを試してください。

• プロジェクトのルート ディレクトリに空の README ファイルを配置します。
• 最後に「パッチは大歓迎です」と書いてください。
• 独自のライセンスを作成するか、WTFPL などのまったく馴染みのないライセンスを使用します。

そうなると、あなたのプロジェクトにはユーザーが一人もいなくなるでしょう。保証します。

プロジェクトのドキュメントを書く

ドキュメントの作成は簡単ではなく、時間がかかります。しかし、ドキュメントはユーザーにとって最も効果的な手段の一つです。ドキュメントはユーザーの時間を大幅に節約するだけでなく、ライブラリが放置されたソフトウェアではないという安心感を与えることにもつながります。

ドキュメントは、ユーザーがライブラリを使用する際に最初に行うタスクを完了することを可能にします。Rob Pike氏が述べたように、ドキュメントは「それらのタスクを可能にする」のです。これにより、ユーザーはあなたがドキュメントを重視していること、そしてあなたが単なるコード生成マシンではなく、感情を持った人間であることを理解できます。

ClojureWerkz で約 2 年間働いた後、ユーザーが最も評価しているのはプロジェクトのドキュメントであると自信を持って言えます。

• Elastischドキュメント
• Welleのドキュメント
• ネオコンの文書
• Monger ドキュメント
• ランゴール文書

優れたドキュメントを書くには時間がかかります。幸いなことに、最新のツールが役に立ち、面倒な作業を大幅に軽減してくれます。

ClojureWerkzプロジェクト向けに、Jekyllベースのドキュメントテンプレートをオープンソース化しました。CSSやビジュアルデザインに特に精通しているわけではないので、TwitterのBootstrapライブラリを使用しました。ドキュメントサイトの見た目はもっと良くできるかもしれませんが、多くのオープンソースプロジェクトと比べると、既にかなり優れています。このテンプレートをご利用いただくか、ご自身のプロジェクト向けに同様のツールを開発していただくことも可能です。

さらに良いことには、ドキュメント サイトをオープンソース化すると (そうしない理由はないように思えますが)、コードの変更に貢献するよりも前に、人々が小さな改善に貢献してくれるようになります。

プロジェクトを文書化する価値があるかどうかまだわからない場合は、Jacob Kaplan-Moss による次のレポートをご覧ください。

どうやって台無しにしたんですか？

ユーザーを詐欺したい場合は、次のことを試してください。

• ドキュメントや例さえも書かないでください。
• API ドキュメントが 3 か月間更新されていないことを確認してください。
• 最も基本的なことさえ理解するためにコードを読もうとしないユーザーは愚かであり、ハンバーガーを売るべきだと私は断言します。

アップグレードが簡単

時には、プロジェクトの別のバージョンをリリースしたいと思うこともあるでしょう。これは、既にライブラリを使用しているユーザーを喜ばせることもあれば、時間を無駄にしてしまったと怒らせることもあります。

下位互換性は気にしない

ソフトウェア開発で最もイライラすることの一つは、ライブラリをアップグレードしたのに何百ものテストが失敗する時です。さらにイライラするのは、誰かが何の警告もなく公開APIを壊してしまったために、基盤となるコードベースの半分を書き直さなければならない時です。

そのため、私たちは後方互換性の維持に尽力しています。もちろん、OpenJDKのように15年以上前のプロジェクトをサポートする必要はありません。しかし、変更点を見つけやすくするために、削除する前に特定のものの使用を避けることをお勧めします。

どうやってそれを実現するのでしょうか? 変更ログを維持します。

変更ログを作成する

場合によっては、ユーザーはアップグレードすることがあります（詳細は後述）。その際、次のような疑問が湧きます。

このリリースではどのような変更が行われましたか?

それから

コードは使えなくなりますか？ 必ず書き直さなければなりませんか？

やっと

ジョー、システム管理者は私がアップグレードしたせいで私を嫌うでしょうか？

これらの疑問はすべて、変更履歴を見れば解決できます。Twitterに似ていますが、より実用的です。仕組みは以下のとおりです。

• バグを修正するたびに、ログに簡単な記録を追加します。
• 新しい機能を追加するたびに、ログにその機能について簡単に記述し、いくつかのコード例を挙げて説明してください。
• 大きな API 変更を行った場合は、必ずログに太字で明確に記述してください。

以上です。3つ目のステップはありません。

変更ログは通常、最新のエントリを先頭に配置します。変更はバージョン別に分類されます。複数のブランチ（例：masterと1.0.x）がある場合は、それぞれに独立した変更ログを作成する必要があります。

以上です。Welleの変更履歴を確認してください。

バージョンにタグを追加する

今年もこの時期がやってきました。バージョンをアップグレードし、成果物をリリースする準備が整いました。ちょっと待ってください。まずは一つだけやっておきましょう。このコミットにタグを付けましょう。タグがないと、バージョン間の差分を見つけるのが大変な作業になってしまいます。

一部の依存関係 (Bundler、Rebar など) および構成管理ツールはタグを使用でき、これらのタグは開発者システムで利用できます。

v1.0.0-alpha1、v1.0.0、v1.1.2 などの一貫したバージョン情報を使用します。一貫性のないタグ付けは、システム管理者にとってプロジェクトを悪夢にしてしまうことは間違いありません。

バージョンリリースを発表

バージョンをリリースした後は、ブログ投稿を書くか、プロジェクトのメーリング リストまたはより大規模な関連メーリング リスト (Clojure メーリング リストや RabbitMQ など) に更新を送信する必要があります。

件名は必ずANNまたは[ANN]で始まってください。これはアナウンスメントであることを示します。例えば…

ANN Welle 1.5.0 リリース

アナウンスでは、プロジェクトの目的、後方互換性の有無を明確に説明し、ユーザーがより詳しい情報を確認できるように変更ログへのリンクを含める必要があります。これで完了です。

開発中はプレビュー版またはスナップショット版を使用する

0.2.1 のような同じバージョンを半年近く使い続けているプロジェクトを見たことがありますか？ どのバージョンが 0.2.1 なのか、どうやってわかるのでしょうか？まだ開発中でしょうか？誰かがアップグレードしたのにバージョン番号の更新を忘れたのでしょうか？一体何が起こっているのでしょうか？

開発者はみんな気が狂いそうです！そんな人はやめましょう！プロジェクトではプレビュー版かスナップショット版を使い、リリースが近づいた時にだけ公開しましょう。そして、リリース後はすぐにアップグレードしましょう。

以下に開発バージョンの例をいくつか示します。

• 1.1.0.pre1
• 1.1.0-アルファ1
• 1.1.0-スナップショット

開発バージョンに他の命名形式を使用すると不明瞭になり、ユーザーにとって非常に不快なものになります。

どうやって台無しにしたんですか？

ユーザーを完全に騙したい場合は、次のことを試してください。

公開 API を恣意的に破壊しないでください。できれば、テストでも API の変更が検出されないような微妙な方法で破壊してください。

• バージョン情報のアップグレードを忘れました
• バージョンタグを追加しない
• バージョンリリースを決して発表しない

GitHubの使用

GitHubとはあまり親しい関係にありませんし、Gitが「最高の」バージョン管理システムだとも思っていません。でも、本当に素晴らしいです。最近はほとんどの人がGitHubを使っています。

GitHub を使用すると、次のことが容易になります。

• プロジェクトを見つける
• コードの閲覧と検索
• 質問を入力するか、@ をメンションすることで質問をフォローできます。
• 小さな変化に貢献する

おそらく最も重要なのは、GitHubが技術に詳しくない人にとっても非常にユーザーフレンドリーであるということです。まさにその通りで、彼らはGitHubをさらに良くするために懸命に取り組んでいます。

GitHub を使用すると、CI サービス (Travis CI) を非常に簡単に使用できるようになります。

ユーザーにパッチを扱わせたり、問題を報告するためにインターネットでメールアドレスを検索させたり、誤字を編集するためだけにひどい 3G ネットワーク経由で 300 MB のリポジトリをコピーさせたりしない方が、より多くの賞賛を得られるでしょう。

@old_sound @g3rtm Bitbucketは間違いなく素晴らしいサービスです。しかし、オープンソースコードを使う人にとっては少し使いにくくなり始めています。 – Michael Klishin (@michaelklishin) 2013年12月21日

物事を難しくしないでください。

ユーザーがサポートを受けられる場所を提供します。

プロジェクトが一定の人気レベルに達したら、いくつかの質問に答える必要があります。そのためには、メーリングリスト（Googleグループなど）を作成するか、IRCを頻繁に使用する場合はチャンネルを開設してください。

時間が足りないとお考えですか？メーリングリストを利用する最大のメリットは、ユーザーが互いに助け合える手段を提供できることです。そのため、プロジェクトのREADMEに、サポートを受ける方法を明確に記載しておく必要があります。

Twitterでプロジェクト名を頻繁に検索すると、様々な質問、批判、称賛の声が見つかります。Twitterを頻繁に使用する場合は、プロジェクト専用のアカウント（@ClojureWerkzなど）を作成してください。

これにより、プロジェクトの利用状況や改善点を把握できるコミュニティを構築できます。最終的には、プロジェクトの維持を手伝ってくれる人を見つけるのに役立ちます。これは時間の節約になるだけでなく、プロジェクトを宣伝するきっかけにもなります。

例が必要な場合は、Welle README にコミュニティとサポートに関するセクションがあります。

どうやって台無しにしたんですか？

ユーザーを完全に騙したい場合は、次のことを試してください。

• GitHub 上の問題を無効にする機能。
• 開発協定を利用するには、ユーザーはタンザニアに紙の手紙を書く必要があります。
• README で 1 行だけ変更する場合でも、パッチを使用する必要があります。
• Ruby、JavaScript、Clojure プロジェクトの場合でも、プロジェクトを Darcs に配置します。
• プロジェクトがどこにあるか見つけるのが難しくなります。

これにより、他のユーザーがプロジェクトに貢献したり、サイトからアイデアを盗んだりすることを防ぐことができます。

他の人に伝える

いつか、プロジェクトのメンテナンスに抵抗を感じる時があるかもしれません。転職したり、自分のプロジェクトを使わなくなったりするかもしれません。メーリングリストでその旨を伝え、誰かにプロジェクトを引き継いでもらいましょう。すぐに誰かが助けてくれるでしょう。GitHubはこのような時に役立ちます。特に、リポジトリの管理権限を委譲できる新機能が発表されたので、なおさらです。

何をするにしても、誰も責任を負わないプロジェクトにならないようにしてください。これが、現在のユーザーと将来のユーザーが猫の虐殺を続けられるようにするための最も確実な方法です。

後で言い訳をするよりも、プロジェクトを他の人に引き渡す方が常に良いです。

どうやって台無しにしたんですか？

ユーザーを完全に騙したい場合は、次のことを試してください。

• 説明なしに突然コードの投稿をやめ、メーリング リストでの質問への回答をやめます。
• 提出リクエストを無視し、提出物は役に立たないので他の提出物を作成する必要があると伝えます。
• 問題が解決したら、一切の興味を失ってしまう人だと言うこと。

これにより、どのコピーされたプロジェクトがどの問題を解決したかを判断するのは非常に面倒な作業であるため、最終的にプロジェクトが少なくとも 300 回コピーされ、最後の置換プロジェクトが作成されます。

最後に

ご覧の通り、プロジェクトを受け入れられるものにするのはそれほど難しくありません。ドキュメント作成を除けば、ユーザーの怒りを鎮めたり、運用チームに嫌われないようにするのにそれほど時間はかかりません。

オープンソースプロジェクトの維持には時間と労力がかかります。しかし、やりがいも感じます。GitHubはまだテスト段階だった頃から使っていますが、これほどプロフェッショナルな機会を与えてくれるものはほとんどありません。オープンソースコミュニティで活動しているというより、今の自分の立場にいられることを嬉しく思っています。

本当にクールなことをしたくないのであれば、すぐにリリースしないほうがいいかもしれません。

オリジナルリンク: ClojureWerkz 翻訳: Bole Online - archychu
翻訳リンク: http://blog.jobbole.com/57767/