The MariaDB contribution process: a step by step guide.

Written by Written by Georgi Kodinov Leave a comment on The MariaDB contribution process: a step by step guide.

Inspired by my VERY long presentation on the topic at FOSDEM26 I thought I’d say a couple of words on how the contribution process works.

Contributing changes to MariaDB server is easy because it follows industry best practices: it’s using “normal” GitHub pull requests. Note that I’m working for the MariaDB Foundation. As such, “normal” for me is doing everything in the open, for everybody to see and participate. And all of the communication around the contribution (including the code review) is happening in that same pull request and is public. Until the intended end of the process: merging the pull request into the repository.

Steps in the contribution process

Step Zero: Read up

If this is new to you, or if you’re new to the project the BEST way to start is read up on how to do it. CONTRIBUTING.md is a great start. It even comes complete with a dynamic list of easy tasks if you need some inspiration on what problems to try your hand on.

At this point it’s natural to have questions too that would need somebody to answer. I’d personally recommend our zulip chat: this is what most teams are using nowadays anyway. But, for the traditionally minded people, there’s also the mailing lists.

When cooperating with others it’s important to speak the same “language”. Our language here is the coding standards document. Learn it, live it, love it!

Step One: Pick What You Want To Do

The best advice I can offer here is: pick something that is both fun and important for you. People are most productive when they are happy about what they do. Make sure you pick a task that “speaks” to you. It can be many things. And they are all important.

It can be about finally taking the time to analyze, reproduce and report this unexpected effect you’ve been seeing while using the product. Filing bugs is how to go about it.

Even more challenging (and more rewarding) than that can be trying your hand at actually providing a fix for an issue.

Or you could go one step further and share your idea about a neat new feature that might help you.

Even just voting for an existing idea in Jira helps!

BUT, if you want the hard stuff: then implementing a whole new feature is as hard as it gets. Please first make sure it’s something that the rest of the people working on the product can live with of course. Saves a lot of extra work down the road if you communicate early and communicate often. You do that by making sure there’s either an existing Jira or by creating a new one describing the idea. Once you have the description it’s a good idea to communicate it with the rest of the developers.

You could approach the area from the opposite direction also: spend some time to test the development versions and report back on how they “drive”. And whether the new features in them work as advertised. No great software has ever been developed without great many tests of its workings.

All and all: whatever you pick, there’s always prior work! Reviewing what others are doing will help you. And can also help the project too. Reviewing other’s pull requests is not something that requires secret knowledge. They are all public on GitHub. So feel free to join the conversation too.

Step Two: Work on your selected contribution

For brevity, I’m going to cover the pull request development process from here on.

Having spent years doing iterations of this for fun and profit, the best summary of this process I can offer is from the Chronicles of Amber book series:

While traveling (shifting) between Shadows, they can alter reality or create a new reality by choosing which elements of which Shadows to keep or add, and which to subtract, eventually arriving at their chosen destination

https://en.wikipedia.org/wiki/The_Chronicles_of_Amber#Premise

In more mundane words:

  • Understand (and document) exactly what you want to achieve
  • If need be, make a plan on how to achieve it
  • Keep doing changes until you think you have achieved it. Add tests as needed.
  • Compare the result with the original plan. Make sure everything is tested and testing is repeatable.

This mechanics of that are cloning the repository, making a branch for your work, building it and then authoring and pushing one or more commits into the branch.

Step Three: Submit the Pull Request And Get It Reviewed

Submitting a pull request is well described in the GitHub docs. For the MariaDB server, it needs to land in this list.

Step Four: The Preliminary Review

This is where I come in! I make sure that the newly submitted PR:

  • Has a Jira describing it and the Jira:
    • is quoted in the PR’s heading
    • is in the right state
    • is assigned to myself (as the next in line to review it)
  • The contribution is legally acceptable (we have a bot to check it, so please pay attention at what it says).
  • The coding standard is followed
  • The pull request, at least on the surface (and to my limited knowledge), is doing what it says
  • Is properly tagged as “External Contribution”
  • Is in the right state (open)
  • And is submitted against the correct branch
  • All the buildbot tests are passing
  • Is based on a recent commit

As a result of that I may have some comments. That may result in several iterations of changes. Moving the state of the PR between “needs changes” and “review needed”. Hopefuly to “preliminary review done”.

So please be active and try to keep up! I’m hard at work trying to avoid stale PRs. And I am aiming at reasonable turnaround times for this step.

Step Five: “Final” Review

When I’m good with the primary review, I will solicit a review from a domain expert. A “final” review for short. This is signified by the said domain expert being assigned as a reviewer to the pull request and the Jira moved to “in review” and assigned to the reviewer.

Note that domain experts come in REAL short supply. So response times here can vary greatly! I will do my best to honestly communicate these with you. And help you in your communication with the reviewer if they are not responsive.

But the executive summary is that it might take some queueing time. Depending on the complexity and the quality of the pull request of course.

The result of this step hopefully is an approval of the pull request. This is signified by moving the pull request to “Approved” state. And the Jira to “Approved” state and re-assigned to me.

Final Step: Push, Push, Push!

This is where the process ends. I make sure the pull request is mergeable, all the tests are passing and it’s been rebased on a recent commit from the target branch.

Ideally, at this point, I would just click the “Merge” button on GitHub and say “Thank you” again!

And possibly enter you into the next “contribution of the <period>” vote. For a chance to receive even more recognition and some very cool badges, if you win!

The Future

If you’ve read that far, THANK YOU! It’s ok to stop reading now. But, for the curious minds, I wanted to share some of my own thoughts on how to improve the process and make it more visible.

The first theme is of course visibility. I would like to end up with some dashboards and/or metrics for the various parties: the submitter, the preliminary reviewer(s), the final reviewer(s) and the project leadership. These should make their lives easier. And make them happier to participate. I have some ideas on what these might be. But, in the spirit of the true open source, I do take contributions even for these! There’s some open source project management for you in a nutshell 🙂

The second theme I’d like to mention is automation. I’m hoping the volume of contributions to increase (and YES, I’m looking at you :). This will mean that the current manual steps might become bottlenecks. I am hoping to create automation scripts around this. For example, I already am doing automated tagging of the incoming pull requests. But there’s definitely more automation to be added. Did I mention that I’m taking contributions?

Overall: working with the community is not very dissimilar to working with a (hopefully) very large development team. So it might benefit from some of the modern day tools and technologies. But, most importantly, it should remain easy to get to and fun!