We run a major open-source project, Steampipe, that's spawned over 200 open-source repositories. A handful are for the core components, and the majority are for the plugins and mods that layer on top of the core. Managing all these repos demands both technical rigor and human connection. That's why Turbot combines proven engineering practices with a focus on community. Here are seven key lessons we've learned along the way.
Lesson 1: Respond instantly
Challenge: It's easy to miss issues and PRs that span hundreds of repos.
Solution: Monitor everything and alert the core team.
Lesson Learned: People really appreciate instant responses!
When a community member opens a new issue, or raises a PR, we use a GitHub action that runs a Steampipe query every hour and notifies a Slack channel when something new turns up.
When we scan all the repos we filter out members of our own organization so we can prioritize external contributors.
Lesson 2: Early communication is essential
Challenge: Contributors' ideas may not align with project goals.
Solution: Communicate early and often.
Lesson Learned: Be crystal-clear about project goals and expectations to avoid painful misunderstandings.
One memorable lesson came by way of a passionate user who opened a PR that would simplify the management of AWS credentials, but create a dependency between Steampipe and the AWS CLI. The idea was appealing, but we were adamant about avoiding unnecessary dependencies. Unfortunately we didn't communicate that stance clearly at the outset. As a result, the enthusiastic contributor invested time and effort, believing it aligned with our goals. Only later, during a more thorough review, did we spot the problem.
Rejecting the contribution at that stage was painful for both the contributor and our team. We learned the hard way that transparency and clear communication about project goals and expectations are essential from the outset. It's crucial to steer enthusiastic contributors away from efforts that don't align with the project's vision.
Lesson 3: Treat contributors like team members
Challenge: Incentivize contributors.
Solution: Prioritize external contributors and collaborate closely for quality contributions.
Lesson Learned: Being friendly, respectful, and direct fosters collaboration and accelerates progress.
Treating contributors like team members means more than just accepting their contributions. Solicit heir ideas, provide clear instructions, and help them understand what you want to be done. Don't hesitate to ask them to refine their work to meet the project's standards or goals — they will often gladly accept the challenge.
Here's one example: a user needed to specify a custom AWS endpoint, opened an issue, and worked with the core team to refine a pull request that we approved and merged.
One valuable practice we've adopted is not waiting too long to merge a contributor's mostly-complete work. People who contribute to open source projects are often busy and are donating their time. Merging their contributions, even if they require minor adjustments, acknowledges their effort and allows the project to move forward swiftly. This approach gives contributors credit for their work and keeps the momentum going.
Lesson 4: Age reports keep you honest
Challenge: Long-forgotten issues and PRs sap enthusiasm and hinder progress.
Solution: Use daily age reports to assess the "cost" of open issues and PRs and ensure systematic review.
Lesson Learned: It's painful but necessary to create age reports and regularly review them.
Daily age reports are like a financial statement for open issues and PRs. We calculate the number of days each issue has been open, sum them up, and create a running tally of "days open" for the entire repository.
This approach helps us identify and prioritize old issues that have been open for an extended period. That happened, to our embarrassment, in this case. The issue was opened last September, there was early engagement, but it fell off our radar and was only resolved a few weeks ago thanks to more systematic review of stale issues.
The age reports also ensure we stay on top of new issues and PRs to prevent them from accumulating and becoming long-term challenges.
Lesson 5: Burndown is a must
Challenge: Long-standing issues and PRs can create bottlenecks.
Solution: Dedicate resources regularly to burn them down.
Lesson Learned: Visualize trends in order to bend them in the right direction.
We aim for continuous improvement, and to do that we need to measure progress. This isn't something easily done with GitHub alone, across a large set of repos, with filters for external contributors. We use trend charts built from daily snapshots of the age reports.
There's still room for more improvement but we've made good progress!
Lesson 6: Consistency is the name of the game
Challenge: Maintaining consistency across repos is vital.
Solution: Implement benchmarks to enforce uniform settings, both public-facing and internal.
Lesson Learned: Automate your consistency checks!
Consistency is the bedrock of an efficient open-source project. To achieve it, we conduct checks across multiple dimensions:
Naming: We ensure that repository names, control names, and table names follow a standardized format.
Formatting: Our consistency checks extend to query examples, ensuring they adhere to established formatting standards.
Documentation: We prioritize thorough, high-quality documentation, including column descriptions, query examples, and credential setup instructions.
Quality: Our benchmarks include checks for tables that must handle pagination and error handling to maintain high-quality code.
Coverage: We assess whether there are enough tables to make the repository useful and ensure that columns are complete.
Repository setup: Consistency checks extend to public-facing aspects such as licenses, descriptions, tags, and social images.
Lesson 7: Documentation is king
Challenge: Users need good examples that make our software easier to use.
Solution: Expect contributions to include high-quality documentation.
Lesson Learned: When you prioritize documentation you improve usability and reduce the support burden.
Documentation isn't just an afterthought; it's the backbone of user-friendly software. Prioritizing good descriptions for the columns of tables provided by plugins, for example, often inspires redesign of those tables to make them more usable. And with quality documentation, many support questions can be answered with a link.
Be fast, friendly, and clever
When open source projects thrive it's because users bring new ideas — and contributors deliver implementations — that augment what the core team is able to do on its own. To realize those benefits at scale, you need a process that blends technical rigor and human connection. The process we've built embodies the lessons we've learned. We're confident that it helps us be better stewards of our community, but you don't need to take our word for it. You can meet our users and contributors in our Slack community and learn more about how our community works.