Open-sourcing Transition - a lesson learned

February 8th, 2018

2018, a new year that brings many new opportunities for us to create apps that make you smile ;) At the beginning of 2017 we looked at what we could do to expand our horizons, try new things and at the same time improve the brand awareness of Touchwonders. This blogpost is about one of the ideas we put into practice; contributing to the open-source community.

The plan

At the time, “going open-source” was a concept that was buzzing around at Touchwonders. Kickstarter had just open-sourced their iOS and Android apps, and Artsy had recently enlightened the world with their “Open Sourceby Default” approach. We thought; we should do something with that too! We predicted that open-source would provide a number of benefits:

  1. It could exhibit the quality of our code, serving as a business card for Touchwonders;
  2. It would therefore demand of us that we write all our code to the best of our abilities, not permitting anything less;
  3. Our code would be open for input and feedback from other developers, allowing us to learn from others and together improve the quality of the code; We felt that we were only consuming open-source, mainly through Cocoapods. Now we wanted to give something back.

To be honest, Cocoapods was pretty much our primary window into the open-source community. Although we all had experience in mobile development, we were beginners when it came to open-sourcing our own projects. So we knew we wanted to start by taking small steps.

We have been using a number of internal frameworks in multiple projects through a private Cocoapods spec repo. We figured that open-sourcing such a framework would be a suitable first step for Touchwonders. Unfortunately, all were still written in Objective-C, some were tailored quite specifically to a number of our projects, and others were just small practical components written to not repeat ourselves. There wasn’t much that would fit one of our credos “Deliver wow in everything you do”, if we were to make it open-source at this point.


More recent projects were all written in Swift, which was regarded as “the new standard”. Our collective forte at that time was crafting beautiful custom interactive animations and transitions. Particularly interactive interruptible custom view controller transitions, a subject that was covered during WWDC’16 and one on which we had recently spent one of our monthly team DevSessions, collectively playing around with the concept. So we figured we might distill this into a new framework, one that would be state-of-the-art and could be used in future projects.

Interactive interruptible custom view controller transitions are quite involved. The sample code project provided by Apple illustrates only a single use case and – in style with most other Apple sample code projects – doesn’t spend too much attention on separating out all required components into a decent architecture. As such the concept is relatively hard to fully grasp and implement correctly. This was what our framework should focus on: making it easy for developers to implement such transitions by defining a number of clear building blocks, each with its own well defined responsibility.

As the term “interactive interruptible custom view controller transitions” suggests, there are three aspects to what the framework should cover:

1. Custom view controller transitions

iOS offers a number of built-in view controller transitions. The most well known are: when you push to the next view in a navigation controller, the next view slides in from the right (vice versa when navigating back) when a view is presented modally, sliding in from the bottom Apple allows developers to customize the animation of such transitions. This is relatively straight-forward and one might not need a framework for that.

2. Interactive view controller transitions

iOS includes the “interactive pop” transition, allowing users to navigate back in a navigation controller by edge-swiping from the left. If you want to add interaction to a modal or tab bar transition, or change the interaction of navigation transitions in a navigation controller, there are a lot more components involved. Using a framework to ease this would be perfectly valid.

3. Interruptible view controller transitions

This kind of transition is not so obvious. An interactive transition has two phases: animation and interaction. Either you are moving the transition back and forth through a gesture, or it is animating towards the and or rolling back to the start. Allowing the transition to be interruptible means you can interrupt the animation phase and interact with the transition from that point on. Apple’s sample code project illustrates this through a Photos app, in which the transition from a fullscreen photo back to the photos overview animates the photo getting smaller and moving it towards its position in the overview. The user can initiate this transition interactively by dragging the fullscreen photo downwards. When the touch is released, the photo animates towards the overview. However, the photo can be “grabbed” again during this animation, allowing you to move it around, effectively scrubbing the transition back and forth.

You will not encounter such kind of transition very much. There are two good reasons for that: it is only really possible since iOS 10, and it involves a lot of well-orchestrated components.

These three aspects follow each other. It begins with customizing a view controller transition. Then you make it interactive. Then you make it interruptible. With these three steps, the complexity also increases. We figured that our framework should provide progressive disclosure, allowing the user to figure out how to use the framework by allowing them to take one step at a time. These steps are:

  1. Defining the animation of the transition
  2. Defining the interaction of the transition
  3. Defining the animation and interaction of a shared element

