The Road Less Starred: Lessons Learned from My Markdown Twain Library

Introduction

As a seasoned software developer deeply immersed in the world of Android, Kotlin, and Jetpack Compose, I’ve always been driven by a passion for creating tools that empower developers. My journey with Markdown Twain, a WYSIWYG Markdown editor for Jetpack Compose, has been a testament to this passion.

Until our recent acquisition by Bending Spoons, I served as the tech lead for Kotlin Multiplatform development at the social site Meetup. Knowing that I would be speaking about our Kotlin Multiplatform experience at KotlinConf last year, I hurried to release my new Markdown Twain library as open source.

I debuted this project at KotlinConf 2023 in Amsterdam, filled with excitement and high hopes. Today, I want to share a candid tale about the unforeseen hurdles I encountered along the way and the lessons they taught me.

The Birth of Markdown Twain

Markdown Twain was born out of necessity. While working on the Meetup for Organizers app, I realized we needed a rich text editing solution in Jetpack Compose. With no existing software libraries, I took on the challenge and developed Markdown Twain using a mere two weeks while our iOS app was able to simply use an off-the-shelf solution in SwiftUI. Fueled by the excitement of showcasing this project at KotlinConf 2023, I rushed to release it as open source.

The Rush to Release

In the whirlwind of preparation before my flight to KotlinConf and my eagerness to share my creation with the world, I made oversights in the packaging and configuration of Markdown Twain. These weren’t glaring errors, but rather the “works on my machine” kind QA knows well that can quietly slip through the cracks when you’re racing against the clock.

One of my first missteps involved the Maven publishing code. I had set it to depend on a Gradle variable for the Maven username and passphrase. To safeguard against either forgetting these or hardcoding them into Github, I programmed an error alert into the setup. Unfortunately, due to a misconfiguration, this error triggered for all tasks, not just the publishing one. On my machine, everything seemed fine because I had set an environment variable that bypassed this issue.

Moreover, I inadvertently obscured another error by using my library as a direct project dependency in testing, instead of pulling it from Maven Central as others would. This meant my example code was looking directly at the source code, not the packaged version. When I finally switched to using Maven Central, I was greeted by runtime errors due to missing symbols—caused by ProGuard processing on the release artifacts.

The Discovery of Mistakes

It wasn’t until months after the launch, when I transitioned to a new laptop and temporarily lost access to my Maven Central keys, that the true impact of these issues became apparent. Unable to swiftly address the problems, I was forced to confront the consequences of my haste.

However, this setback proved to be a turning point. I embraced the challenge as an opportunity to learn and improve. I adopted the robust “com.vanniktech.maven.publish” Maven publishing plugin to better handle Maven credentials and error management.

Lessons Learned

My experience was humbling and enlightening. No one told me that my open source was not working as documented. I had to test everything again when the expected stars and engagement did not materialize.

I found, yet again, that common problems in software development are not simply bugs in code, but also often issues in packaging.

My journey to resolve the missing symbols issue taught me the importance of community knowledge sharing—something I found lacking as I navigated this challenge mostly alone. I found no blog articles or StackOverflow posts mentioning the ProGuard issue in Maven artifacts. Since I was looking specifically at articles about Compose libraries, no one had spoken about this common issue. I only discovered it as a result of comparing a variety of build.gradle files for successful Compose libraries.

Moving Forward

With the immediate technical issues resolved in version 0.3.2, I’m now setting my sights on a significant overhaul of Markdown Twain. I’m planning a 1.x version which should support Compose Multiplatform, making the library more versatile across a wide range of applications. It will also no longer wrap Android Views and should offer better performance.

To my fellow developers, I extend an open invitation to join me on this journey. Your insights, bug reports, and feature suggestions are invaluable in shaping the future of Markdown Twain. Together, we can build better software, learn from each other’s experiences, and foster a supportive community.

Conclusion

The story of Markdown Twain is one of passion, pitfalls, and perseverance. It’s a reminder that in the world of open source development, challenges are inevitable, but so is growth. By embracing our mistakes, learning from them, and leaning on the strength of our community, we can transform setbacks into stepping stones towards creating something truly remarkable.

So, let’s embark on this journey together. Visit the Markdown Twain GitHub page to get involved and let’s build a tool that empowers developers everywhere.

Have you ever messed up delivering an open source project and spotted it much later? I’d love to hear about it in the comments.


Comments

Leave a Reply

Your email address will not be published. Required fields are marked *