Contributing Code to MySQL

Participation from the contributor community is an important factor in the success of the MySQL open-source project. There are many ways to contribute to MySQL, and this page describes primarily code-related contributions.

As we gain more experience, absorb more contributions and receive feedback from the contributors, please expect some modifications to the contribution system described here.

Getting Set Up

Your first step in getting involved with software development for the MySQL project should be to join discussions and notification mailing lists relevant to your area of interest. The Internals Mailing List in particular is the central point for discussions related to MySQL Server software development. Certain sub-projects have their own mailing lists, however, as shown on the mentioned web page.

Also, depending on your intended level of involvement, you should sign up for a centralized Oracle user account, which gives you access to the discussion forums, the MySQL bug database, and other MySQL services.

Some contributors may also wish to sign up for a Launchpad account to be able to use MySQL on Launchpad. This is especially useful if you plan to host larger branches of your own on Launchpad.

MySQL uses Bazaar as its version control system. If you plan larger projects or more frequent contributions, you should install Bazaar and familiarize yourself with it. The Bazaar page links to various helpful resources to get you started, while the MySQL Bazaar Howto provides some concrete advice on how to work with the MySQL Server source trees.

Finally, the #mysql-devIRC channel on Freenode can be used for discussions related to MySQL development.

Paperwork

If you expect to make code-related contributions, you must sign and return the Oracle Contributor Agreement (OCA). Without an OCA on file, Oracle cannot integrate your contribution into the MySQL code base or engage in extended discussions on proposed patches. The OCA gives Oracle and the contributor joint copyright interests in the code: The contributor retains copyright while also granting those rights to Oracle as the open-source development project sponsor. The OCA is applicable to all products and projects owned or managed by Oracle; signing it once means you can contribute code to any Oracle-sponsored open-source project. More detail, and the OCA itself, is available on the Oracle Contributor Agreement page.

If you have previously signed and returned the OCA (or the former Sun Contributor Agreement) for a different project, you can contribute to the MySQL project under the same SCA/OCA. If you have previously signed the MySQL Contributor License Agreement (CLA) , you must now sign and return the OCA instead. All contributions to the MySQL project from now on require that the contributor sign and return the OCA.

To be able to store the OCA and match it to you, we require that you have a MySQL.com account. This account gives you access to important MySQL development resources (see above), so it is almost essential to have this account anyway if you are contributing to MySQL development. On the OCA form, enter “mysql.com” for the project name/project website, and your MySQL.com account handle (your e-mail address) for your username.

Finding Projects

You can get a sense of what work is being done by others by following the mailing lists and the bug-tracking system. After you have a better idea of what you would like to do, you can search the bug database for bugs or feature requests you want to work on and see if someone else is already working on an idea you have had. The MySQL engineers will already have identified a number of bugs in MySQL software. There are always many bugs which are small and self-contained, and as a starting point, we hope that you will be interested to work on some of these.

If you have an idea for a new feature, or have found a bug, you can report a Bug in the bug-tracking system. Others can then work on fixing the bug or on the feature. If you want to work on the bug or feature request you filed, indicate that you would like to do so when you file it.

New contributors are naturally encouraged to start with fixing small bugs to get familiar with the contribution process and the MySQL code base.

When you decide to work on a completely new feature or one already noted in WorkLog for the MySQL server or tools, the process is mostly identical to the one for fixing a bug, but the Code Review Process probably involves more developers, to ensure quality feature patches that adhere to the MySQL Internals Coding Guidelines. In any case, make sure to contact the MySQL developers and discuss your proposal via the Internals Mailing List before working on the implementation!

Submitting a Patch

If you have a patch for an existing bug or feature request, attach it to your bug report. (If there is no corresponding bug report yet, create one.) Add the tag "Contribution" to the bug report, to make sure that it shows up in the patch contributions pipeline, which is used internally to make sure your patch gets the attention of a MySQL engineer. If you would like to discuss your patch with others first, you can send e-mail to the Internals Mailing List or the mailing list that is dedicated to the subsystem you are working on, if there is one. In the e-mail, describe the bug or feature request, provide your patch, and ask for review. If you choose to have a mailing list discussion, it can be helpful for tracking to add a link to the e-mail to the bug report. (A link to the mailing list archive looks something like http://lists.mysql.com/internals/1111 .)

When sending patches to the bug-tracking system or to MySQL mailing lists, indicate whether you have signed and returned the SCA, as this will guide MySQL engineers on what level of review they may direct at your patch. Also, please use your real name in e-mails and the bug-tracking system, as this will help matching you up with the legal paperwork.

When it comes to actually contributing code, you must complete the following high-level phases. This applies to community members inside and outside of Oracle equally. The number of steps represented in these phases will vary depending on the size and complexity of the change.

Development/Implementation

Test

Review: architectural, design, and code review

Documentation changes (if needed)

This does not mean that every patch must come with a complete test suite and documentation before it is considered. MySQL engineers and others may be willing to assist you in writing tests or polishing the documentation. But the more you contribute to completing these steps, the faster and more efficiently your contribution will be handled.

If your patch or feature has a performance or security impact, it is helpful if you mention that explicitly, so that the appropriate review and testing resources can be allocated. Also, be sure to provide adequate supporting documentation, such as performance test numbers.

It might be useful to submit your patch (after having tested it) as a Bazaar Bundle. If you have a fix for a bug in the form of Bazaar Bundle, you can easily attach it to an e-mail to the internals list or on the bug report. For very large projects, you can also submit a patch by publishing a Bazaar tree on Launchpad and proposing it for a merge.

After a review you may be asked to submit a corrected patch. For larger projects, many review iterations may be necessary.

Eventually, the patch will hopefully become ready to be committed to any of the internal source code trees from where it eventually will be merged to the main source trees. Depending on the type of bug fix, the developers will decide in which version of the code base it will be applied. If you are not sure on this point, please ask or make suggestions of your own.

Testing

The development of tests, test frameworks, and the execution of test suites are all important aspects of high-quality software engineering.

All contributions must come with tests that exercise those contributions. Tests should be provided in the same format that the subsystem for which the contribution is meant uses. For instance, for MySQL server, you should consult the MySQL Test Framework documents. For connectors, see the test suite released with the source. The new tests will be merged into the source tree test repository and framework along with the rest of your submission.

Contact the developers through the mailing lists if you are not sure what the preferred format for tests is.

Over time, we expect to create environments that facilitate testing by contributors in the community. In the meantime, we expect you, as the contributor, to ensure a complete error-free build and passage of all tests, including your contributed tests, before you submit a patch.

The individuals who post here are part of the extended Oracle community
and they might not be employed or in any way formally affiliated with Oracle.
The opinions expressed here are their own, are not necessarily reviewed in
advance by anyone but the individual authors, and neither Oracle nor any
other party necessarily agrees with them.