Like many developers, I use open source tools on daily basis. Recently, I’ve got the chance to create one for other teammates and try to think about what I should consider before launching it. Today I share this checklist.
License
Before sharing anything, it’s quite important to know what would be the license for your project. Thing is there are so many that it can be tricky to know what to consider for this.
Fortunately, Github helps developers quite a lot to navigate in this area.
It’s directly part of the steps when creating a new repository, so it makes it even easier for us to consider it from the start.
If you wonder why licenses are important, it defines how your software can be used, edited or distributed. Some have different restrictions, for instance for commercial use.
To understand more in-depth the most popular licenses and what applies to your own project, Opensource.org can be a good place to start.
In my case, it’s an internal tool for my current company, so all rights reserved applied.
Compatibility
It’s important to know early on the compatibility of your project. It can be defined at different level.
It could be based on the language used: what Swift version? Is Swift 5 and above enough?
It could be based on the available platform: is it iOS only? macOS too? And what version of the operation system?
It could be based on its dependencies: if you need latest Ruby version or Python, make sure to be explicit from the start.
Finally, it can be about other system it interact with, like a dependency manager. Distributing a library through Swift Packager Manager, CocoaPods or Carthage requires a different effort.
Often, contributors use badges on the header of their repositories to help clarify those information. With a quick look, you can see what is required to make use of this project.
Clarity is essential in open source projects.
Stability
Once the compatibility is define, next step is stability.
As a developer, when I evaluate if I can use a third-party library for work, I like to see how stable it is.
For instance, does the project has unit-test? Is there unit-test coverage rate? Is there a continuous-integration set to run those tests?
How about documentation? Is there a Wiki space? Maybe a sample app to navigate?
On the other hand, how many issues are known? How often are they resolved?
If those are my questions before using a third-part library, it makes sense to have the same requirements when creating a similar library for others to use.
Those information are really important for other developers, it help to build confidence in your tool that it won’t break at the first try.
But what about you? If you compare two exact same libraries with the exact same codebase, but one repository has a continuous integration, a built-in documentation, an extra sample app and all badges in green. Which one would you be more confident using?
Documentation
Early on in your project, I also believe it’s important to document as much as possible.
For instance, sharing your vision and your long term plan for your library could be a good start. You can also illustrate what project you want to tackle and what are the advantages of your solutions.
It can also be to share your design choices and trade-off made or any other technical decisions. This kind of content will avoid other developers to ask later “why not doing X rather than Y?”.
There is also a need of documentation when it comes to installation and usage. It’s always good to have some code snippet or a sample app to showcase your tool.
When diving deeper into the technical aspect, it also great to document the code and potentially have a Wiki / web documentation outside too. Fortunately, there are plenty of tools to generate documentation based on the codebase. For Swift project, my go-to are swift-doc and SourceDocs.
Collaboration
We can’t talk about open source projects without mentioning collaboration and contributions of peers. After all, it’s a community effort to maintain all those amazing projects.
This is also why it’s best practice to share guidelines how to contribute and be part of this community.
Using template for pull request can be a good start to standardize any new contribution format.
If you’re open for external contribution, make sure to have also a CI/CD pipeline setup. At this stage, it would be a shame to have to manually re-test every available feature.
If your tool is heavily used and your community get bigger and bigger, it could be good to even create new standard how to submit feature request and bug reports. That’s something Fastlane community put in place to help triage and prioritize their work.
It could be good to create a space for maintainers and users to discuss and help each others. That can be a forum like Appium or Swift, or create a Slack or Discord.
Finally, as a maintainer, it’s very important to stay open to other contributors’ feedback and suggestion. If maintainers became rude and dismissive to others, then it will most likely kill the community all together.
Remember that openness is the key to open source development.
Know when to stop
One last thing that is worth mentioning is to know when deprecating and archiving your work.
You built this amazing library few years back and don’t feel the energy to support and maintain it?
That’s okay. Life goes on, and you move to new projects, people will understand.
When you leave this project, if you can find new maintainers to take over, that’s really great. If you can’t, just highlight your library is deprecated or archive it moving forward. This will help any developers to know the status of it if they ever find it.
In conclusion, if open source projects are really exciting to start and a great opportunity to share your latest tool or framework, there is a lot more to consider for it to survive over time. After all, it’s not just a project but it becomes a product on its own with its users.
Resources:
Photo credits Glenn Carstens-Peters