How to improve your iOS open source library
A lot of people decide to share their code on GitHub and organize it in a library. The problem? How to transform your code into a high quality open-source library. In this post I’m going to talk about important things that can be done to attract more users and improve your library’s quality.
If you’re not an Open Source contributor this post is still for you! Please skip to section 3: Medium.
📰 We just launched our Newsletter: AwesomeiOS.Weekly 📰
Intro
AwesomeiOS was created in 2014, and since then I have looked through about ten 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 taught me how they access a library before adding to their project.
OK Lucas, now teach me how to do it
Since people have their full time jobs and work on open-source on their spare time, the list was divided by difficulty, so you can decide what to attack right away based on the availability.
1. Instant README things
Clear installation section
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.
Usage example
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, so people who use a package manager like CocoaPods or Carthage can just install, paste the example code provided on the README and start customizing for their needs.
Code of Conduct
The open-source community is an amazing group of people that ensures a safe and welcoming environment for everybody. A Code of Conduct talks about what is not acceptable when engaging in the community. To add it in your project, you just have to copy and paste this example.
Use Badges
Badges are an easy and concise way to provide useful information to developers who are considering your library. In order to add them to the README, you can get your badges from Shields.io or from this README. Here are some examples:
Images & GIFs
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.
[Credits to PMAlertController and JTAppleCalendar for the examples]
Images also make your README look 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
2. Easy
CocoaPods
CocoaPods integration is a big deal because it is the most used iOS package manager.
I understand that there are people who dislike CocoaPods, but implementing it will give more people the opportunity to download your library.
The integration is easy as 123. 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 the centralized repository of all publicly available pods. You’re going to use it to push your library.
The easiest way to implement it is to follow this post and this checklist.
Carthage
Carthage is used by a lot of developers and it is a plus if you implement it. To make your library available for Carthage, please follow this link
3. Medium
Inline Documentation
To generate the documentation template in Xcode 8+, you can use Command + Option + /
4. Medium-Hard
Unit Tests
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
Travis CI
“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. It is free for open-source libraries!
You can open this link to learn how to implement Travis on your library
“But I’m a solo maintainer, why would I need automated checks?”
Christian Tietze
You still need automated checks to give trust to developers that your library won’t actually break. A lot of companies instantly reject a library if it doesn’t include automated checks. Also, it saves you time when someone makes a contribution, so Travis can tell you if the person made a mistake instantly.
UI Tests
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 library.
For more info about this, here’s a 2015 WWDC session
5. Harder (kinda)
Danger Systems
“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 project’s norms, leaving humans to think about harder problems. Here’s an example of a Danger rule:
Extra Resources
iOS README Template
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 @vsouza and I created an iOS README Template so people can follow an organized template to improve their READMEs.
The CocoaPods Quality Index
A really easy way to see what can be done to improve your library is by checking CocoaPods. The CocoaPods team has done an incredible job on creating their Quality Index — CocoaPods’ ranking algorithm that filters and ranks libraries 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 documentation.
- README Scoring: Uses ScoreMe algorithm to access number of non-code sections, number of code blocks, number of images, number of lists, number of GIFs, amount of code and penalty for lack of code blocks.
- CHANGELOG: Having a CHANGELOG means that it is easier for people to compare versions and see what has changed from release to release.
- Language Choices: Swift is encouraged and Objective-C++ are discouraged.
- Licensing Issues: CocoaPods takes points off if you use a GPL license.
- Code Calls: Multiple, smaller files are encouraged over big files.
- Ownership: Verified accounts for official Pods for companies like Google, Facebook, Amazon are verified by CocoaPods staff…
- Maintenance: Before 1.0.0 a library author makes no promise on backwards compatibility.
- Misc — GitHub specific: Tracks the number of open issues.
Special thanks to:
