[Debian-olpc-devel] Anyone working on packaging sugar-turtleart-activity

Jonas Smedegaard dr at jones.dk
Mon Mar 30 13:21:09 UTC 2009

On Mon, Mar 30, 2009 at 01:31:56PM +0200, Petter Reinholdtsen wrote:
>[Jonas Smedegaard]
>> Great that you work on this.  And nice that you consider the Pippy 
>> packaging an improvement :-)
>I picked Pippy at random, hoping it was a simple package with similar 
>needs. :)

You were lucky then: Pippy is probably the best showcase of Sugar 
activity packaging - it is the one I recommend myself to people wanting 
to get their hands dirty on Sugar activity packaging :-)

>> Would you be interested in maintaining Turtleart together with us at 
>> the OLPC Alioth team?
>Yes, definitely.


>> So far, the team consist of some 10 people but I have done most work 
>> so far.  I am fan of CDBS and Git (as you might have noticed from 
>> that Pippy packaging) so you might consider doing similar for 
>> Turtleart.
>I am not yet up to speed with git, but expect to be able to handle
>that too, and do not have anything against CDBS, so I suspect that
>should work just fine.  Clues and tips on how to add a new package to
>the alioth repository is most welcome.

Attached is a couple of draft documents about packaging. One is the file 
currently included in packages like sugar-pippy-activity and the other 
is an early draft of what became the README.source that I posted earlier 
today.  Both of them contain more details for newcomers to the packaging 

