BluezGit

The process for managing BlueZ in Git

Goals and benefits

  • Everything is in git. Everything has history and version control.
  • git log shows history going back to the master branch upstream changes.
  • The debian/ directory lives inside the source tree natively. It not only has history but is always ready for packaging in-tree.
  • Human-readable branches and tags that are very easy to work with. For example:
  • focal
    refers to the code (a branch) that is going into focal next, as well as containing history of what has been in focal archive.
    5.53-tar

    refers to the exact contents of the upstream release tarball.

  • No custom tools or commands. Just regular git.

As far as I know, no other approach achieves all of these.

Caveat

Ubuntu branches directly from upstream BlueZ and not from Debian versions. This is inherited technical debt caused by:

  • Debian often being slower to release new upstream versions than Ubuntu; and
  • Ubuntu already being significantly branched from Debian before this new git process was designed. We are slowly shrinking the diff to minimize the differences between Debian and Ubuntu releases.

Initial setup

  1. Join the team: https://launchpad.net/~bluetooth
    And while waiting for approval, get familiar and comfortable with git.

  2. Bookmark (and optionally read): https://git.launchpad.net/~bluetooth/bluez

  3. Make a local git repository:

    $ git clone git://git.kernel.org/pub/scm/bluetooth/bluez.git
    $ cd bluez
    $ git remote add launchpad git+ssh://USERNAME@git.launchpad.net/~bluetooth/bluez
    $ git fetch launchpad

  4. Start working on master:

    $ git checkout master

  5. Pull in the latest upstream BlueZ code (everything!):

    $ git pull

  6. Decide what upstream version of BlueZ you want. It will either be mentioned here:
    http://www.bluez.org/
    or in the directory:
    https://mirrors.edge.kernel.org/pub/linux/bluetooth/

  7. Verify your git contains a tag for the release you'll be working against:

    $ git tag -l 5.41
    If the tag doesn't exist then do not continue until it does.

  8. Create an intermediate branch for the release. This serves as a parent branch for the distro branch. An intermediate branch is required because the bluez release tarballs contain different files to the actual tag contents in git. The purpose of the intermediate branch is to make a perfect copy of the release tarball with near-perfect git history.
    $ git branch 5.41-tarball 5.41

  9. Download the official release tarball for reference: http://www.bluez.org/

  10. Make the intermediate branch into a perfect copy of the release tarball:
    $ git checkout 5.41-tarball
    $ rm -rf .gitignore .checkpatch.conf .gitlint .mailmap *   # (yes, really)
    $ tar xJvf ~/Downloads/bluez-5.41.tar.xz
    $ mv bluez-5.41/* .
    $ rmdir bluez-5.41
    $ git add .
    $ git commit
    $ git tag 5.41-tar

  11. Assuming your Ubuntu series already contains a release from the above BlueZ version then put it in Downloads/ and import it into git:
    $ git branch yakkety 5.41-tarball
    $ git checkout yakkety
    $ tar xJvf ~/Downloads/bluez_5.41-0ubuntu3.debian.tar.xz
    $ git add debian
    $ git commit
    $ git tag 5.41-0ubuntu3
    $ git push --tags launchpad yakkety
    Note: Patches are never applied in git commits. They exist as debian/patches/* only. This avoids conflicts with changes from upstream.

Updating to a newer upstream version

  1. Download the official release tarball from http://www.bluez.org/ or https://mirrors.edge.kernel.org/pub/linux/bluetooth/

  2. Follow steps 7-10 from the previous list.

  3. Choose which Ubuntu distro to target:
    $ git checkout artful
    If you had to create a new branch for a new Ubuntu series then please also change the Default branch at https://code.launchpad.net/~bluetooth/bluez/+git/bluez/+edit

  4. Merge the new BlueZ release into your distro branch:
    $ git merge -s recursive -X theirs 5.45-tarball
    And complete the merge.

  5. Update debian/changelog with the new version:
    $ dch -i

  6. Save your work before testing packaging works (which will leave a mess):
    $ git commit

  7. Test Debian packaging works in the current directory, and iterate until it does work.

  8. Now the git branch 'artful' contains the exact tree we want to release to archive (plus a .git directory which will be ignored). You can build source packages and test binary packages directly in your git directory, with clean diffs. Nothing unexpected can creep in to a deb release unless it was introduced by a git commit (which is fully traceable).

Housekeeping

Since the -tarball branches will never need to be referred to by name after each major release is completed, they can be hidden somewhat by converting them to tags:

  • git tag 5.41-tar 5.41-tarball
    git push --tags launchpad
    git push -d launchpad 5.41-tarball

DesktopTeam/Bluetooth/BluezGit (last edited 2023-10-26 06:14:50 by vanvugt)