Open-source projects thrive on community contributions, but one of the biggest barriers for new contributors is setting up a local development environment. With varying tech stacks, computer usage limits, and dependency overhead, how can open-source projects provide a one-size-fits-all setup?
Recently, I addressed these challenges for a free, open-source, privacy-first therapy application called Bloom. After containerizing the application with Docker, contributors were still required to host PostgreSQL data locally. While this approach was practical for backend development, it posed challenges for frontend contributors, as PostgreSQL hosting was necessary to run integration tests. To attract talented contributors, it became essential to minimize dependency overhead and align development requirements with the needs of developers. Additionally, offering flexible solutions to accommodate diverse computing capabilities was prioritized to help expand global developer accessibility.
Here’s how it worked, and the impact it made 👇
The Challenge: Lowering the Barrier to Entry
For developers interested in contributing to Bloom, getting the app running locally was often the first hurdle. Depending on their environment, contributors had to grapple with:
- Installing and configuring PostgreSQL.
- Manually populated their database with test data.
- Managing dependencies that conflicted with their existing stack.
- Adapting to Docker’s or PostgreSQL’s learning curve if they weren’t already familiar.
These issues would deter new contributors, especially those with limited system resources or time.
The Solution: Offering Flexible Setup Options 🌐
To make contributing more accessible, I configured three distinct, cross-compatible setup paths with clear documentation for seamlessly implementing each:
1. Manual Hosting with PostgreSQL:
For developers who prefer working directly with PostgreSQL on their local machine, this option allows them to host the database manually. Additionally, this lowered computer resource usage, as Docker has a high overhead.
2. Connecting a Locally Hosted PostgreSQL Database to Docker:
Some contributors might already have PostgreSQL installed and want to keep it separate from Docker. This option lets them connect their locally hosted database to the Dockerized application, bridging the gap between containerized and non-containerized setups. This also provided a compromise for computer usage and dependency overhead.
3. Running the App Entirely in Docker (with Persistent Data):
For devs who prefer a fully containerized development environment, they can now the backend and database in Docker (my personal favorite method). This approach minimizes dependency conflicts and leverages Docker-specific PostgreSQL tools. To ensure persistent data storage, similar to a locally hosted PostgreSQL database, I configured Docker volumes. With Docker volumes, this enabled both staff developers and contributors to fully containerize the application without needing to re-populate the database with each new container. Additionally, this streamlined my pull request workflow as a maintainer, as I no longer needed to manually populate the database from a forked branch when reviewing complex pull requests locally. Of course, there are caveats to this method, forked pull request tests run on my machine using Docker volumes can alter my local database, but I quickly realized I could navigate this using tmux multiplexers or docker-compose.override.yml files (that is for a future blog post).
Why These Options Matter?
This flexible setup benefits staff and community developers alike by:
- Catering to diverse preferences: Whether a developer prefers Docker or manual PostgreSQL configurations, they can choose the setup that works best for them. ✔️
- Accommodating resource limitations: Developers with lower-powered machines or network limitations can manually use PostgreSQL, while those with more resources can opt for containerization. ✔️
- Reducing dependency conflicts: Each option minimizes the risk of version mismatches or conflicts with pre-installed tools. ✔️
- Implements consistency: Regardless of the set-up developers opt for, the code remains consistent, and data is persistent. ✔️
The Results: A More Inclusive Developer Community
By lowering the barrier to entry, these setup options helped attract more contributors to Bloom and streamlined the workflow for maintainers. As an open-source tech organization focused on advocating for positive social impact, utilizing the most of limited resources is paramount for this project. With this new set-up, developers can start working on the app faster and with less frustration, fostering a more inclusive and engaged developer community. So far, contributor troubleshooting inquiries have been reduced, but this is only the beginning! Ultimately, this was an excellent learning opportunity for me as a developer advocate, and for contributors exploring Docker and PostgreSQL configurations.
Takeaways for Other Open-Source Projects
If you’re looking to improve community outreach for your open-source project, consider implementing flexible setup options like these. Providing contributors with choices tailored to their preferences and constraints, while maintaining consistency for staff developers, can make a significant difference in empowering contributors to engage.
When evaluating the onboarding flow for open-source applications, here are questions I like to ask myself:
Is this set-up causing contributors to drop of, and if so, where?
Can the gaps in the onboarding flow be resolved?
How can we provide flexible dev environment set-up options to enhance developer reach?
Thank you for reading this far! 🏆
If this post interested you, let's connect! I am always looking to collaborate with passionate technologists. Schedule a chat with me today: https://calendly.com/communaltech/coffee-chat-15-30min
Stay tuned for more, if you enjoyed this post, I invite you to follow my work on GitHub: https://github.com/kyleecodes
Top comments (0)