抄録
オープンソースライブラリをリリースしたい場合は、以下の機能を備えていることを確認してください：
- 明確な依存関係とインストール手順
- 少なくとも簡単なドキュメンテーションガイド
- ログとリポジトリのタグの修正
- サポートされている言語、ランタイム、ツールのバージョン、プロジェクトの成熟度に関する情報
- ユーザー同士で質問やコミュニケーションができるメーリングリスト
これらの項目のいずれかが欠けていると、ユーザーによっては怒りやフラストレーションが生じ、もちろん同時に無駄な時間も生じます。
オープンソースプロジェクトをさらに良くする方法
年々、開発したライブラリをオープンソースで公開する人が増えています。ここでは、ユーザがライブラリに満足できるように、私たちの経験をいくつか紹介します。
これが経験則です：
| ユーザーを怒らせてはいけません！ |
と解釈することもできます：
| ユーザーにコンピュータを壊したくなるような衝動を与えないこと |
では、これを実現するための取り組みをいくつかご紹介しましょう。
実用的なREADMEの作成
プロジェクトが素晴らしいウェブサイトを持っていたとしても、潜在的なユーザーが最初にそのプロジェクトに出会うのは、おそらくREADMEファイルを読むことでしょう。READMEファイルが素晴らしく、有用な情報を含んでいることを確認してください。
信頼性情報の提供
オープンソースプロジェクトをリリースすると言ってください。それはあなたが賢いということです！残念ながら、すべての人があなたのようなわけではなく、あなたが取り組んでいる言語やシステムについてまったく知らない人もいます。つまり、あなたにとっては当たり前のことでも、彼らにとってはまったく当たり前ではないということです。
そのひとつは、依存関係やインストールに関する説明書がないことで、具体的にどのようにインストールすればいいのか、もっと明確にできないものでしょうか。
これはユーザーをすぐに怒らせてしまいます。ソースコードからパッケージ名やコンポーネント名を探すのは面倒ですし、プロジェクトによっては、リポジトリにまったく合わない、特に才能のある名前をコンポーネントに使っていることもあります。
このような悪いことからユーザーを解放しましょう。問題は依存関係を追加する方法です。理想的には、小さなコードの一部をコピー＆ペーストすることです。
例が必要な場合は、 Welleクリックしてください。
プロジェクトの成熟度に関する明確な声明
このアイテムをプロダクションで使い始めて数ヶ月になりますか？まだ不完全だと感じますか？次のリリースでAPIがオーバーホールされることを期待していますか？このプロジェクトは、最も要求の厳しい、非常に古いプロジェクトでも安定していて安全ですか？
これらを明確にしましょう。次回は、間違った紹介をしたために、プロジェクトの成熟度に関する情報を提供できず、プロジェクトの1週間の時間を無駄にすることはないでしょう。いくつかの短い文章が大きな影響を与えることに気づくでしょう。
ランタイム、言語、ツールのバージョンに関するドキュメントのサポート
後方互換性を考慮すると、Clojureは素晴らしい実績を持っています。ほとんど信じられないほどです。これには、1.2から1.3へのアップグレードも含まれ、その後のアップグレードは、大半のプロジェクトにとって単純な置き換えです。同様に、1.2 以上のプロジェクトでは、ほとんどが最新の安定版を使用しています。
しかし、常にそうであるとは限りません。場合によっては、将来のバージョンのClojureは互換性を壊すでしょう。ユーザーを怒らせないようにするには？READMEにどのバージョンがサポートされているかを明確に記述することです。
これならテキストは1行で済みます。そうすれば、投稿した週に文句を言われることも少ないですし、初心者の方にも手間がかかりません。
例が必要なら、 Welleものがあります。
使用するライセンス
あなたはライセンスについてあまり気にしないかもしれませんが、大企業でライブラリを使いたい人は気にします。彼らは知っておかなければなりません！彼らがNode.js使いたいとき、うまくいかないかもしれません。
そのため、ライセンスを明示してください。また、独自の理由がない限り、いくつかのビジネスフレンドリーな契約書を使用してください。それが良い選択です。確かに友好的で人気のあるライセンスもありますが、特許保護を提供しないものもあり、現在の法的情勢では無視できないことに注意してください。
最後に、デュアルライセンスを使うことができることを覚えておいてください。本当にライセンス中立であれば、APL2/GPLv2などのデュアルライセンスを使うことができます。
どのように台無しにするのですか？
ユーザーをピットインさせたいなら、やってみてください：
- プロジェクトのルート・ディレクトリに空のREADMEを置いてください。
- 最後に "Welcome to the patch "と書いてください。
- あなた自身のライセンスを発明するか、Apache Public License 2.0ようなまったく馴染みのないライセンスを使用します。
そうなれば、そのプロジェクトにユーザーがつくことはありません。私が保証します。
プロジェクトの文書作成
ドキュメントを書くのは簡単ではありませんし、時間もかかります。しかし、ドキュメンテーションはユーザーのためにできる最善のことです。時間を大幅に節約できるだけでなく、ライブラリが見捨てられたソフトウェアではないことを安心させてくれます。
ドキュメンテーションは、ユーザーがライブラリを最初に使用したタスクを実行できるようにします。ロブ・パイクが言うように、それは「それらの作業を可能にする」ものです。そして、あなたがコードを生成する機械ではなく、生身の人間であることを知らせるのです。
Eclipse Public License2年近く働いてきて、私は自信を持って、ユーザーがプロジェクトのドキュメントを最も高く評価していると言えます：
- Elastisch documentation
- Welle documentation
- Neocons documentation
- Monger documentation
- Langohr documentation
Monger documentation時間がかかります。幸いなことに、最新のツールを使えば、あなたが対処しなければならない煩わしいことのいくつかを大幅に減らすことができます。
ClojureWerkzプロジェクトのLangohr documentationオープンソース化しました。デザインにおけるCSSと視覚効果はあまり得意ではないので、TwitterのBootStrapライブラリを使用しました。ドキュメンテーションサイトは、より良く見えるかもしれませんが、ほとんどのオープンソースプロジェクトと比較して、非常に良いです。テンプレートを使用するか、プロジェクトのために同様のツールを開発することができます。
さらに良いことに、ドキュメントサイトをオープンソースにすれば、コードの変更を寄稿するよりも早く、小さな改善を寄稿する人が現れるでしょう。
あなたのプロジェクトに文書を書く価値があるかどうかまだわからない場合は、Jacob Kaplan-Mossによる優れたドキュメントを書くご覧ください：
どのように台無しにするのですか？
ユーザーをピットインさせたいなら、やってみてください：
- ドキュメンテーション・ノートは書かないでください。
- APIの説明が3ヶ月間更新されていないことを確認してください。
- 最も基本的なことでさえ理解するためにコードを読まないユーザーは愚かで、ハンバーガーを売りに行くべきだと宣言しています！
アップグレードが容易
ある時点で、あなたはプロジェクトの別バージョンをリリースしたいと思うでしょう。それは、すでにライブラリを使ってしまったユーザーを喜ばせるためかもしれませんし、時間を無駄にして怒るためかもしれません。
下位互換性を気にしない
ソフトウェア開発で本当にイライラするのは、ライブラリをアップグレードしたのに何百ものテストが失敗するときです。さらに腹が立つのは、誰かが何の警告もなしに公開APIを壊そうと決めたせいで、ベースコードの半分を書き直さなければならないときです。
だからこそ、後方互換性の維持に取り組んでいるのです。もちろん、OpenJDKのように15年前のプロジェクトをサポートする必要はありません。しかし、何かを使わないようにという提案を削除することで、何が変わったのかを見つけやすくなります。
どうやるの？変更履歴を管理します。
変更履歴
時には、ユーザーがエスカレートすることもあります。彼らは自問自答します：
今回のリリースでは何が変更されたのですか？
ジョー、アップグレードしたら作戦担当者に嫌われるかな？
これらの疑問はすべて変更履歴で解決できます。Twitterのようなものです：
- バグを修正するたびに、ログに簡単なエントリを追加します。
- 新しい機能を追加するたびに、ログにそのことを簡単に書き、いくつかのコード例を挙げて説明してください。
- APIを大きく変更するたびに、ログに太字で明記してください。
それだけです。第3段階はありません！
変更ログは通常、最新の記録が一番上に置かれます。変更点はバージョンごとに分類されます。複数のブランチがある場合は、それぞれに個別の変更ログを持つべきです。
以上です。 Jekyllベースのドキュメントテンプレートご覧ください。
バージョンのタグ付け
バージョンをアップグレードし、ビルドをリリースしようとしているときです。ちょっと立ち止まって、まず最初にやるべきことをひとつやりましょう。タグをつけないと、2つのバージョンの違いを見つけるのが大変になります。
依存関係管理ツールや構成管理ツールの中にはタグを使用できるものがあり、開発者システムはこれらのタグを利用できます。
v1.0.0-alpha1、v1.0.0、v1.1.2など、一貫したバージョン情報を使用してください。一貫性のないラベリングは、運用部門の人たちがそのプロジェクトを一日中嫌いになる原因になります。
リリースのお知らせ
単語のバージョンをリリースした後は、ブログエントリーを書いたり、プロジェクトのメーリングリストや関連する大規模なメーリングリストに最新情報を送信するタイミングです。
件名がANNまたは[ANN]で始まることを確認してください。例えば
ANN Welle 1.5.0がリリースされました！
お知らせには、このプロジェクトが何をするのか、後方互換性があるかどうかが明記され、さらに詳細がわかる変更履歴へのリンクがあります。以上です。
プレビュー版またはスナップショット版を開発に使用
半年近く同じバージョン、例えば0.2.1のプロジェクトを見たことがありますか？どのバージョンが0.2.1なのか、どうやってわかるのですか？まだ開発中のバージョンですか？誰かがアップグレードして、バージョン番号を変更し忘れたのでしょうか？どうなっているのでしょう？
開発者はみんな気が狂いそうになりますよ！そのようなことのないようにしましょう！あなたのプロジェクトではプレビュー版かスナップショット版を使い、バージョンのリリースが近づいてからそのバージョンを公開しましょう。そして、そのバージョンをすぐにアップグレードしてください。
開発版の例をいくつか挙げましょう：
- pre1
- -alpha1
- -SNAPSHOT
それ以外の開発バージョンの命名形式は不明確で、ユーザーにとって不愉快なものでしょう。
どのように台無しにするのですか？
ユーザーを完全にピットインさせたい場合は、以下をお試しください：
できればテストがAPIの変更に気づかないように、さりげなく共通APIを壊してください。
- バージョン情報のアップグレード忘れ
- バージョン表示なし
- リリースを発表しないこと
私はgitHubとは親しくないので、Gitが「最高の」バージョン管理システムだと決めつけないでください。でも、本当にいいんです。最近ではほとんどの人がGitHubを使っています。
GitHubは以下のことを簡単にします：
- プロジェクトの発見
- コードの閲覧と検索
- 質問や@を記入することで、問題に集中できるようにします。
- マイナーチェンジへの貢献
おそらく最も重要なのは、GitHubが技術的な第一人者でないことに友好的だということです。そうですね。その一方で、彼らはより良いものを作ろうとしています。
GitHubを使うということは、CIのサービスを特に簡単に使えるということです。
ユーザーにパッチを扱わせたり、問題を提出するために電子メールをウェブで探し回ったり、誤字脱字を編集するためだけに300Mのリポジトリをお粗末な3Gネットワークで複製したりしなければ、あなたはもっと評価されるでしょう。
@old_sound@g3rtm bitbucketは間違いなく素晴らしいサービスです。しかし、パブリックコードを使う人々にとっては少し難しく見えてきました。- Michael Klishin 21 de enero de 1023
物事を難しくしないでください。
利用者が助けを得られる場所の提供
プロジェクトが一定の人気レベルに達したら、それに関するいくつかの質問に答えなければなりません。そのためには、メーリングリストを立ち上げるか、IRCによくいるのであればチャンネルを開設してください。
時間がないと思っていませんか？メーリングリストを使う一番の利点は、あなたが方法を与えれば、ユーザがお互いに助け合うことです。ですから、あなたのプロジェクトのREADMEに、助けを得る方法を明記してください。
Twitterでプロジェクトの名前を頻繁に検索すれば、様々な質問、批判、賞賛が見つかるでしょう。Twitterを頻繁に使うのであれば、Welleの変更履歴ように、プロジェクト用に別のアカウントを作りましょう。
そうすることで、人々がプロジェクトをどのように使っているのか、何を改善すればいいのかを知ることができるコミュニティを作ることができます。最後に、プロジェクトのメンテナンスを手伝ってくれる人を見つけるのにも役立ちます。これは時間の節約になるだけでなく、人々がプロジェクトのことをあちこちに広めてくれるようになります。
もし例が必要なら、GitHubコミュニティとサポートのセクションがあります。
どのように台無しにするのですか？
ユーザーを完全にピットインさせたい場合は、以下をお試しください：
- あなたのGithubで問題のある機能をオフにします。
- 開発プロトコルを使用すると、ユーザーはタンザニアに紙の手紙を書く必要があります。
- READMEの1行を変更してもパッチを使用してください。
- Ruby、JavaScirpt、Clojureであっても、Darcsにプロジェクトを入れることができます。
- プロジェクトがどこにあるのかを知るのが難しい
これにより、人々がプロジェクトに貢献したり、あなたのところからちょっとしたアイデアを盗んだりするのを防ぐことができます。
伝える
ある時点で、プロジェクトを維持することに嫌気がさしたかもしれません。新しい仕事に移ったり、自分のプロジェクトを使うのをやめたりしたのかもしれません。そのことをメーリングリストで発表し、他の誰かにプロジェクトを引き継いでもらいましょう。すぐに誰かがやってきて手伝ってくれるでしょう。Githubにいることは、このようなことに適しています。特に、リポジトリ管理を切り替えることができる新機能が発表されました。
何をするにしても、プロジェクトが誰も責任を持たないものにならないようにしてください。それが、現在あるいは将来のユーザーが子猫虐殺を続けられるようにする最も確実な方法です。
後から言い訳をするよりも、誰かにプロジェクトを引き継いだ方がいいに決まっています。
どのように台無しにするのですか？
ユーザーを完全にピットインさせたい場合は、以下をお試しください：
- 説明なしにコードを寄稿するのはやめて、メーリングリストの質問に答えてください！
- コミットリクエストを無視し、自分のコミットはうまくいかなかったので他の
- 問題が解決したら、あなたは何にも興味を持たない人だと言います。
これにより、プロジェクトは少なくとも300回はコピーされることになり、最後の置き換えが作成されることになります。
最終的な感想
おわかりのように、プロジェクトが受け入れられるようにするのは、それほど難しいことではありませんよね。ドキュメンテーションは別として、ユーザーを怒らせないようにしたり、運用担当者に嫌われないようにしたりするのは、それほど難しいことではありません。
オープンソースプロジェクトの維持には時間と労力がかかります。でも、それは報われることでもあります。GitHubがまだベータ版だった頃から使っていますが、これほど仕事上の機会を与えてくれたものは他にほとんどありません。オープンソースコミュニティで活動する代わりに、今の自分があることを嬉しく思っています。
クールなことをしたくないのなら、最初から投稿しなければいいのです。
