This page contains general guidelines and procedures for contributing code. If
you have any questions we invite you to ask on the
maria-developers mailing list, on our Zulip instance at https://mariadb.zulipchat.com, or on the #maria IRC channel on Freenode. Other email lists and places to find MariaDB can be found
here.
General information about contributing to MariaDB (for developers and
non-developers) is found on the
Contributing to the MariaDB Project
page.
There are many open development projects for MariaDB which you can contribute
to (in addition to any ideas you may have yourself).
<<nowiki>>
<<style class="redbox centered">>
**The MariaDB source is now hosted on Github: https://github.com/MariaDB/server. \\See [[using-git|Using Git]]. The information below is outdated and will be rewritten at some point.**
<</style>>
== Prerequisites
You need [[http://bazaar-vcs.org|Bazaar]] for revision control.
= = = bzr Login Setup
* Get a launchpad account at https://launchpad.net/+login
* When logged in, setup your SSH keys
** Click your name (top right corner)
** Click Change Details link (upper right)
** Click SSH Keys button (middle of page)
** Upload your public SSH key
([[https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair|How do I get a public key?]])
* Register yourself with launchpad from your local commandline: <<fixed>>bzr launchpad-login [yourloginid]<</fixed>>
=== Getting the MariaDB Code
# First, [[getting-the-mariadb-source-code|get a clean copy of the MariaDB code]]
(for some, the fastest way to get up and running is to follow the
instructions in the "Source Tree Tarball" section).
#decimal.2 Once you have a clean copy of the source, create a working copy for
your changes:
<<code lang=sh inline=false indent=1>>
cd $maria-repo # ex: ~/repos/maria
bzr branch trunk maria-fix-bugNNNNNN
cd maria-fix-bugNNNNNN
<</code>>
<<style class="bluebox">>
**Tip:** //Use descriptive names such as maria-fix-bugNNNNNN (where NNNNNN is the bug # of course).//
<</style>>
#decimal.3 You should now be ready to [[generic-build-instructions|Compile MariaDB]]. It's
a good idea to compile at this stage to confirm the source tree you are going
to be hacking on works . . . before you make any changes.
The following pages will help you get up and running with the MariaDB source
code:
* [[getting-the-mariadb-source-code|Getting the MariaDB Source Code]]
* Setup your build environment:
** [[build-environment-setup-for-linux|Linux]]
** [[build-environment-setup-for-mac|Mac]]
** [[building-mariadb-on-windows|Windows]]
* [[compiling-mariadb-from-source|Building MariaDB]]
== Setting up tests
The Maria test suite is contained in the <<code>>./mysql-test/<</code>>
subdirectory of the source tree. The mysql-test directory has two
subdirectories of utmost concern to you, the bug fixer: the <<code>>t/<</code>>
directory and the <<code>>r/<</code>> directory (for "tests" and "results"
respectively). Be sure to check and see if your bug already has a test too.
All the tests are found in the <<code>>t/<</code>> directory. Open up the file
that corresponds to the functionality you are changing (or add a new file) and
add the commands that will reproduce the bug or validate the new functionality.
For example, the test below creates a new test table "t1"; shows us the result
of that CREATE TABLE statement; and lastly, we cleanup the test by dropping the
test table:
<<sql>>
#
# Bug #XXXXXX: INET_ATON() returns signed, not unsigned
#
create table t1 select INET_ATON('255.255.0.1') as `a`;
show create table t1;
drop table t1;
<</sql>>
By adding your test first, it will remind you to re-record the test output file
later (and inform future efforts about your expected output, of course). Now
it's time to make your changes.
Examine existing tests to get a better idea of how you should write your test.
We are always on the lookout for better tests, so if you create new test or
improve an existing test, please upload it to the "private" folder on our
[[FTP]] server and then ping us on [[IRC]] or send a note to the
Maria-Developers mailing list to let us know about it.
== Editing and Adding to Your Contribution
With a working version, you can commence making changes in your new branch,
committing code regularly to your local working copy; feel free to commit early
and often as you will formalize your contribution later with a push and
proposal.
<<code lang=sh>>
cd $maria-repo/maria-fix-bugNNNNNN
# Make Changes
bzr commit -m "Merge comment"
<</code>>
Prior to publishing your completed work, you need to confirm that your branch
works as expected and update the test runs.
To allow others to see your commits, you should configure
[[setting-up-and-using-bazaar-bzr-with-mariadb|bzr]] to send its commit emails
to
[[http://lists.askmonty.org/cgi-bin/mailman/listinfo/commits|commits 'at' mariadb 'dot' org]]
email list.
== Testing Your Branch
Make sure you have at least libtool 1.5.22
([[http://www.gnu.org/software/libiconv/|found here]]).
First, check to see that all the tests pass (remember the test you set up
earlier? It should fail. That's ok, you will re-record it momentarily):
<<code lang=sh>>
cd $maria-repo/mysql-test
./mysql-test-run
<</code>>
Any that fail will need to be re-recorded.
<<code lang=sh>>
cd $maria-repo/mysql-test
./mysql-test-run --record $test # where $test is the name of the test that failed
<</code>>
You are now ready to merge into trunk.
== Merging Recent Changes
It is important to merge any changes from trunk into your branch before pushing
or publishing.
Update your local trunk.
<<code lang=sh>>
cd $maria-repo
cd trunk
bzr pull
<</code>>
Updating your local branch.
<<code lang=sh>>
cd $maria-repo
cd maria-fix-bugNNNNNN
bzr merge ../trunk
bzr commit -m "Merged from trunk"
<</code>>
Conflicts can be resolved in bazaar via:
<<code lang=sh>>
bzr resolve $filename
<</code>>
To revert to your last commit on your branch use:
<<code lang=sh>>
bzr revert $filename
<</code>>
(Note you will need to remerge with trunk before pushing)
Verify differences carefully
<<code lang=sh>>
bzr diff
<</code>>
== Publish Your Branch
When all changes are merged and your changes are all consistent you can push
your branch to LaunchPad
<<code lang=sh inline=false>>
cd $maria-repos/$your-branch # where $your-branch is the branch you want to push (ex: maria-bugNNNN)
bzr push lp:~[yourloginid]/maria/$your-branch
<</code>>
If you find that this takes a very long time (eg. >30 minutes), you may want to
try using '<<code>>bzr init-repo --format=1.9<</code>>' to initialize a new
repo and merge your work into it, then push again.
== How to Propose Branch for Merging
On your Launchpad Code page
{{{https://code.launchpad.net/~{yourloginid}/maria/{branch-name} }}} click the
**Propose for merging into another branch** link to propose branch to the
maintainers to be merged into the main trunk.
== Getting Your Code into the Main MariaDB Tree.
All code in MariaDB comes from one of the following sources:
* MySQL
* Code developed by people employed by the [[http://mariadb.org|MariaDB Foundation]].
* Code developed by people employed by [[http://mariadb.com|MariaDB Corporation]].
* Code shared with the MariaDB Foundation under the [[mca|MCA]].
* Code with a known origin that is under a permissive license (BSD or public domain).
If you want the code to be part of the main [[MariaDB]] tree, you also have to
give the MariaDB Foundation a shared copyright to your code. This is needed so
that the foundation can offer the code to other projects (like MySQL).
You do this by either:
# Signing the MariaDB Contributor Agreement
([[mca|MCA]]) and then scanning and sending it to the foundation.
# Sending an email to
[[http://launchpad.net/~maria-developers|maria-developers]] where you say
that your patch and all fixes to it are provided to the MariaDB Foundation under
the [[mca|MCA]].
# Licensing your code using the
[[http://opensource.org/licenses/bsd-license.html|BSD license]].
We need shared copyright for the following reasons:
# to defend the copyright or GPL if someone breaks it (this is the same reason
why the Free Software Foundation also
[[https://www.gnu.org/licenses/why-assign.html|requires copyright assignment]]
for its code)
# to be able to donate code to MySQL (for example to fix security bugs or new
features)
# to allow people who have a non-free license to the MySQL code to also use
MariaDB (the MCA/BSD allows us to give those companies the rights to all
changes between MySQL and MariaDB so they can use MariaDB instead of MySQL)
More information about the MCA can be found on the
[[mca-faq|MCA FAQ]] page.
== Fix Branch (if needed)
If fixes are needed on your branch you will need to: make the changes, re-merge
any new changes to trunk, commit and re-push; you do not need to re-propose.
After the push, LaunchPad will pick up the changes automagically.
Please be aware that changes can take a few minutes for LaunchPad to merge your
new changes into your proposal.
== How to Re-Submit a Proposal
At the moment, this is a tricky process, and none of the "Request another
review" links on Launchpad work.
To resubmit a merge proposal, follow these steps:
# On the main page of the merge proposal, the top line will be something like
"Status: Needs Review". Just to the right of this is a small button; click on
this to change the status.
# Select "Resubmit" from the drop down menu and click "Change Status".
# The next page should prompt you to resubmit the merge proposal and inform you
that the new proposal will supersede the old one
# Click "Resubmit" to finish.
A couple of easy ways to get attention to your proposed merge are:
* Join the #maria [[IRC]] channel on freenode ask people to review/discuss your
merge.
* Subscribe to and send an email to the
[[http://launchpad.net/~maria-developers|maria-developers]] group on
Launchpad.
<</nowiki>>