Meeting the right people, joining the right teams
In order to do any work on Sugar in Debian, you *should* have the following:
An account on Alioth.
A subscription to the debian-olpc-devel mailing list
Membership in the debian-olpc and collab-maint Alioth teams.
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:
- sudo apt-get build-dep PACKAGE_NAME
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:
- 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
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
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:
?Debian New Maintainer's Guide
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.
In changelog, rules, and control.in, replace PACKAGE_NAME as well as package-name with the name of your package. In our case, it is sugar-colors-activity.
In changelog, copyright, and control.in, replace YOUR_NAME <YOUR_EMAIL> with your name and email address. For me, I used Luke Faraone <luke@faraone.cc> You can use any email address you like, but keep in mind that the email will be publicly viewable and people may use it to try to contact you about your work. Do not use something that will only be temporary, and use the same one for yourself across packages.
In changelog, replace VERSION with the upstream package version part. In this case, we want 15, since we're packaging Colors!-15.
In control.in and copyright, replace NAME_OF_ACTIVITY with the activity name. This is what comes in between the "sugar-" and "-activity", but capitalized. In our case, use "Colors".
In copyright, update the file to match the contents of the actual package. Check each file to ensure it is under the same license as the entire project, and that all authorships are represented. If a file is under a different license or author, this is fine, but list it in its own block on copyright file.
In control.in, change SHORT_DESCRIPTION to a one-line (80 characters max, including "Description: ") summary of the package. Likewise, change SOMETHING and DESCRIBE_MORE_IN_DEPTH to more lengthy descriptions of what the package does.
In watch, include the URL to find upstream source in the proper format. Read the manual page for uscan(1) for more information on how to write watchfiles. In our case, we'll use http://download.sugarlabs.org/sources/honey/Colors/Colors!-(.*).tar.bz2. We escape the "."s with ""s after the "(.*)" so they are not misinterpreted as part of the regular expression.
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
See http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.building.html for information about building packages.
Uploading the package!
Seek a sponsor on the debian-olpc-devel mailing list. Provide a link to your repository (you *have* been pushing your changes to Alioth, right?), a short description of the package, and the link to your ITP.