良いライブラリを提供するために、読んでおくと良さげだったので適当にそれっぽく訳しました。細かいニュアンスとか正確な情報は原文
を読んで下さい。
品質の指標
podspecをpod trunk
で提出すると、CocoaDocsは提出したpodの指標を生成します。
指標は http://metrics.cocoapods.org/api/v1/pods/[Pod] で参照することが出来、これは品質の評価を算出するために利用されます。
品質の指標を設ける目的は、品質の良し悪しを際立たせるためです。
Podはデフォルトのままであれば50という数値評価になります。
この考え方の良い例としてはSwiftのライブラリがあります。
SwiftのライブラリはObjective-Cよりも高い評価を得ます。
しかし、Objective-Cの評価を下げる事ではありません。
これはSwiftのライブラリが先進的で、良い事例であるからです。
始める前に一つ。これらの指標は柔軟性に乏しいわけではなく、常に進歩を遂げています。
評価に対するフィードバックは高く評価していますので、議論があればIssueを立ててください。
https://github.com/CocoaPods/cocoapods.org/issues/new
人気度 (Popularity Metrics )
とても人気のあるライブラリは多くの人が目にする事になりますし、メンテナンスもされるようになります。
私達は品質の指標を★ではなく、項目に分けて重み付けをしました。
Modifier.new("Very Popular", "The popularity of a project is a useful way of discovering if it is useful, and well maintained.", 30, { |...|
value = stats[:contributors].to_i * 90 + stats[:subscribers].to_i * 20 + stats[:forks].to_i * 10 + stats[:stargazers].to_i
value > 9000
}),
しかし、すべてのアイデアがそのような高い指標を保証するのに十分な大きさである必要はありません。多くはライブラリ自体が便利であれば良いはずです。
Modifier.new("Popular", "A popular library means there can be a community to help improve and maintain a project.", 10, { |...|
value = stats[:contributors].to_i * 90 + stats[:subscribers].to_i * 20 + stats[:forks].to_i * 10 + stats[:stargazers].to_i
value > 1500
}),
Swift Package Manager
AppleのSwift Package Managerのサポートを奨励したいと思っています。コミュニティを統一する方が良いでしょう。詳細については、FAQを参照してください。
今はPackage.swiftの存在をチェックしています。
SPMの開発が落ち着いてきたら、最新のリリースをサポートしているかどうかをテストするようになるかもしれません。
Modifier.new("Supports Swift Package Manager", "Supports Apple's official package manager for Swift.", 15, { |...|
cd_stats[:spm_support]
}),
READMEスコア(README Scoring)
READMEスコアは、バンドルされているREADMEのさまざまな種類を調べるアルゴリズムに基づいています。 clayallsopp.github.io/readme-score では任意のURLに対してスコアを計算することができます。 READMEはあなたのライブラリの一番上にあり、APIの概要を提供したり、何が出来るライブラリなのかを示すことができます
バイナリをCocoaPodを提供している場合は、README.mdをzipに埋め込む価値があります。CocoaPodsは埋め込まれたzipを利用してpodページを生成できることを意味します。
私たちはあなたのプロジェクトのルートから二階層までREADME{,.md,.markdown}を探します。
注:podspecのdocumentation_urlを品質評価の要素に入れたいので、評価方法は変わるかもしれません。
Modifier.new("Great README", "A well written README gives a lot of context for the library, providing enough information to get started. ", 5, { |...|
cd_stats[:readme_complexity].to_i > 75
}),
Modifier.new("Minimal README", "The README is an overview for a library's API. Providing a minimal README means that it can be hard to understand what the library does.", -5, { |...|
cd_stats[:readme_complexity].to_i < 40
}),
Modifier.new("Empty README", "The README is the front page of a library. To have this applied you may have a very empty README.", -8, { |...|
cd_stats[:readme_complexity].to_i < 25 && spec.documentation_url == nil
}),
CHANGELOG
CHANGELOGを持つことは、古いバージョンを比較する人達により優しいかと思います。これは、品質の基準として、メンテナが変更を示すために気を配り、より成熟したライブラリであるということです。私たちはあなたのプロジェクトのルートから二階層までCHANGELOG{,.md,.markdown}を探します。
Modifier.new("Has a CHANGELOG", "CHANGELOGs make it easy to see the differences between versions of your library.", 8, { |...|
cd_stats[:rendered_changelog_url] != nil
}),
言語の選択 (Language Choices)
Swiftは素晴らしいです。私達はSwiftで書かれたライブラリをひいきします。
Modifier.new("Built in Swift", "Swift is where things are heading.", 5, { |...|
cd_stats[:dominant_language] == "Swift"
}),
Objective-C++ライブラリはSwiftとの統合が難しく、大半のプロジェクトが使用されていたのとは異なるプログラミングのパラダイムが必要になる可能性があります。
Modifier.new("Built in Objective-C++", "Usage of Objective-C++ makes it difficult for others to contribute.", -5, { |...|
cd_stats[:dominant_language] == "Objective-C++"
}),
ライセンスの問題 (Licensing Issues)
GPLは正当なライセンスです。ですが、殆どの場合App Storeにアプリを配布する事とは相性が悪いです。
このような課題があるため、私たちはGPLのライブラリは評価を下げています。
Modifier.new("Uses GPL", "There are legal issues around distributing GPL'd code in App Store environments.", -20, { |...|
cd_stats[:license_short_name] =~ /GPL/i || false
}),
WTFPLを使用しているライブラリもかなりあますが、これはライセンスとは認めたくありません。なぜなら、WTFPLはOSI(オープンソースライセンス機関)によって、ライセンスを含まないことと変わらないものとして拒否されたからです。
WTFPLを使いたいのであれば、パブリックドメインライセンスを使用してください。
Modifier.new("Uses WTFPL", "WTFPL was denied as an OSI approved license. Thus it is not classed as code license.", -5, { |...|
cd_stats[:license_short_name] == "WTFPL"
}),
Code Calls
ライブラリのテストは重要です。ライブラリは、利用者と作者が期待している動作であることをテストすることで、品質が向上します。
Modifier.new("Has Tests", "Testing a library shows that the developers care about long term quality on a project as internalized logic is made explicit via testing.", 4, { |...|
cd_stats[:total_test_expectations].to_i > 10
}),
Modifier.new("Test Expectations / Line of Code", "Having more code covered by tests is great.", 10, { |...|
lines = cd_stats[:total_lines_of_code].to_f
expectations = cd_stats[:total_test_expectations].to_f
if lines != 0
0.045 < (expectations / lines)
else
false
end
}),
cocoapodsによって、複数のファイルで構成されたライブラリが作りやすくなりました。
私達はシンプルな構成のライブラリを奨励したいです。
Modifier.new("Lines of Code / File", "Smaller, more composeable classes tend to be easier to understand.", -8, { |...|
files = cd_stats[:total_files].to_i
if files != 0
(cd_stats[:total_lines_of_code].to_f / cd_stats[:total_files].to_f) > 250
else
false
end
}),
権限(Ownership)
CocoaPods Specs RepoはライブラリをWebから収集しているわけではありません。大きなSDKの場合、企業は公式のpodを作成します。ライブラリが公式のものか確認するために、私達はアカウントを確認します。これらは、大規模の企業にとって有益です。
Google、Facebook、Amazon、Dropboxなどがあります。我々はこれを非常に控えめに評価に加味しており、個々に企業にアプローチしています。
メンテナンス(Maintainance)
私たちは、開発者がセマンティックバージョンを利用するように促したいと考えています。まだ1.0.0になっていないライブラリから何を期待するのかを知ることは難しいかもしれません。これは、v1.0.0より前のライブラリ作成者は、後方互換性について約束していないからです。
Modifier.new("Post-1.0.0", "Has a Semantic Version that is above 1.0.0", 5, { |...|
Pod::Version.new("1.0.0") <= Pod::Version.new(spec.version)
}),
ライブラリを非推奨にするときは、その結果を検索結果に反映させる必要があります。
Modifier.new("Is Deprecated", "Latest Podspec is declared to be deprecated", -20, { |...|
spec.deprecated || spec.deprecated_in_favor_of || false
}),
その他 - GitHub (Misc - GitHub specific)
これは、プロジェクトが放棄されたかどうかを判断するための実験です。IssueはTODOリストとして使用することができますが、50以上をopenのままにしておくのはやめてください。プロジェクトが崩壊した可能性は高いです。
Modifier.new("Lots of open issues", "A project with a lot of open issues is generally abandoned. If it is a popular library, then it is usually offset by the popularity modifiers.", -8, { |...|
stats[:open_issues].to_i > 50
})