
###########################################################################
# Here are some information that are only of interest for the current and #
# following Debian maintainers of MySQL.                                  #
###########################################################################

The debian/ directory is under GIT control, see debian/control for URL.

#
# Building with sbuild and running dep8 tests
#
- Note: This is tested on Ubuntu 16.04 with xenial-backports enabled. There are bugs in older
- versions of the required packages that might break the build/test run
- You need packages autopkgtest, qemu, sbuild, ubuntu-dev-tools and vmdebootstrap

- To create a basic sbuild image for building:
mk-sbuild --eatmydata [codename]
- eg. mk-sbuild --eatmydata sid

- Build using the created image
DEB_BUILD_OPTIONS=parallel=15 sbuild -Ad[codename] mysql-5.7_[version].dsc
- eg. DEB_BUILD_OPTIONS=parallel=15 sbuild -Adsid-amd64 mysql-5.7_5.7.15-1.dsc

- Create raw sid image for running dep8
sudo vmdebootstrap --verbose --serial-console --distribution=sid --customize=/usr/share/autopkgtest/setup-commands/setup-testbed --user=adt/adt --size=10000000000 --grub --image=adt-sid.raw
- If behind a proxy, add an ADT_APT_PROXY=[url:port] before vmdebootstrap
- Convert to qemu image
qemu-img convert -O qcow2 adt-sid.raw  adt-sid.img
rm adt-sid.raw

- Run dep8 tests
adt-run -oadt -B *.deb mysql-5.7_[version].dsc --- adt-virt-qemu ./adt-sid.img
- eg. adt-run -oadt -B *.deb mysql-5.7_5.7.15-1.dsc --- adt-virt-qemu ./adt-sid.img | tee testresult.txt

#
# Preparing a new version
#
The new orig.tar.gz (without non-free documentation) is created in /tmp/ when
running this command:
 
debian/rules get-orig-source

#
# mysqlreport
#
The authors e-mail address is <public@codenode.com>.

#
# Remarks to dependencies
#
libwrap0-dev (>= 7.6-8.3)
	According to bug report 114582 where where build problems on
	IA-64/sid with at least two prior versions.
psmisc
	/usr/bin/killall in the initscript

zlib1g in libmysqlclient-dev:	
	"mysql_config --libs" ads "-lz"

Build-Dep:

debhelper (>=4.1.16):
	See po-debconf(7).

autoconf (>= 2.13-20), automake1.7
	Try to get rid of them.

