Proposed 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:
artful
refers to the code (a branch) that is going in to artful next, as well as containing history of what has been in artful archive.
artful-release
refers to the code (a tag) that is currently in artful.
5.45-tarball

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.

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 clone:

   $ git clone git://git.launchpad.net/~bluetooth/bluez
   $ git remote add launchpad git+ssh://USERNAME@git.launchpad.net/~bluetooth/bluez
   

4. Start working on master:

   $ git checkout master
   

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

   $ git pull git://git.kernel.org/pub/scm/bluetooth/bluez.git

6. Push that latest upstream code to Launchpad:

   $ git push launchpad master

7. Decide what upstream version of BlueZ you want. It will either be existing in the archive here:

   https://launchpad.net/ubuntu/+source/bluez
   or it will be a newer version mentioned here:
   http://www.bluez.org/

8. 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.

9. 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

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

11. Make the intermediate branch into a perfect copy of the release tarball:
    $ git checkout 5.41-tarball
    $ git rm .gitignore .mailmap
    $ diff -qr . <path-to-extracted-release-tarball>
    and add/remove files from git until they are identical (the only remaining difference is the existence of the .git directory). Ensure that as many files remain unchanged in git as possible so they keep a nice history (ie. don't remove and then re-add files. You should only remove, or add.)
    $ git commit

12. Now the 5.41-tarball branch is finished. You will never need to modify or check it out again. So go back to master:
    $ git checkout master

13. Create a branch for your Ubuntu series:
    $ git branch yakkety 5.41-tarball

14. Assuming your Ubuntu series already contains a release from the above BlueZ version then Downloads and import it into git:
    $ git checkout yakkety
    $ tar xJvf ~/Downloads/bluez_5.41-0ubuntu3.debian.tar.xz
    $ git add debian
    $ git commit
    And create some tags so you can refer to that release easily:
    $ git tag 5.41-0ubuntu3
    $ git tag yakkety-release
    Note: Patches are never applied in git commits. They exist as debian/patches/* only. This avoids conflicts with changes from upstream.

15. Save your new branches to:
    $ git checkout 5.41-tarball
    $ git push --tags launchpad 5.41-tarball
    $ git checkout yakkety
    $ git push --tags launchpad yakkety
    

Updating to a newer upstream version

(these steps are from memory, not retested because I'd already done it)

1. Download the official release tarball: http://www.bluez.org/

2. Update your master branch and do not proceed until it contains the official release tag from upstream:
   $ git tag -l 5.45

3. Make an intermediate branch for the new tarball release per above steps 8-11. For example:
   $ git branch 5.45-tarball 5.45
   And follow the previous steps 8-11.

4. Choose which Ubuntu distro to target:
   $ git checkout artful

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

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

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

8. Test Debian packaging works in the current directory, and iterate until it does work.
9. 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).