Contributing to MySQL

Participation from the contributor community is an important factor in the success of the MySQL open-source project. There are many ways and reasons people contribute to MySQL:

  1. To avoid having to maintain their patch, which they wrote in order to fix their own problem with MySQL
  2. To increase their market value for recruitments, not just by Oracle but by any company
  3. To get feedback and users for their projects, as MySQL is the wide-spread fundamental of their project

Regardless of the reason, MySQL thrives off of your contributions. With your contributions, the MySQL team is able to:

  • Identity and fix bugs more effectively and efficiently
  • Implement custom features requested by users
  • Collaborate directly with the community
  • Grow a larger recruitment base of developers

Getting Set Up

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

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

What is needed to submit Contribution:

If you intend to submit contributions to MySQL you will need the following

  1. A user in the MySQL bug system, as described above.
  2. Sign an Oracle contribution agreement (see below)
  3. Optionally a Github user (if you plan to contribute via Github) – see next paragraph.

In addition, contributors can also sign up for a GitHub account to use MySQL on GitHub, which is especially useful if you plan to host larger branches of your own on GitHub. MySQL uses Git as its version control system. For information about working with and maintaining Git repositories, refer to the GitHub Help page. For information about how to obtain the MySQL Server source trees, see Installing MySQL Using a Development Source Tree.

Paperwork

If you expect to make code-related contributions, you must submit signed the Oracle Contributor Agreement (OCA). Without a submitted and approved OCA, 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.

Submitting the OCA, step by step:

  1. Go to Oracle Contributor Agreement (OCA) application
  2. Login to the OCA app using the Oracle account
  3. Decide whether you would like to submit Individual or Company OCA
  4. Fill in all requested details
  5. Sign (using DocuSign) & Submit

For any questions, refer to the OCA FAQ page.

If you have previously signed or submitted the OCA (formerly the 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 sign and return the OCA instead. All contributions to the MySQL project require that the contributor sign and return the OCA.

We assign your signed OCA with your MySQL/Oracle account. If you don't yet have an account, please register under https://bugs.mysql.com (top right corner, Register). The account (Oracle SSO) provides access to other MySQL development resources too.

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 and 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 yourself, 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 involves more developers to ensure quality feature patches that adhere to the MySQL Coding Guidelines. In any case, make sure to contact the MySQL developers and discuss your proposal via the MySQL Community Slack 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, contact us in the MySQL Community Slack. Alternatively, you can submit a patch via Github

Join the channel dedicated to patches and contributions: #patches.

When sending patches via GitHub Pull Request, the system will provide you with feedback on whether you need to sign an OCA or (if you have one) confirm that the contribution is under your OCA.

If submitting a patch via the MySQL bug system – you will need to have an OCA in place before submitting the patch

Also, please use your real name in e-mails and the bug-tracking system, as this will help to match you 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.

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 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. For now, 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.

For more information and resources, see the MySQL Community page.