Guest post by Riaan Kleinhans of the TAG Contributor Strategy and Technical Project Manager at ii.nz
Imagine a time before smartphones and satellite navigation, as we recount a remarkable road trip across Europe with little more than a map book. Our story mirrors the challenges faced by open source contributors who often navigate complex projects without clear guidance. Join us in exploring how roadmaps can transform this landscape, making it more accessible and inviting. From revamping repositories to streamlining issue tracking, we’ve learned valuable lessons we’re eager to share. Let’s embark on this adventure and discover the power of roadmaps in open source projects.
Roadmaps, Looking back
Ever since I was a child, I’ve had a fascination with maps. They offer insights into locations and how to reach them.
In the year 2001, my wife and I were newly married and I lived for a while in London, UK. At that time, we acquired a 15-year-old Nissan Micra from a friend for a mere £100. We wanted to see the magnificent sights of Europe and decided we should embark on a road trip across the expanse of western Europe. The adventure covered 12,000 km over 6 weeks, all while camping. It was truly an unforgettable journey.
We were travelling on a shoestring budget, armed with a well-worn secondhand copy of Lonely Planet’s “Best of Europe” and an A3-sized map book detailing all of western Europe (just imagine lack of detail) —we embarked on this escapade before the era of smartphones and satellite navigation.
One fateful Monday morning, we set off from a location just west of Madrid, Spain, destined for Zaragoza. Armed with our rather rudimentary map, we discovered that Madrid had a ring road that could take us around the city. Navigating through peak-hour traffic, we set our hearts on circumvent any time-consuming gridlock. My wife, a skilled navigator, guided me toward Madrid, yet the traffic grew denser, and we found ourselves, the lone right-hand drive car among the throng, bewilderedly surveying our surroundings. Despite our earnest efforts, we missed the ring road off-ramp by one simple lane change and a terrible roadmap. Our reward? An hour and a half mired in traffic within an unfamiliar city, armed only with an inadequate map.
Navigating open source: When you’re flying blind
This anecdote brings me to a tale about roadmaps in open source projects. My life journey led me to become involved in the work of CNCF Mentoring Working group, which is part of the CNCF TAG Contributor strategy. During a meeting in 2022, Nate Wadington, the chair of the working group recounted an encounter in which he advised an individual keen on getting involved in open source projects to explore our Mentoring working group repository. Later that day, while immersed in the repository’s work, he assumed the perspective of a newcomer, much like the individual he had invited. Viewing it through this lens, he realised that though the repository was familiar to him, it was akin to navigating an unfamiliar city without a map for a newcomer. In response, the members of the working group worked together to revamp and clean up the repository, much like readying one’s home for the arrival of esteemed guests.
Shouldn’t open source projects always anticipate the arrival of significant guests? After all, every contributor, maintainer, and leader was once a visitor themselves.
TAG Contributor Strategy roadmap: Bringing our own house in order
Upon completing this task, in early 2023, Dawn Foster brought up the concept of roadmaps during a TAG Contributor Strategy meeting, proposing that they could serve as a catalyst for attracting and welcoming contributions to CNCF projects. Thus, we explored the possibility of creating an advisory guide to aid CNCF projects in crafting effective roadmaps.
The late Caroline van Slyck was always very pragmatic, and she proposed that before we advise others on the right path, we must first ensure our own house is in order. Profound advice indeed.
Thus, we delved into the process of cleaning our metaphorical house. Like numerous open source repositories, ours had grown organically over the years, accumulating contributions from dedicated individuals. These additions were made in a manner that seemed appropriate at the time. However, it wasn’t until much later that we paused to take stock of the larger picture, organising information into more coherent categories while eliminating or updating obsolete details. We also included a diagram, crafted by Jay Tihema , that at a single glance, familiarised newcomers with the project’s components and their interrelations. While not all projects can be succinctly visualised, the maxim “a picture is worth a thousand words” still holds true.
With the repository polished, our attention shifted to the open Issues. Legacy project boards were replaced with the new Github project board, accompanied by Github workflows that automatically channelled all new issues and pull requests to the board. Subsequently, we embarked on the process of sorting through the issues. Some brilliant ideas from yesteryears had gone unattended and now some lacked relevance, while others warranted updates and an assigned contributor to nurture them into fruition. Certain issues could be consolidated, maintaining their place on the to-do list but grouped with similar tasks. During this organisational process, we recognized that certain Github labels in the repository were less descriptive than initially thought and demanded revisions. We also introduced additional labels to leverage the Views functions of the new project board, filtering issues for enhanced clarity.
Come join our effort!
Our efforts have paid off, and we’re excited to invite new contributors to our repository. They can browse around our workspace, see where we’re headed and where they can get involved.
Reflecting on the Europe map book we used more than two decades ago, and comparing it to the navigation tools my smartphone offers today, it’s evident that crafting a roadmap is an ongoing endeavour. Our project would have to continue with regular self-assessment, involving reviews of the repository, project board, labels, automation and visuals. This isn’t just about wanting things to be neat and organised. It’s more about wanting to create a welcoming space for new contributors and friends.
Our project’s Roadmapping journey was full of valuable lessons, and we’ve documented all of them to help the wider open source community. In this way, we modestly provide not only theoretical guidance but also a real-life example of our principles in practice.