📰 We just launched our Newsletter: AwesomeiOS.Weekly 📰
AwesomeiOS was created in 2014 and since then I look through about 10 libraries a day, searching for good new libraries that can be added to AwesomeiOS or even for my own projects, so I developed some tactics to quickly see if a library is good or not. Of course, as I learned more about programming, people also teached me how they access a library before adding to their project. Because I like to contribute a lot to libraries, I've developed a set of clipboard texts to quickly open issues. I also discovered that people don't always know what to include in their README.md, so I created with @vsouza an iOS README Template so people can follow an organized template to improve their READMEs.
The CocoaPods team has done an incredible job on creating their Quality Index – CocoaPods' ranking algorithm. The Quality Index is a number based on the following:
- Popularity Metrics: Different metrics are weighted according to how much more valuable the individual metric is rather than just using stars.
- Swift Package Manager: SPM is encouraged.
- Inline Documentation: These metrics are about the usage of Appledoc and Headerdoc within your public API for inline documentations.
- README Scoring: Used ScoreMe algorithm: Number of non-code sections, number of code blocks, number of images, has any lists?, number of GIFs, amount of code, penalty for lack of code blocks.
- CHANGELOG: Having a CHANGELOG means that its easier for people for compare older verions.
- Language Choices: Swift is encouraged. Languages like Objective-C++ are discouraged
- Licensing Issues: CocoaPods takes points off if you use a GPL library
- Code Calls: Multiple, smaller files are encouraged over big files.
- Ownership: Verified accounts for official Pods for companies like Google, Facebook, Amazon...
- Maintainance: Before v1.0.0 a library author makes no promise on backwards compatability.
- Misc - GitHub specific: Tracks the number of open issues
So now we have to go backwards and improve our library based on how it's quality will be accessed. Since a lot of people don't do open source and full time, the list was divided by difficulty.
Please, please, pretty please: always write an installation section with the mind of a person who just learned how to program. Easiest way? Add a manual installation guide so the people who don't know how to use CocoaPods or Carthage, can still use your library.
I often see libraries that say please see example project
instead of providing a few lines about how to implement.
It's always good to provide the easiest way to implement the main function of your library in the first few lines of the README.md
, so people who used the package managers
Badges are just so easy to add and they show important information that gives more trust from the developer who is thinking about using your library. Here are some examples:
Credits to PMAlertController and JTAppleCalendar
If you have an UI library like an Alert, special animation or a cool button, it's always good to have an image or GIF to visually show what your library does. By doing that your README looks much better. Also, people don't have to spend time compiling your library to see if it is a fit for their projects. And you can always do something funny like this library.
CocoaPods is easy as 123. I understand that it's kinda tricky to learn how to do it, but once you learn, it becomes a really simple task. The main concepts you need to know:
- Podspec: This file describes information about this specific version of your pod. Your pod's, version number, homepage, and author names are some examples of what’s included.
- Git tags: Tag your most recent commit and push it to the remote.
- Trunk: CocoaPods Trunk is an authentication and CocoaPods API service. Easiest way is to follow this post and this checklist.
To make your library available for Carthage, please follow this link
/// EZSE: Checks if String contains Email
public var isEmail: Bool {
let dataDetector = try? NSDataDetector(types: NSTextCheckingResult.CheckingType.link.rawValue)
let firstMatch = dataDetector?.firstMatch(in: self, options: NSRegularExpression.MatchingOptions.reportCompletion, range: NSRange(location: 0, length: length))
return (firstMatch?.range.location != NSNotFound && firstMatch?.url?.scheme == "mailto")
}
Unit Tests give to you and your users confidence that the library is working. The more method test coverage, the better. Please check this link to learn how to use Unit Tests
"Continuous Integration, often abbreviated to just CI, is the process of automatically building and running tests whenever a change is committed". Travis runs tests at every commit so you can always check if your library is working without having to open Xcode. You can open this link to learn how to implement Travis on your library
A huge part of the iOS open source world is UI Libraries. Sometimes Unit Testing can be hard to do when you have buttons and user actions going on, so Apple made it really easy to record and implement UI Tests to your lubrary. For more info about this, here's a 2015 WWDC session
"Stop saying "you forgot to …" in code review". Danger runs during your CI process, and gives teams the chance to automate common code review chores. You can use Danger to codify your teams norms, leaving humans to think about harder problems. Here's an example of a Danger rule:
# Add a CHANGELOG entry for app changes
if !git.modified_files.include?("CHANGELOG.md") && has_app_changes
fail("Please include a CHANGELOG entry. \nYou can find it at [CHANGELOG.md](https://github.com/realm/jazzy/blob/master/CHANGELOG.md).")
message "Note, we hard-wrap at 80 chars and use 2 spaces after the last line."
end