Step 3 probably needs some explanation. The “shared element” is the element that moves from one view to the other during the transition. In the case of the Apple sample project, this is the photo that moves from its detail view back to the overview. By virtue of its existence, the shared element allows the transition to be interruptible.

Each step introduces just a few new components that need to be specified, each with a clear responsibility. The heavy lifting of tying these components together and orchestrating the initiation of a transition and switching between animation and interaction is all done by the framework. And so, “Transition” was born.

transition components overview

The release

We released Transition on March 15th 2017, a few hours before we presented it at the monthly CocoaheadsNL meet-up. Initial reactions were conservatively positive, but it is understandably not so easy to grasp the entire framework and the concept it tries to alleviate in less than 40 minutes.

In the days that followed, we approached a number of iOS mailing lists, and saw Transition being covered in several of them within a few days:

indie iOS focus & iOS dev weekly

Within a few days, Transition hit the #1 spot in GitHub’s “Trending Swift projects today” list. Shortly after, Touchwonders was listed #2 in their “Trending Swift developers today” list:

no. 1 trending swift project / no. 2 trending swift developer

Within a week, Transition had been rewarded with over 500 stars on GitHub. Less than a week later, it reached a thousand stars!

a 1000 stars on GitHub

With these numbers, it is safe to say that Transition was received well 🎉


The metrics available through Cocoapods showed a continuous interest in the project and the quality rating that Cocoapods gave Transition was pretty good. We considered Transition to be a success. Although tapering off, GitHub stars kept adding in the weeks after that. We were filled with joy, proud of our achievement but also had to get back to work.

As mentioned earlier, we figured we could use Transition in future projects but we didn’t have a suitable project yet. We had many projects in which all transitions were already implemented, but they were all written in Objective-C. And overhauling these projects just for the Transitions framework would be too much.

And then the first issue was reported on Transition’s GitHub page. It wasn’t really an issue: the reporter had seen one of our example videos on the Transition homepage that demonstrated a Pinterest-like interactive transition, but this wasn’t included in the actual project examples. He wanted to know where it could be found…

This example project had a few hard-to-tackle bugs that we still had to address, but in the meantime our clients’ projects were requiring priority. Admittedly, it wasn’t the smartest move to already include a video of it on the homepage but we realized we had todo something with the issue and squeezed in a few hours to investigate the issues for this project further.

Unfortunately the developer who initially created the example project left Touchwonders making it even harder to properly address the Pinterest-example. We decided to admit it’s not perfect yet, but committed it in a separate branch on the public GitHub repo.

In the months that followed, another three issues were reported. These were indeed proper issues like glitches, disappearing views & stuck transitions. This was bad. Although one might argue that it is not necessarily our responsibility to immediately fix these issues, we felt that they illustrated that some things just didn’t work properly. Things that would have become apparent to us much earlier if we had been using Transition in a production app ourselves. But now again, as was the case with the Pinterest-example, priorities had to be first on client projects instead of what had essentially become our pet project, Transition.

It took several months before some spare time became available and all open issues could be properly addressed. By then, the joy of occasionally looking at the amount of stars (1856 by now) had made place for the dread of opening Transition’s GitHub page and seeing that tab stating there were open issues…

A lesson learned

Not all reported issues are equal. One could argue that some of them are merely a request, as was the case for official Swift 4 support that was recently reported. Although it is polite to quickly provide an answer, it is not necessary per se to immediately act on such requests. Also, an important aspect of open-source is that it allows those who use your code to also contribute and help fix issues when there is a need for it.

When publishing a framework like Transition however, you provide people with a framework that they can use. In doing so, their work becomes dependent on it. Issues that arise can potentially be a real problem. We have realized that not actively using your own open-sourced code increases the chance of losing focus on its development. Priorities shift and addressing reported issues becomes hard. As our initial intention was to get more involved in the open-source community, we felt that we should have maintained our project with more priority.

2018 is a new year with new opportunities. And we are looking forward to finally including Transition in one of our own projects. Besides we have several ideas for new frameworks and libraries that we’d love to share with you. But this time, you’ll have to wait until we have integrated them into one of our own projects first! ;)