Improving your Open Source tools to save time — Automate things 1
I have been maintaining react-native-webview for more than a year now, let’s see how the repository is set up to achieve a lot with as little interaction as possible. This article is about Javascript projects but some of the principles are probably applicable to any programming language.
I. Use types
Use types in your library code with either TypeScript or Flow. JavaScript is a fantastic language to get tons of things done, but when doing open source, it can quickly become very painful to maintain.
Example of types on the react-native-webview repository
Types have several benefits:
- Documentation living inside your codebase
- Tests inside your codebase
- Developer experience is way better (autocompletion and other perks…)
While it can be painful to convert all your codebase at once, you don’t have to and you can add them incrementally. I do recommend migrating big chunks when there are not too many pull requests opens if you don’t want to scare away contributors.
Recently, react-native-cli asked for help to convert to TypeScript and the community response was awesome! Good job everyone ❤️
II. Release often and keep a changelog
If you want to get people involved, they need feedback on what they do and they want information on what other people do.
To achieve these two goals, I decided to use semantic-release. It is a tool that will take care of several things for you:
- Increment your version number following semver
- Generate the changelog
- Release the new version on NPM
- Close and comment issues / pull requests related
Let’s see what’s great about each of these.
SEMVER — Anyone’s addict to being up to date best friend 👭
It is a versioning convention that informs you about what kind of change was intended between the new release and the previous one. You are never 100% safe when upgrading, but if everything goes according to plan you should be good 👍.
Semantic-release will parse your commit messages and decide to release the correct version.
Some example from webview:
- fix(iOS): hideKeyboardAccessoryView on iPads
The previous version was 7.2.6, this only contains a fix, the new version will be 7.2.7 and everyone is safe to update. ✅
- feat(android): Expose cacheMode property
The previous version was 7.2.8, this contains a feature, the new version will be 7.3.0 and everyone is safe to update. 🚀
- fix(iOS): UIWebView Removal but inside the commit description it says BREAKING CHANGE: UIWebView has been removed.
The previous version was 6.11.1, this contains a breaking change, the new version will be 7.0.0 and everyone is not safe to update. But maybe you are 😍.
An automated changelog — Happy users 🎉
By parsing your commits, semantic-release can generate a changelog that your users will be able to access under the release tab on Github.
That’s the best place for anyone to go when having doubts about what’s new in a version.
Release after every merge — Smaller updates, faster feedback ⚡️
Every time we merge a commit on react-native-webview master branch, our CI will release a new version. This provides a great experience for both users and contributors, who are both happy about not needing to wait to get an update. As a maintainer, it also saves me so much time. This also makes it easier to pinpoint where regressions might come from since there is usually only one commit to look at.
By doing that, after a year, we released 123 versions of webview in a year, but only had 5 breaking releases, most of which were only affecting few users but we don’t joke with SEMVER. 😊
Automatic issues and pull request updates — More goodies 🍭
After every release, a nice bot will come and comment on related issues or pull requests. This allows users to get notified that their issue has been solved and that their pull request is merged and available on NPM.
As a bonus, there are many plugins you can use with semantic-release. For example, every time we release a new version of webview, a bot comes and updates the version inside the package.json file and commits it directly.
Setting up semantic release takes a few minutes and saves hours. 🕐
yarn add -D semantic-releaseAdd tokens from Github and NPM to your CI.
Make sure your CI runs the following command after your tests are successful on master:
yarn semantic-releaseDone 🔥.
Some interesting reads:
- https://semantic-release.gitbook.io/semantic-release/
- https://semver.org/
- https://www.typescriptlang.org/
If you want a part 2, please let me know by commenting/clapping the article, and feel free to share it.
Thanks for reading!
