# README for Debian package maintainers

This file mostly applies to how the packaging work-flow works for the official
Debian packages, but it may contain useful information also for anybody doing
their own private .deb builds.

## Version control

This package is maintained by the MariaDB/MySQL team in Debian using the
git-buildpackage tool and storing the git repositories on the Debian Gitlab
instance Salsa. For details see https://salsa.debian.org/mariadb-team/.

The official Ubuntu packages are also maintained by the same team using the same
source repository.

### Ensuring git contents match what has been uploaded to Debian/Ubuntu

It is possible (but extremely rare) that somebody uploads a MariaDB package to
Debian/Ubuntu and either does not use git at all, or simply forgets to push the
same changes on git, or makes an error in tagging the release or something.
Therefore, maintainers should check that the git contents match what has been
uploaded to Debian/Ubuntu before making new changes on git.

This can be done by using dgit. The example command below will fetch the latest
mariadb-10.1 package available in Ubuntu 18.04 (Bionic) base archive, security
archive or updates archive (whichever has a newer version):

    dgit -d ubuntu clone mariadb-10.6 jammy,-security,-updates
    cp -ra mariadb-10.6/* .
    rm -rf mariadb-10.6

You can then compare these two directories with a recursive diff or `git diff`.


Another option is to manually check on packages.debian.org or packages.ubuntu.com
what is the latest version, and download and extract it on top of the existing
debian/ directory with:

    curl -SL https://launchpad.net/ubuntu/+archive/primary/+sourcefiles/mariadb-10.6/\
    1:10.6.7-2ubuntu1.1/mariadb-10.6_10.6.7-2ubuntu1.1.debian.tar.xz -o - | tar xv --xz

You can simply run `git diff` to see the report on differences.


## Building from sources with git-buildpackage

See README.Contributor for details.


## Upgrading sources from upstream

Upstream will publish maintenance releases at least 5 years after the major
version release, and security updates are likely to come even after that as
long as major distributions ship the version.

See table at
https://mariadb.com/kb/en/mariadb/development/mariadb-maintenance-policy/

Release notes are available at
https://mariadb.com/kb/en/mariadb/development/release-notes/


### Steps to import new upstream version

Download new source package:

    git checkout 10.6
    git pull --tags upstream 10.6
    git tag -v mariadb-10.6.12
    git checkout debian/latest
    git merge -v mariadb-10.6.12

Refresh patches:

    while quilt push; do quilt refresh; done; quilt pop -a

Simple offsets will be updated automatically. If there are any rejects, inspect
the files and update the patches or discard the patch completely if you are
_sure_ that it has been applied upstream.

Generate new debian/changelog entry automatically with git-dch:

    gbp dch -vR

Edit the details to match correct release:

    gedit debian/changelog &

Commit to git:

    git citool

Build and test locally to verify it works:

    gbp buildpackage

Alternatively you can use Docker with something like this:

    mkdir ccache buildout
    docker run -it -v "${PWD}/buildout":/tmp/build -v "${PWD}/ccache":/.ccache \
       -v "${PWD}/$PKG":/tmp/build/source -w /tmp/build/source \
       -e DEB_BUILD_OPTIONS="$DEB_BUILD_OPTIONS" -e CCACHE_DIR=/var/cache/ccache \
       --user=1001 registry.gitlab.com/mariadb/mariadb.org-build-containers:$PKG-debian-sid-build-env \
       gbp buildpackage | tee latest.build

If needed, add commits or amend the ones you made until the package is in
perfect shape.

Let Lintian automatically check as much as possible:

    lintian -EvIL +pedantic --color=always *.changes

Then proceed to make a source only build:

    gbp buildpackage -S

Test more with upload to Launchpad:

    COMMIT_ID=`git log -n 1 --oneline | cut -d ' ' -f 1`
    PKG=mariadb-10.6
    backportpackage --yes -u ppa:mysql-ubuntu/$PKG -d groovy -S ~`date '+%s'`.$COMMIT_ID $PKG*.dsc

When done, push to Salsa:

    gbp push # gbp branches and tags
    git push # master branch

Wait until the Salsa CI pipeline finishes. If it did not either spot any
regressions, proceed to tagging the commit:

    gbp tag
    gbp push

Once you are sure there are no regressions, finally upload to Debian:

    dput ftp-master *.changes

After the upload, check that everything is OK at
* https://tracker.debian.org/mariadb-10.6 (Debian)
* https://launchpad.net/ubuntu/+source/mariadb-10.6 (Ubuntu)

## Maintaining translations

Running `debconf-updatepo --verbose` will refresh the translation files.

A call for translations can be initiated with e.g. `podebconf-report-po --call -v --smtp=smtp.kolumbus.fi`.

### Launchpad testing matrix

Since Launchpad only has Ubuntu releases, packages for specific Debian releases
needs to be tested on the Ubuntu release which most closely matches the Debian
release in question. The following matrix maps what package should be tested
where:

- 10.6 for sid on Launchpad lunar
- 10.6 for kinetic on Launchpad kinetic
- 10.6 for jammy on Launchpad jammy
- 10.5 for bullseye on Launchpad hirsute (not available anymore)
- 10.3 for focal on Launchpad focal
- 10.3 for buster on Launchpad disco (not available anymore)
- 10.1 for bionic on Launchpad bionic
- 10.1 for stretch on Launchpad xenial (not available anymore)

## Uploading security releases to Debian

After you've got permission from the security team, upload with `dput security-master *.changes`.

For details see https://www.debian.org/doc/manuals/developers-reference/pkgs.html#bug-security

## Uploading security releases to Ubuntu

See example with documented procedure:
 * https://bugs.launchpad.net/ubuntu/+source/mariadb-10.3/+bug/1861260

### Upload priority

Do the security uploads in this order for having the best chance of catching
regressions before they spread out to too many users.

Upload priority for 10.6
- debian sid
- ubuntu-22.10 kinetic
- ubuntu-22.04 jammy

Upload priority for 10.5
- debian-11 bullseye

Upload priority for 10.3
- ubuntu-20.04 focal
- debian-10 buster

for 10.1 (only in case there are extra releases after official EOL)
- ubuntu-18.04 bionic
- debian-9 stretch

## Comparison to other distributions

For tracking security release information, finding solutions for build errors
on many architectures and for general quality control it can be useful to keep
an eye on what packagers in other distributions do:

Fedora:
  * https://apps.fedoraproject.org/packages/mariadb/
  * http://pkgs.fedoraproject.org/cgit/mariadb.git/
OpenSUSE:
  * https://build.opensuse.org/package/show/server:database/mariadb
Arch Linux:
  * https://projects.archlinux.org/svntogit/packages.git/?h=packages/mariadb
Mageia:
  * http://svnweb.mageia.org/packages/cauldron/mariadb/current/

See also: https://repology.org/project/mariadb/badges