doxygen, tetex-bin, tetex-extra, gs
	for ndb/docs/*tex

#
# Remarks to the start scripts
#

## initscripts rely on mysqladmin from a different package
We have the problem that "/etc/init.d/mysql stop" relies on mysqladmin which
is in another package (mysql-client) and a passwordless access that's maybe
only available if the user configured his /root/.my.cnf. Can this be a problem?
* normal mode: not because the user is required to have it. Else:
* purge/remove: not, same as normal mode
* upgrade: not, same as normal mode
* first install: not, it depends on mysql-client which at least is unpacked
                 so mysqladmin is there (to ping). It is not yet configured
		passwordles but if there's a server running then there's a
                /root/.my.cnf. Anyways, we simply kill anything that's mysqld.

## Passwordless access for the maintainer scripts
Another issue is that the scripts needs passwordless access. To ensure this
a debian-sys-maint user is configured which has process and shutdown privs.
The file with the randomly (that's important!) generated password must be
present as long as the databases remain installed because else a new install
would have no access. This file should be used like:
	mysqladmin --defaults-file=/etc/mysql/debian.cnf restart
to avoid providing the password in plaintext on a commandline where it would 
be visible to any user via the "ps" command.

## When to start the daemon?
We aim to give the admin full control on when MySQL is running.
Issues to be faced here:
OLD:
        1. Debconf asks whether MySQL should be started on boot so update-rc.d is
           only run if the answer has been yes. The admin is likely to forget
           this decision but update-rc.d checks for an existing line in
           /etc/runlevel.conf and leaves it intact.
        2. On initial install, if the answer is yes, the daemon has to be started.
        3. On upgrades it should only be started if it was already running, everything
           else is confusing. Especiall relying on an debconf decision made month ago
           is considered suboptimal. See bug #274264
        Implementation so far:
        prerm (called on upgrade before stopping the server): 
          check for a running server and set flag if necessary
        preinst (called on initial install and before unpacking when upgrading):
          check for the debconf variable and set flag if necessary
        postinst (called on initial install and after each upgrade after unpacking):
          call update-rc.d if debconf says yes
          call invoce-rc.d if the flag has been set
        Problems remaining:
          dpkg-reconfigure and setting mysql start on boot to yes did not start mysql
          (ok "start on boot" literally does not mean "start now" so that might have been ok)
NEW:
        1. --- no debconf anymore for the sake of simplicity. We have runlevel.conf,
           the admin should use it
        2. On initial install the server is started.
        3. On upgrades the server is started exactly if it was running before so the
           runlevel configuration is irrelevant. It will be preserved by the mean of
           update-rc.d's builtin check.
        Implementation:
        prerm (called on upgrade before stopping the server):
          check for a running server and set flag if necessary
        preinst (called on initial install and before unpacking when upgrading):
          check for $1 beeing (initial) "install" and set flag
        postinst (called on initial install and after each upgrade after unpacking):
          call update-rc.d
          call invoce-rc.d if the flag has been set


Test plan
=========

This is the test plan agreed to at the meeting in London, December
2014. Please revisit and keep this document up-to-date if you're
changing any tests.


Why we're changing the test plan
--------------------------------

Historically, the main suite of the upstream MTR tests have been run at
build time. This has deteced real bugs, especially when building for
platforms not supported by upstream, so we definitely see a value in
running these tests.

Test runs are taking a long time to finish. Some tests are unstable and
may return false positives, leading to failed builds. In addition, we're
testing a lot of things that have already been tested upstream and that
are unlikely to change when packaged for Debian/Ubuntu.

We're also adding DEP8 tests, so we have to decide what goes into the
build tests and what goes into DEP8 tests.


Build tests
-----------

Instead of running the main test suite for every build, we should spend
time on testing the things that are actually different from upstream:

 - Dependencies (both build and runtime)
 - Install paths

Until we figure out a set of test for this, we continue with the main
MTR suite, as before. We skip rpl tests (using --skip-rpl) to reduce the
number of false positives.

The build itself fails on the first error, and we do the same in testing
by running MTR without --force. This shortens down build cycles in case
of failures.

DEP8 tests
----------

The time it takes to run the tests isn't that much of an issue for DEP8
as it is for build tests, so we can do more thorough testing here.

We run the build tests in DEP8 in order to detect when dependency
updates that don't require a rebuild of MySQL will cause the MySQL
package to break.

Since bugs on platforms not supported by upstream has been found by the
main suite earlier, upstream recommends that we continue to run this
suite in DEP8.

We skip rpl tests to reduce the number of false positives.

We run MTR with --force in order not to stop at the first failure. Since
DEP8 tests are expected to run for a while, and we expect the tests to
pass since the build tests passed, it's more useful to come back and see
that all tests have run, but a couple of them failed, than to see that
the first test failure was after 5 minutes and that it aborted
immediately. It will also give us more information, since we can see
from the log if this was an unstable test that passed when rerun or if
it is a real test failure.


#
# Bundled boost and rapidjson headers
#

MySQL bundles code from two projects that are technically available in Debian: boost and rapidjson
For both of these projects, MySQL bundles header files only.

For boost, MySQL relies on a very specific version, so using the version available on the system
will generally not work.

For rapidjson, they have not published a release for years (https://github.com/Tencent/rapidjson/issues/1006),
and MySQL requires more recent patches (and will occasionally sync with their master branch).
