Takeaways

• “Development Setup” sections in a project’s README or CONTRIBUTING instructions are a barrier. The more complex the setup steps, the more likely someone walks away and does not contribute.
• Automation is a great first step towards lowering the barrier of entry, but global dependencies may interfere with individual projects.
• Ideally, a project lives in its own sandbox, completely isolated from anything else.
• Focus on project onboarding as an interactive experience rather than text to read and commands to copy & paste.
• Move away from “my long-lived dev environment” to automated, ephemeral environments.

The challenges with “Development Setup”

Contributing to an open source project comes with a certain level of overhead. First, you read the project’s README and/or CONTRIBUTING files. Next, you copy & paste the provided commands to execute them in your local terminal. Lastly, you run the project’s test suite to make sure everything is set up correctly.

In an ideal scenario, the above process works as advertised. However, it is quite possible you run into incompatibility issues, for example when your installed version of Java doesn’t match what the project expects or when specific OS libraries are required.

While the above focuses on the first-time interaction with a project, the overhead continues if you haven’t contributed to a project for a while and the dev setup has changed. It requires you to follow the latest steps again to update your local environment. Alternatively, you could delete the local project folder and start from scratch.

Automation and project sandboxing

“Automate the dev setup with a setup.sh (or similar) script”, you say. This is a great initial step to improve the first-time onboarding experience. Depending on how sophisticated the script is, it can be run repeatedly to keep one’s development environment updated. With that in place, you can contribute to an open source project once every few months and the script saves you time to keep your environment updated.

A challenge with scripts like that is to make sure they are up-to-date. Project maintainers are unlikely to run a setup script frequently to make sure it still works, which leads to a broken onboarding experience for new contributors when they run into issues with the script.

Another area where a setup script falls short is when it comes to globally installed dependencies, such as the installed version of Java or OS-level libraries. It also gets a bit trickier when you want to support any kind of underlying operating system as you now have to ensure the script runs on Mac OS, Linux and Windows.

To deal with that in a seamless way, this is where containers come into play. Hear me out though, there is more to it than “move your development environment into a container”. Many have tried that and it can feel laggy or not as efficient as developing outside a container.

It is not only about developing in a container, but more so about the fact that containers can be created and deleted with minimal overhead. A maintainer of an open source project makes sure the development container has the necessary libraries installed at any given time since they use the container to develop the project daily. No matter who wants to contribute, all they do is start a new container and begin their work. This is an up and coming concept, but what if we took this a step further? What would a development environment setup of the future look like? Read on to explore some ideas in the next section.

Interactive project onboarding

It is increasingly common for web-based applications to provide an interactive onboarding experience, wizard-like step-by-step instructions of how to use the product. By the end of it, you actively used the product and have a better understanding of how to interact with it.

What if onboarding to an open source project were like that (or any software project for that matter)? Imagine contributing to a project were as simple as clicking a button to start a development environment in a new browser tab. The underlying system prebuilds a container image for every code commit, so by the time you start up a new, ephemeral dev environment, you are ready to contribute. It could even run the project’s test suite to put you at ease that everything works as expected. Why stop there though when the system could also automatically start the application with a debugger attached.

If it is your first time to work on that project, a wizard guides you through what you need to know to effectively provide your first contribution. If you previously contributed, you may see a “What has changed” dialog to inform you of any noteworthy changes.

Once you added your contribution and opened a pull request, you simply close the browser tab and the environment will delete itself after a short while. That process repeats for each of your contributions, but also for anyone else who is interested in the project.

Conclusion

We use containers to run production applications in a well-defined, sandboxed environment to avoid surprises and the well-known “It worked on my machine” situation. We also automate CI / CD pipelines to have a predictable behavior when code is committed.

When it comes to development environments, we have not yet achieved the same level of sophistication, automation and predictability. This causes unnecessary friction, not only in the onboarding process, but also for the ongoing maintenance of a project.

It is time to look at our development environments and let go of the “one long-lived local development environment” and move to automated, ephemeral development environments. If we as an industry tackle that well, this will ultimately lead to easier project onboarding and higher engagement in open source contributions.

Join the cloud native community at KubeCon + CloudNativeCon Europe 2021 – Virtual from May 4-7 to further the education and advancement of cloud native computing.