CockroachDB was conceived as open source software, and we are proud that CockroachDB remains open source to this day. Throughout our journey, our community has made valuable contributions to our product. Over the course of our existence, we have had over 1590 commits from over 320 external contributors across all our open source repositories. Today, we want to thank all our wonderful external contributors.
In this blog post, we celebrate open source contributions across the CockroachDB repositories, with a glimpse of how we manage contributions to our own repo. We take a closer look at the impact of external contributions on the spatial offering for v20.2 and CockroachDB ORMs. We also take a look at how we encouraged first-time open source contributors during Hacktoberfest 2020. Finally, we recognize all our external contributors and celebrate their work.
Open Source Contributions to the Cockroach Repo
The CockroachDB repo contains the core database product, where most of our contributors show initial interest. In this section, we will dive into how we encourage external contributions for the database as well as how we manage the community and reviews.
Labeling good first issues
We follow GitHub’s recommendation of regularly adding the good first issue label to issues to solicit contributions. Generally, the issues we affix with the “good first issue” label are small bug fixes or feature improvements that can be approached with minimal context.
These good first issues generally contain a small set of reproduction steps. We have found that external contributors find it easier to resolve issues that include pointers to code snippets and tests to look at in the codebase.
Our team’s extra effort to include relevant pointers pays off since these issues are usually picked up quickly by the community. Out of the 85 “good first issues” closed in the past year, 30 had been commented on or merged by an external contributor within 14 days of being tagged “good first issue,” and 50 within 30 days.
Assigning reviewers for external contributions
Members who are not part of your GitHub organization cannot request reviewers - and they may not know whom to talk to! It is important to us that all external contributions are looked at, and we do our best to ensure they get merged.
A simple remedy that any repository can use is to add a CODEOWNERS file in the GitHub repository that will automatically tag a team from Cockroach Labs. However, this is only effective if owners were declared for each part of the repository, which may not be true for bigger projects like CockroachDB.
To make sure no external contributions go unnoticed, we created a GitHub bot named blathers, which looks through issues mentioned in the PR description and tags authors or issue commenters from the Cockroach Labs organization (see example). Blathers can also automatically detect common anomalies found in PRs and suggest fixes to them (see example). Failing that, blathers will provide steps for finding help with reviewing the contribution (see example).
Supporting our open source contributors
We have ample resources for getting started with contributions, including a customary CONTRIBUTING.md file that links to the more detailed Contributing to CockroachDB public wiki page. Our community Slack channel also contains a #contributors slack channel, allowing external contributors to engage, ask questions, and follow up. Finally, we aim to actively maintain “good first issue” tickets and respond to our contributors' questions to unblock them quickly. Strong follow-up both here and on Slack generally leads to a successful external contribution.
Celebrating our contributors over the past year
Currently, we have had 333 commits from 96 open source contributors in 2020. These contributions - no matter how big or how small - have all incrementally made CockroachDB a better database. We are grateful to our contributors and would like to thank them here today:
23 Contributions: Erik Grinaker
18 Contributions: Aniket Bharsakale
16 Contributions: Dima
15 Contributions: Artem Barger, Jaewan Park
13 Contributions: Abhishek Gupta, Shinwanee, Max Neverov
10-11 Contributions: Vaibhav, Martin Besada
6-9 Contributions: Rohan Suri, Joël Gähwiler, dkorwar, Adzim Zul Fahmi, Marcin Knychała, Neeral Dodhia, Irkan
4-5 Contributions: Eugene Kalinin, Ini, Mnovelodu, Vincent Xiao, Yongyang Lai, Cyrus Javan
2-3 Contributions: Arun Ranganathan, Jay, Alina, Chanyoung Park, Girish Ramnani, Anthony Huang, glorv, James, Vipul Gupta, Hugo, Lars Lehtonen, Jason Brown, Joshua Shanks, Cyrus Javan, Amit Sadaphule, Cholerae Hu, Oleg Kovalov, Georgy Savva, Hiep Doan, Himanshu Chawla, Kumar Akshay, Matthew Rathbone, Xuhui Lu, Yanxin
1 Contribution: Arun Mittal, BurtonQin, Dominique Rau, Sergei Gorjunov, Terry Wong, Nitesh Koushik S, Richard Tweed, Tayo, UdokaVrede, Adrian Popescu, Antoine Grondin, Latern4ever, Ben McCann, Clucle, Damien Hollis, Deven Bhooshan, Andrew Grosser, Ian Cowley, George Papadrosou, Gabriel Jaldon, Gábor Liptak, Harsh Seth, heidawei, Joshua M. Clulow, jieniu$, Jake Rote, Jaime Soriano Pastor, Juan Carlos, Katie, Kirk True, Lance Rutkin, Masroor Hasan, Michael Meng, Omar Bahareth, Petr Jediný, Poh Zi How, Pratik Sethi, gary rong, Ruixin Bao, SaintMalik, Sam Ward, Shaker Islam, Tancredo Souza, Teiva Harsanyi, Themis Papavasileiou, Tom Milligan, Vincent Thiery, TAKAHASHI Yuto, zhiqiangxu, Zain Malik
Impact of Open Source Contributions to CockroachDB’s v20.2 Spatial Offering
Open source contributors have been instrumental in the large number of spatial functions we were able to make available in CockroachDB’s spatial data offering. So far, we’ve had 59 commits from 15 contributors covering over 70 spatial functions out of the 249 we have available.
This section will dive deep into how we corralled these contributions and celebrate the contributors.
Maintaining Issues for Spatial Functions
For our spatial offering, our aim was for CockroachDB to be able to be a drop-in replacement for PostGIS, an extension of PostgreSQL providing spatial functionality. This is in line with our goals for CockroachDB to be a drop-in replacement for PostgreSQL.
We knew this would be a daunting task. In spatial functions alone, PostGIS has over 300 functions for vector geometry, covering anything from encoding/decoding to coordinate clustering. We were understaffed for this lofty endeavor and would have had to cut scope for our first spatial release.
However, we realized that spatial functions were easily parallelizable once we had a foundation for manipulating spatial data. We also knew that we had a keen community eager to contribute!
Once we implemented a few basic functions, we compiled a spreadsheet of all functions to be implemented. Then we created a tool that converts the spreadsheet entries into GitHub issues based on an issue template. The template contains detailed instructions on where to begin, what changes need to be made, where to add and run the tests. The tool also updates the spreadsheet after an issue is closed.
We decided to tag issues we considered suitable for external contributors as “E-Easy.” As over 140 issues were deemed suitable, it would have polluted the good first issues page for contributors looking to contribute something outside of spatial. However, we did create a meta-issue with the good first issue tag to make the spatial issues discoverable.
With the practices highlighted in the earlier section, we ensured that all contributions were reviewed and issues and inquiries were responded to promptly.
The results - 59 commits implementing over 70 functions from 15 contributors - speak for themselves. Altogether in v20.2, we managed to implement 229 functions, a fair way towards the 300+ functions PostGIS has today. Our efforts in creating the spreadsheet, syncing with GitHub, and providing implementation details paid off.
Celebrating our spatial contributors
We are extremely grateful to all our contributors on these important spatial data features. They are, by order of contributions:
19 Contributions: Erik Grinaker
6 Contributions: Jaewan Park, Arthem Barger
5 Contributions: abhishek20123g, Vincent Xiao
4 Contributions: Marcin Knychała, Azdim Zul Fahmi
3 Contributions: Cyrus Javan
1 Contribution: manhhiep92, himanshuchawla009, Themis Papavasileiou, Michael Meng, Deven Bhooshan, Arun Ranganathan, ArjunM98
CockroachDB’s spatial offering would also not have been possible without Tom Payne. We found that Tom’s open source go-geom library provided the best solution for manipulating spatial features in Go. Tom’s quick reviews for our patches and guidance for features were instrumental for our spatial offering. Thank you!
Our spatial functionality today would not have been available so early without the quality contributions from the individuals mentioned above. Thank you for your contributions!
The Open Source Community’s Impact on CockroachDB’s ORMs
Having a great database is one thing, but just as important is being able to connect to it and use it within an application. The open source community has been instrumental in getting existing object relational mapping (ORM) software and other tools to work with CockroachDB. We highlight and thank them here.
Cockroach Labs maintains several open source projects built internally by engineers to integrate with ORMs. These “dialects” (which sometimes are also known as “adapters”) tell the ORM how to create SQL queries that are compatible with CockroachDB and can also provide other helpful functionality like automatic transaction retry logic. We maintain dialects or helpers for Django, SQLAlchemy, Sequelize, ActiveRecord, and various Go libraries. It would be impossible for us to stay on top of all of these on our own, so we are immensely grateful for our community of developers who report issues with these projects or submit bug fixes and improvements. Thanks to the following contributors!
16 contributions: Christian Köhn
6 contributions: adamgee
3 contributions: Zac Pullar-Strecker
2 contributions: Georgy Savva
1 contribution: Christian Kulpa, Dominique Rau, Terry Chun Wong, Danilo Cabello, Garvit Juniwal, Masroor Hasan, Neeral Dodhia, Ronan Cherrueau, Paul Colomiets, Xuhui Lu
In addition to projects that we maintain, we’ve also benefited tremendously from all the hard work done on tools that are supported by others over the past year.
The teams at Hibernate, Flyway, and Liquibase have added first-class CockroachDB support into their projects, and our developer community has already contributed directly to those projects as well. A few other tools with maintainers dedicated to supporting CockroachDB in their projects (and who work directly with us to identify fixes and improvements within CockroachDB) are TypeORM, .NET EF Core, Elixir/Ecto, knex, and Beekeeper Studio. Having an ecosystem of tools like these is key to our success so far, and just as importantly improves the lives of developers who work with CockroachDB.
Hacktoberfest 2020 Encouraged First Time Open Source Contributors
While we get amazing contributions from experienced developers, we know that the CockroachDB repo can be overwhelming and intimidating to new contributors. To lower the barrier to entry and welcome first-time contributors, we participated in Hacktoberfest 2020 and designed beginner-friendly projects for the participants.
We identified and tagged beginner-friendly issues in our code and docs repos and also created a sample applications repository for folks to contribute CockroachDB apps using a language/framework of their choice. The goal was to allow contributors to use a technology they were comfortable with while learning a new technology (CockroachDB) and helping our open source project build out our sample apps repo.
The result: 29 CockroachDB apps created and 33 Docs issues closed!
Celebrating our External Contributors Going Forward
We acknowledge all CockroachDB external contributions in the release notes for each release - but this does not cover contributions to other repositories. To recognize our external contributors in a more general fashion, we have set up a Hall of Fame with statistics on all external contributions to CockroachDB. The page will list all our external contributors over the course of our history and will be updated regularly.
Contribute Today!
At Cockroach Labs, we are proud of our external contributors and always keen to welcome new contributors. For keen contributors out there - join the fun! To get started:
For contributing to CockroachDB: Follow our contribution guide, which contains instructions for getting CockroachDB set up, and look for issues labeled “good first issue”.
For our documentation, check out our Docs Contribution Guide.
For our ORMs, check out the READMEs in Django, SQLAlchemy, Sequelize, ActiveRecord, and various Go repositories.
If you are ever stuck, feel free to contact us on the #contributors channel on our community Slack - we’re always happy to help!
And if you are interested in becoming a full-time CockroachDB contributor, we are hiring!
