第4節質量指標 · Cocoapods使用指南

[TOC] 將 Podspec 提交到 [Trunk](https://guides.cocoapods.org/making/making/getting-setup-with-trunk.html) 后，文檔服務 CocoaDocs 將為 Pod 創建一組度量標準。您可以在 [metrics.cocoapods.org/api/v1/pods/[Pod]](http://metrics.cocoapods.org/api/v1/pods/ORStackView) 上查看任何 Pod 的這些指標。這些指標用于生成各種質量修飾符，最終形成一個稱為質量指標的單一數字。該文檔是 [CocoaDocs-API](https://github.com/CocoaPods/cocoadocs-api/blob/master/quality_modifiers.rb) 中的一種[字面量編程](https://en.wikipedia.org/wiki/Literate_programming#cite_note-19)。因此，它包含為了生成單個分數而實際運行的 Ruby 代碼。另外，Swift 看起來像 Ruby ，所以你可以讀它。質量指數的目標是突出正面指標，淡化負面因素。非常有可能有一個沒有實際應用修飾符的 Pod。這意味著指數停留在默認的50位。這是一個非常合理的分數。我們對修飾符的一個很好的例子就是在 Swift 中想到一個帶有大部分代碼的 Pod。它得到了提升，而 Objective-C 不會被修改。這不是為了減少 Objective-C 的分數，而是強調目前 Swift 庫代表了具有前瞻性的最佳實踐。最后，在我們開始之前。這些指標并非一成不變，它們自推出以來一直在發展，并將在未來繼續這樣做。反饋是被欣賞的，最好是在[問題模塊](https://github.com/CocoaPods/cocoapods.org/issues/new)中——這樣他們就可以被討論了。 # 1. 人氣指標這是一個非常安全的賭注，一個非常受歡迎的庫將得到很好的照顧，并維持庫。我們根據單個指標的價值多少來衡量不同的指標，而不是僅僅使用星標作為核心指標。 ~~~ 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 }), ~~~ # 2. Swift Package Manager 我們希望鼓勵對 Apple 的 Swift Package Manager 的支持，這對社區是統一的。欲了解更多信息，請參閱我們的 [FAQ](https://guides.cocoapods.org/using/faq.html) 。目前，它正在檢查 Package.swift 的存在，一旦 SPM 開發速度放慢，我們可能會轉向測試它是否支持最新版本。 ~~~ Modifier.new("Supports Swift Package Manager", "Supports Apple's official package manager for Swift.", 15, { |...| cd_stats[:spm_support] }), ~~~ # 3. README 評分 README 評分基于一種算法，該算法查看的 README 的多樣性。你可以對[clayallsopp.github.io/readme-score](http://clayallsopp.github.io/readme-score) 上的任何URL運行算法。README 是您的庫的首頁，它可以提供 API 的概覽或顯示庫的功能。聽起來很奇怪，如果你提供了一個二進制 CocoaPod，值得將你的 README.md 嵌入到 zip 中。這意味著 CocoaPods 可以使用它來生成 Pod 頁面。我們在您的項目根目錄中的兩個目錄查找 README 或 README.md 或 README.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 }), ~~~ # 4. 修改日志擁有 CHANGELOG 意味著人們更容易比較舊版本，作為質量指標，這通常表明維護人員需要小心以顯示更改的更成熟的庫。我們在您的項目根目錄中的兩個目錄尋找CHANGELOG 或 CHANGELOG.md 或 CHANGELOG.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 }), ~~~ # 5. 語言選擇 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++" }), ~~~ # 6. 許可問題 GPL 是用于您的代碼的合法許可。但它與 App Store 上的應用程序[不兼容](http://www.fsf.org/blogs/licensing/more-about-the-app-store-gpl-enforcement)。為了防止這種情況，我們從 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，這是一個旨在不成為許可證的許可證。它被 [OSI](http://opensource.org/)（一個開放源代碼許可機構）拒絕，因為它與不包括許沒有不同。如果您想這樣做，請使用公共領域的許可證。 ~~~ 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" }), ~~~ # 7. 代碼調用測試一個庫是很重要的。當你有一個人們依賴的庫時，能夠驗證你所期望的工作是否會提高質量。 ~~~ 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 }), ~~~ # 8. 所有權 CocoaPods Specs Repo 并沒有被管理，對于較大的 SDKs，人們將創建非官方的 pod 。我們需要一種方法來說明這個Pod是為圖書館的作者而來的，所以，我們已經驗證了帳戶。這些對公司的規模非常有用;谷歌，Facebook，亞馬遜和 Dropbox。我們非常謹慎地運用這一點，并一直在與各公司進行單獨接觸。 ~~~ Modifier.new("Verified Owner", "When a pod comes from a large company with an official account.", 20, { |...| owners.find { |owner| owner.owner.is_verified } != nil }), ~~~ # 9. 維護我們希望鼓勵人們使用他們的庫來發布語義版本。如果在沒有社會契約的情況下，從一個尚未達到 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 }), ~~~ # 10. 雜項 - GitHub 特定這是一項研究項目是否被放棄的實驗。問題可能會被用作待辦事項列表，但是50+ un-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 }) ~~~