Meeting the right people, joining the right teams

In order to do any work on Sugar in Debian, you *should* have the following:

Everything but the membership in teams does not require approval. When requesting membership, briefly explain who you are, and that you're interested in packaging Sugar on Debian. Consider also sending an email introducing yourself to the mailing list.

For those coming from a background working on Debian derivatives, you may like to review of https://wiki.ubuntu.com/Debian/ForUbuntuDevelopers, which explains the differences between Debian, and one of its primary derivatives.

How to Package using Git

In this section, we'll cover the basics of modifying and creating new Debian packages in Git with collab-maint.

An aside: once you have the upstream source directory for a package, before taking any further action *always* read debian/README.source and debian/README.packaging if they exist, as they often detail critical per-package nuances that you need to take in to account. Said files trump instruction in this page. When in doubt, ask.

Setting up your environment

You should have git-core, git-buildpackage, devscripts, and pristine-tar installed. For each package you work on, you may have additional dependencies. If the package is already in Debian, you can usually automatically install said dependencies using:

Alternatively, install them manually.

Make sure your DEBEMAIL and DEBFULLNAME values are set properly in your ~/.bashrc first. If they are not, add these lines to your ~/.bashrc and then run source ~/.bashrc:

export DEBFULLNAME="John Q. Public"
export DEBEMAIL="jqpublic@example.com"

... replacing those values with those appropriate for you.

Do the same with Git:

git config --global user.name "John Q. Public"
git config --global user.email "jqpublic@example.com"

Updating an existing package

Debian's Sugar packages are maintained in Git on http://git.debian.org/. Visit that site to find the name of the repository you want to modify. In this case, we'll use the sugar-memorize-activity.

Checkout the package from git.

There are three ways to do so, in order of declining preference:

  1. Checkout using the source record. This requires the least effort, and usually gets you the most up-to-date repository.

debcheckout sugar-memorize-activity
cd sugar-memorize-activity
  1. Checkout using the repository URI via gbp-clone. This has the advantage of automatically setting everything you need to begin working in one command, and is useful if the system you are on lacks package source records or does not have the proper repository URIs.

gbp-clone git://git.debian.org/collab-maint/sugar-memorize-activity.git
cd sugar-memorize-activity
  1. Checkout manually using git clone and the repository URI.

git clone git://git.debian.org/collab-maint/sugar-memorize-activity.git
cd sugar-memorize-activity
git checkout -b upstream --track origin/upstream

The --track option altered the .git/config file and added a [branch "upstream"] section telling Git where you fetched it from. That means you can later just run git pull and you will get both the 'master' and the 'upstream' repository merged into your repository automatically.

Download the new upstream version, 33 at the time of this writing, from http://download.sugarlabs.org/sources/honey/Memorize/. Rename the resulting tarball to the proper Debian format: package-name_version.orig.tar.format.

wget -P .. http://download.sugarlabs.org/sources/honey/Memorize/Memorize-33.tar.bz2
mv ../Memorize-33.tar.bz2 ../sugar-memorize-activity_33.orig.tar.bz2
git-import-orig --pristine-tar ../sugar-memorize-activity_33.orig.tar.bz2

Now update debian/changelog:

dch -v 33-1

The part before the "-" is the upstream version number part, in this case "33". The second part is the so-called Debian Revision. If you are uploading this package to Debian, it should start with "1" and continue upward until the upstream version part changes, in which case it should be set back to "1". If you are uploading to Ubuntu, use "0ubuntu1" and only increment the number after the "ubuntu" part. If you are uploading to a PPA, start with "0ppa1".  dch will open up an editor to modify the changelog. Usually you say "New upstream version", and on separate bullet points describe any other noteworthy changes in the package. When you are done, quit the editor.

After finishing your changes, commit them with git commit. This records them in the history of the local repository. When you need to submit your changes to Debian proper, if you are a member of the collab-maint group on alioth.debian.org and can access the repository directly, use a command such as the following to push up your changes:

git push ssh+git://git.debian.org/git/collab-maint/sugar-memorize-activity.git master

Contributing a new package

Starting packaging is covered by many guides, and this document does not attempt to be comprehensive. See the following for more info:

Most Debian Sugar packages are maintained using a system known as CDBS, or the Common Debian Build System.

We'll start out with a skeleton debian/ directory I adapted from other packages. You can find it at: http://people.ubuntu.com/~lfaraone/sugar/initial_debianization.tar.gz

Initialize the git repository:

mkdir colors-15
cd colors-15
git init

Then you import the upstream sources. In this case, we'll use Colors!-15.tar.bz2

wget -P ..  http://download.sugarlabs.org/sources/honey/Colors/Colors!-15.tar.bz2
git-import-orig --pristine-tar -u ''15'' ../Colors!-15.tar.bz2

Now, extract the initial_debianzation.tar.gz file into the current directory:

wget -P .. http://people.ubuntu.com/~lfaraone/sugar/initial_debianization.tar.gz [[BR]]tar xf ../initial_debianization.tar.gz

Now, of the files in this directory, there are a few you need to modify.

Regenerate debian/control from debian/control.in:

DEB_MAINTAINER_MODE=1 fakeroot debian/rules clean

Read debian/control. In debian/control.in, add beyond @cdbs@ the other things you need to build the package. For Colors!, we read in INSTALL that we need to add swig, gtk2-devel, python-devel, gstreamer-devel, pygtk2-devel.

In control.in, replace EXTRA_DEPENDENCIES with anything else the package requires to run. This is usually documented in the README or INSTALL file of that package.  When you're done, be sure to run dch -r to update the timestamp of your changelog.

Finally, add your work to the repository:

git add debian/

Then run debcommit to save your changes.

Replace BUG_NUMBER with the number of your Intent to Package. If you don't have one, file one via the instructions at [http://www.debian.org/devel/wnpp/#l1]

Building the package

Uploading the package!