Beware that one of the files describe way too much: Sugar activities do 
*not* use TopGit (I considered that, but learned that even if a very 
powerful tool it cannot handle multiple concurrent versions that I want 
- not for activities but for library packages (called "glucose" 

To elaborate a bit on why I rewrote that file: I am not against 
documenting for newcomers. I just realized while working on it that 
trying to be both accurate and detailed ends in blurring both. A 
newcomer would probably need even more info than I provide anyway, and 
all those details gets in the way of getting a clear overview for 
experienced package maintainers.

Hope those files is helpful, both concretely to kickstart your very 
welcome engagement in Sugar packaging, and also perhaps helpful for 
writing some wiki page or whatever for newcomers.

Don't hesitate to ask about Git: I have become quite a fan of it, and 
learned a few small tricks on how to navigate.

Here's one: The following command enable colored diffs, status messages, 
etc. when using a terminal (i.e. not when piped to a file or similar 
"colorblind" operations):

    git config --global color.ui auto

Kind regards,

  - Jonas

* Jonas Smedegaard - idealist og Internet-arkitekt
* Tlf.: +45 40843136  Website: http://dr.jones.dk/

  [x] quote me freely  [ ] ask before reusing  [ ] keep private
-------------- next part --------------
Packaging hints

This packaging is maintained with the use of Git, using the following

    upstream-git  - master branch of upstream Git source
    upstream      - unpackaged upstream tarballs
    pristine-tar  - binary deltas to recreate pristine tarballs
    master        - Debian packaging

With the above, we can switch between working from upstream released
tarballs and syncing directly with upstream development, both using
git-buildpackage (with its default branch names).

Package sugar-base as example

The rest of this document uses sugar-base as sample package, and some
old actual version numbers from that package - replace with your actual
package as needed...

Getting packaging source from Git repository

The following commands (in an empty dir) fetch and build the package:

aptitude install git-buildpackage
git clone git://git.debian.org/git/collab-maint/sugar-base
cd sugar-base
git fetch origin upstream:upstream

Merging with newer upstream Git tree

The following commands (inside Git repository) updates the local mirror
of upstream source, and merges with our packaging branch:

cd sugar-base
git checkout upstream-git
git pull
git fetch --tags
git checkout master
git pull . upstream-git

The following command shows upstream changes possibly relevant to
mention in changelog (replace "HEAD^" with a reference to actual sync
commit if not invoked right after sync'ing):

git log --pretty="format:%h %s" HEAD^..upstream-git

Doing a package release from upstream tarball

The following command (inside Git repository) imports a downloaded
tarball into the "upstream" and pristine-tarball Git branches (taball
name is recorded too and used later, so make sure to first rename the
tarball to follow Debian naming convention {name}_{version}.orig.{ext}):

git-import-orig --pristine-tar --sign-tags path/to/sugar-base_0.79.0.orig.tar.gz

Check that all files are included in "upstream" branch (don't know why
this fails sometimes):

git status

If some files are "untracked", then do the following to manually add
untracked files to upstream branch and merge them with master branch
(the stash commands puts changelog update aside and restore it again

git stash
git checkout upstream
git add *
git commit -m "Add files mysteriously skipped by git-import-orig."
git checkout master
git pull . upstream
git stash apply

Comment out tarball hash in debian/control, test get-orig-source, and
enable hash line with new hash:

fakeroot debian/rules get-orig-source

Adjust changelog and package, and if satisfied with the result then tag
it, push Git sources and release the package:

git-buildpackage --git-tag --git-sign-tags
[test package...]
git push --all
git push --tags
cd ..
dput sugar-base_0.79.0-1_amd64.changes

Doing a package release from upstream Git snapshot

First, look at upstream development for a good place to release, and tag
by its date, replacing "~" with ".".  Normally just tag the latest
upstream commit, to avoid simply including later upstream work in the
debian diff:

git log --abbrev-commit upstream-git
git tag -s -m "Tag upstream for package release." upstream/0.2.git20080130 61279f8

Adjust changelog and package, and if satisfied with the result then tag
it, push Git sources and release the package:

dch -r -v "0.2~git20080130-0~0jones1" "New upstream Git snapshot."
debcommit -r -a
[test package...]
git tag -s -m "Tag package release." debian/0.2.git20080130-0.0jones1
git push --all
git push --tags
cd ..
dput sugar-base_0.2~git20080130-0~0jones1_amd64.changes

 -- Jonas Smedegaard <dr at jones.dk>  Sat, 08 Mar 2008 01:08:36 +0100
-------------- next part --------------
Building this package for Debian

This source package uses quilt to apply and remove its patches.  Please
refer to /usr/share/doc/quilt/README.source for information about how to
use quilt for source packages.

The quilt series is generated from the Git repository, using TopGit.
This process is documented in /usr/share/doc/topgit/HOWTO-tg2quilt.gz .

The Git repository for this package uses the branch layout described in
the aforementioned TopGit HOWTO.  Specifically, the recommended use of a
separate "build" branch is used, which is initialized using the command
"git checkout -b build origin/build" once after initial cloning.

Releases, both upstream releases imported and packaging releases built,
are handled using git-buildpackage, with all official releases tagged
and signed, and binary diffs of tarballs stored using pristine-tar.
This is documented below /usr/share/doc/git-buildpackage/manual-html/ .

Maintaining packaging build routines

To participate in maintainance of this package (as opposed to deriving
from it), the "upstream" branch is used too, in addition to above standard need  a fully un
recommended to use same methods as for the

To initialize a full local setup for maintaining this package, the
following commands can be used (replace $pkg with actual package name):


This source package wraps debhelper commands and other tedious parts of
the build routines using the CDBS framework.  Please refer to the actual
makefile snippets included from debian/rules for details on their
purpose and ways to override defaults.  Additionally, makefile snippets
included from below /usr/share/cdbs may also be documented in
/usr/share/doc/cdbs/cdbs-doc.pdf.gz .

Adopting above packaging style

To initiate or convert other packages to use above packaging style,
the following steps might work:

1) Have upstream source Git-maintained

Initial step depends on the environment.

  * Changes from older packaging releases can be included.
  * If upstream already use Git, it might make sense to sync with that,
    to allow cherry-picking from newer development.

1a) Start from scratch and clone upstream Git into custom branch:

    mkdir $pkg
    cd $pkg
    git init
    git remote add upstream-repo git://example.org/somewhere $pkg
    git fetch upstream-repo
    git checkout -b upstream-git upstream-repo/master
    git checkout -b master

1b) Start from scratch and inject tarball using git-buildpackage:

    mkdir $pkg
    cd $pkg
    git init
    git-import-src --sign-tags --pristine-tar ../${pkg}_x.y.orig.tar.gz

1c) Start from one or more historical Debian source packages:

    git-import-src --sign-tags --pristine-tar ${pkg}_*.dsc
    cd $pkg

2) Customize debian subdir:

Borrow from this package or other CDBS-based packages, or try this:

    dh_make --cdbs

3) Include this README.source file:

    git remote add cdbs-skel git://git.debian.org/git/collab-maint/cdbs-skel.git
    git pull cdbs-skel master

4) Publish Git clone at collab-maint group on Debian Alioth:

    git remote add origin ssh://$login@git.debian.org/git/collab-maint/$pkg
    ssh $login at git.debian.org "cd /git/collab-maint && ./setup-repository $pkg $pkg Debian packaging"
    git push --mirror

 -- Jonas Smedegaard <dr at jones.dk>  Thu, 26 Feb 2009 21:28:29 +0100
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: Digital signature
Url : http://lists.alioth.debian.org/pipermail/debian-olpc-devel/attachments/20090330/cfa95902/attachment.pgp 

More information about the Debian-olpc-devel mailing list