From 82a6365993a3c6650c39a1bca3ec3ccba827b763 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 4 May 2024 20:07:29 +0200 Subject: Adding debian version 1:10.5.12-1. Signed-off-by: Daniel Baumann --- debian/README.Contributor | 190 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 debian/README.Contributor (limited to 'debian/README.Contributor') diff --git a/debian/README.Contributor b/debian/README.Contributor new file mode 100644 index 00000000..a912f647 --- /dev/null +++ b/debian/README.Contributor @@ -0,0 +1,190 @@ +# README for Debian packaging contributors + +This documentation describes how to contribute to the official Debian packages +of MariaDB. The packaging in Debian repositories is not identical to the packaging +in mariadb.org repositories, but whatever is in Debian repositories will eventually +be upstreamed. + + +## Development environment and tools + +Use a recent version of Debian or Ubuntu as the environment for Debian packaging +testing and development. Preferred environment is Debian Sid (unstable). + +Install the tool used to manage and build the source: + + sudo apt-get install git-buildpackage + + +## Getting the source + +The official Debian package source is hosted on the Debian Gitlab server under +the MariaDB/MySQL packaging team at https://salsa.debian.org/mariadb-team/. You +are welcome to fork it and make merge requests. + +To get the latest official Debian packaging source of mariadb-10.5, clone the +source repository with all relevant branches (master, upstream, pristine-tar) to +your local environment using _git-buildpackage_: + + gbp clone --pristine-tar https://salsa.debian.org/mariadb-team/mariadb-10.5.git + +If you have your own fork and SSH keys set up on Salsa, you can run: + + gbp clone --pristine-tar git@salsa.debian.org:/mariadb-10.5.git + + +The clone needs to be run only once. On later runs you can refresh your clone with +relevant branches using: + + gbp pull --pristine-tar --force + + +## Building the packages + +Build binaries, run testsuite and build Debian packages with: + + gbp buildpackage + +On the first run git-buildpackage will complain if some of the build dependencies +defined in debian/control are missing. Simply install those packages and run the +build again. + +A quick command to install all dependencies: + + sudo mk-build-deps -r -i debian/control -t "apt-get -y -o Debug::pkgProblemResolver=yes --no-install-recommends" + +If the build fails, the easiest way to clean up before a new run is + + git clean -fdx && git reset --hard + + +### Build options + +If you want to skip the mysql-test-run step (which takes a lot of time) set +the following environment variable: + + export DEB_BUILD_OPTIONS="nocheck" + +If you want to run the build in parallel on 2 CPUs and have verbose output: + + export DEB_BUILD_OPTIONS="parallel=2 verbose" + +The options above can also be combined freely to get desired behavior. + + +### Using special build environments + +If you want to ensure all build dependencies are clean, you can build inside a +Docker or sbuild (Debian tool) environment. + +#### Build in Docker + +First make a working directory for the build artifacts. Inside that directory +clone the repository. Then start a Docker session using whatever Debian/Ubuntu +image you want with the command: + + docker run -it -v ${PWD}:/build -w /build debian:sid bash + +This will start a session, where you are as the root user in the path /build +inside the Docker container. Here you can `cd` into the source directory, +install dependencies and start the build. Note that when you exit the session, +everything will be lost apart from the files you had inside the mounted volume +in `/build`. + +#### Build using sbuild + +If you prefer sbuild, you can build with something like: + + gbp buildpackage --git-builder=sbuild -A -v -d unstable + +## Creating a feature or bugfix branch + +The repository has the following branch layout: + * upstream - contains the upstream source releases without modifications + * pristine-tar - contains extra delta needed to re-create the original + tarballs with the exactly same SHA-1 hash as the original tarballs by upstream + * master - packaging for Debian Sid (unstable) + * stretch - release branch for Debian 9 (stretch) + * buster - release branch for Debian 10 (buster) + * ubuntu-20.14 - release branch for Ubuntu 20.04 (focal) + * ubuntu-18.04 - release branch for Ubuntu 18.04 (bionic) + +All new features and also bug fixes are done only in the master branch. The +release branches for Debian and Ubuntu are only used for security updates. + +To prepare the Salsa pull request, create a bugfix branch from master with: + + git checkout -b bugfix/NNNNNN-example-name + +After this you can develop with all the usual git commit and push commands +until you have in your fork at Salsa the desired change and you are ready +to open the merge request. + + +### Notes about how to make changes in the proper way + +First consider submitting your patch upstream. Upstream MariaDB makes frequent +maintenance releases and any fix done upstream will therefore be included in +Debian relatively quickly. You can send email to the developers mailing list +or open a pull request at https://github.com/MariaDB/server. + +Follow these instructions if your fix is about packaging in Debian specifically. +Start by using `gitk --all` or similar tool to browse the previous changes. Try +to follow similar pattern in your new changes. + +Keep in mind that all changes must done only for files residing in the `debian/` +sub-directory. If you need to create changes outside the `debian/` directory, +then you need to create a patch file using the same pattern as the patches +found in `debian/patches` and activated by a line in `debian/patches/series`. + +Do not bundle in your commit any changes to `debian/changelog`. The correct +changelog entries will be created later by the maintainer using `git-dch` in an +automated fashion. + +For an example of a patch adding commit see https://github.com/ottok/mariadb-10.0/commit/8d2a7c909 + + +# Debug tips if build or test suite fails + +## Debug build + +A debug build can be created by adding the following build flags: + + -DCMAKE_BUILD_TYPE=Debug \ + -DMYSQL_MAINTAINER_MODE=OFF \ + +The latter flag ensures build does not stop on warnings but continues to the end. + +## Debugging test suite failures + +If the test suite is failing on Launchpad or some other CI system where you +don't have access to the build artifacts, you can extend the debian/rules file +to print out valuable information with the commands: + + cd $(BUILDDIR)/mysql-test && find var/log/ -ls || true + cd $(BUILDDIR)/mysql-test && cat var/log/*.err || true + cd $(BUILDDIR)/mysql-test && tail -n 1000 var/log/*.log || true + +The `cd` is required on every line since it is a Makefile and the actual command +needs to run in the correct directory. Also, the `|| true` at the end ensures +the build will complete and not abort if any of those debug steps fail. + +If there is a core dump file a stack trace can be produced with: + + cd $(BUILDDIR)/mysql-test && gdb --batch --ex 'thr a a bt' var/log/*/mysqld.1/core || true + +## Debug installation/upgrade + +To see what exactly the Debian maintainer scripts run, a verbose debug mode can be enabled with: + + export DEBIAN_SCRIPT_DEBUG=1 + apt install ... + +The source files of the Debian maintainer scripts are not the final ones, as the package building stage may make changes and additions to them. To view a maintainer script in the final form run on installed system: + + cat /var/lib/dpkg/info/mariadb-server-10.5.postinst + +To review the my.cnf status you may run: + + find /etc/mysql/ -ls + update-alternatives --display my.cnf -- cgit v1.2.3