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 via MySQL Community Slack relevant to your area of interest. The MySQL Community Slack
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.
Some
contributors may also wish to sign up for a GitHub account to be able
to use MySQL on GitHub. This 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. 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:
- Go to Oracle Contributor Agreement (OCA) application
- Login to the OCA app using the Oracle account
- Decide whether you would like to submit Individual or Company OCA
- Fill in all requested details
- Sign (using DocuSign) & Submit
If
you have previously signed or submitted 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.
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.
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 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. Join the channel dedicated to patches and contributions: #patches.
When
sending patches to the bug-tracking system or via GitHub Pull Request,
indicate whether you have signed and returned the OCA, 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.
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.