== Merging from MySQL into MariaDB
=== Merging code changes from MySQL bzr repository
We generally merge only released versions of MySQL into MariaDB trunk. This is
to be able to release a well-working release of MariaDB at any time, without
having to worry about including half-finished changes from MySQL. Merges of
MySQL revisions in-between MySQL releases can still be done (eg. to reduce the
merge task to smaller pieces), but should then be pushed to the maria-5.1-merge
branch, not to the main lp:maria branch.
The merge command should thus generally be of this form:
<<code lang=sh inline=false>>
bzr merge -rtag:mysql-<MYSQL-VERSION> lp:mysql-server/5.1
<</code>>
As a general rule, when the MySQL and MariaDB side has changes with the same
meaning but differing text, pick the MySQL variant when resolving this
conflict. This will help reduce the number of conflicts in subsequent merges.
=== Buildbot testing
To assist in understanding test failures that arise during the merge, we pull
the same revision to be merged into the
lp:~maria-captains/maria/mysql-5.1-testing tree for buildbot test. This allows
to check easily if any failures introduced are also present in the vanilla
MySQL tree being merged.
=== Helpful tags and diffs
To help keep track of merges, we tag the result of a merge:
<<code lang=sh inline=false>>
mariadb-merge-mysql-<MYSQL-VERSION>
<</code>>
For example, when merging MySQL 5.1.39, the commit of the merge would be
tagged like this:
<<code lang=sh inline=false>>
mariadb-merge-mysql-5.1.39
<</code>>
The right-hand parent of tag:mariadb-merge-mysql-5.1.39 will be the revision
tag:mysql-5.1.39. The left-hand parent will be a revision on the MariaDB
trunk.
When merging, these tags and associated revisions can be used to generate some
diffs, which are useful when resolving conflicts. Here is a diagram of the
history in a merge:
<<code>>
B----maria------A0-------A1
\ / /
\ / /
---mysql---Y0------Y1
<</code>>
Here,
* <<fixed>>'B'<</fixed>> is the base revision when MariaDB was originally
branched from MySQL.
* <<fixed>>'A0'<</fixed>> is the result of the last MySQL merge, eg.
<<fixed>>tag:mariadb-merge-mysql-5.1.38<</fixed>>.
* <<fixed>>'Y0'<</fixed>> is the MySQL revision that was last merged, eg.
<<fixed>>tag:mysql-5.1.38<</fixed>>.
* <<fixed>>'Y1'<</fixed>> is the MySQL revision to be merged in the new merge,
eg. <<fixed>>tag:mysql-5.1.39<</fixed>>.
* <<fixed>>'A1'<</fixed>> is the result of committing the new merge, to be
tagged as eg. <<fixed>>tag:mariadb-merge-mysql-5.1.39<</fixed>>.
Then, these diffs can be useful:
* <<fixed>>'bzr diff -rY0..before:A1'<</fixed>> - this is the MariaDB side of changes to be merged.
* <<fixed>>'bzr diff -rY0..Y1'<</fixed>> - this is the MySQL side of changes to be merged.
* <<fixed>>'bzr diff -rA0..before:A1'<</fixed>> - these are the new changes on the MariaDB side to be merged; this can be useful do separate them from other MariaDB-specific changes that have already been resolved against conflicting MySQL changes.
=== Merging documentation from MySQL source tarballs
The documentation for MySQL is not maintained in the MySQL source bzr
repository. Therefore changes to MySQL documentation needs to be merged
separately.
Only some of the MySQL documentation is available under the GPL (man pages,
help tables, installation instructions). Notably the MySQL manual is not
available under the GPL, and so is not included in MariaDB in any form.
The man pages, help tables, and installation instruction READMEs are obtained
from MySQL source tarballs and manually merged into the MariaDB source trees.
The procedure for this is as follows:
There is a tree on Launchpad used for tracking merges:
<<code>>
lp:~maria-captains/maria/mysql-docs-merge-base
<</code>>
(At the time of writing, this procedure only exists for the 5.1 series of MySQL
and MariaDB. Additional merge base trees will be needed for other release
series.)
This tree must **only** be used to import new documentation files from new
MySQL upstream source tarballs. The procedure to import a new set of files when
a new MySQL release happens is as follows:
* Download the new MySQL source tarball and unpack it, say to mysql-5.1.38
* run these commands: <<code lang=sh inline=false>>
T=../mysql-5.1.38
bzr branch lp:~maria-captains/maria/mysql-docs-merge-base
cd mysql-docs-merge-base
for i in Docs/INSTALL-BINARY INSTALL-SOURCE INSTALL-WIN-SOURCE support-files/MacOSX/ReadMe.txt scripts/fill_help_tables.sql $(cd "$T" && find man -type f | grep '\.[0-9]$' | grep -v '^man/ndb_' | grep -v '^man/mysqlman.1$') ; do cp "$T/$i" $i; bzr add $i ; done
bzr commit -m"Imported MySQL documentation files from $T"
bzr push lp:~maria-captains/maria/mysql-docs-merge-base
<</code>>
* Now do a normal merge from <<fixed>>lp:~maria-captains/maria/mysql-docs-merge-base<</fixed>> into <<fixed>>lp:maria<</fixed>>
== Merging from XtraDB into MariaDB
=== Background
Percona maintains XtraDB as a patch series against the InnoDB plugin. However,
in MariaDB, XtraDB in included as a replacement for the built-in innodb. This
influences the way merging among the different projects is done.
The patch series is maintained in a launcpad repository, at the time of
writing this is <<fixed>>lp:~percona-dev/percona-xtradb/extensions-1.0.<</fixed>>
Percona also maintains a normal source tree repository of XtraDB. This is
obtained by applying the patch series to an upstream tarball of the InnoDB
plugin. The Lauchpad tree is lp:percona-xtradb. There is also different tree
for each XtraDB release, for example <<fixed>>lp:percona-xtradb/release-7<</fixed>>
Percona regularly updates this Launchpad tree by re-applying the current patch
series and committing the results. However, no development is committed
directly to these trees.
=== Merging
The <<fixed>>lp:percona-xtradb<</fixed>> tree has been included into the
MariaDB repository with the merge-into bzr plugin. This means that merging from
XtraDB can be done with a command like this:
<<code lang=sh inline=false>>
bzr merge lp:percona-xtradb
<</code>>
Due to the way that various files have been replaced or moved about between
XtraDB and MariaDB, this will often result in a number of conflicts that need
to be resolved manually.
Here are some points to observe:
* The files that live in the topmost directory of lp:percona-xtradb are moved
into storaga/xtradb in MariaDB. However, some files have been removed as they
are not used in MaraDB (for example README, COPYING, Makefile.in). Whenever
these files are changed in XtraDB, bzr merge will re-add them in the root
directory as a conflict to be resolved, and they must be re-deleted to
resolve the conflict.
* XtraDB contains a directory named mysql-test containing additional test
cases and patches against existing testcases. This directory is deleted in
MariaDB. However, everytime a file is changed in that directory on the XtraDB
side, it causes a conflict where the real mysql-test directory is moved away
and the XtraDB one re-created. This conflict must be resolved by moving back
the real one and deleting again the xtradb one. New test cases must be
renamed into the real mysql-test t and r directories. Any changes to the
patches must be manually merged into test cases, and the patches deleted.
While the number of conflicts that bzr gives when merging is annoying, it is
important that we actually get these conflicts. This prevents important
changes from getting lost accidentally. So resist the temptation to leave
unused files hanging about to avoid future conflicts; it will cause more
problems than it solves. Of course, conflicts that can be arranged to be
handled automatically without manual intervention is good, and eg. renaming
new files into the proper place to achieve this is appropriate.
With respect to the test suite, XtraDB is updated with result files etc. to
match a given release of MySQL. So it is often very beneficial (in terms of
time saved debugging test failures) to coordinate merge of XtraDB with the
merge of the associated MySQL version.
==== Update XtraDB version
When merging, the XtraDB version should be set correctly in the file
<<fixed>>storage/xtradb/include/univ.i<</fixed>>
<<code lang=sh inline=false>>
#define INNODB_VERSION_MINOR 0
#define INNODB_VERSION_BUGFIX 6
#define PERCONA_INNODB_VERSION 9 // <-- add this
<</code>>
