This page is a mirror of http://people.debian.org/~mpalmer/debian-mentors_FAQ.html.
Matthew Palmer <firstname.lastname@example.org>
This FAQ is intended to head off the standard set of questions asked by a large proportion of new posters to the debian-mentors mailing list. There are three sections:
If in doubt, just read the whole thing. If you still have your question, ask on the debian-mentors list.
debian-mentors is for the mentoring of new and prospective debian developers. Almost any question relating to Debian development is potentially on-topic for d-mentors. Although there are other lists which deal with most aspects of developing for Debian, they're often pretty hard core and can be daunting. If you think your question might be a little "newbie" for the hardcore developers on debian-devel, then it's probably a good fit for -mentors.
In short, we aim to be the "softer, gentler" Debian development mailing list.
One of the most common uses for the list is to attempt to get a sponsor for a piece of software you've packaged (or are intending to package). It's such a common request that it has it's own section in this FAQ.
Things that aren't really appropriate for -mentors:
This is a very difficult question to respond to, because there's so many different things that could be done, and we don't know what you're really interested in doing. Particular problems include:
If you really are keen on getting involved in random places in Debian, there are lots of resources in the question "What can I do to help Debian other than packaging?", below.
The perennial question. As provided by Andreas Metzler (I couldn't have put it better myself, so why bother trying?):
Apart from the debian-mentors mailing list, there are a wealth of useful places and documents which the aspiring developer can use to improve themselves:
Excellent question! Debian is a lot more than a great big collection of random packages. There's documentation to write and translate, bugs to fix, installers to test, and newbies to haras^H^H^H^H^H, uh, help.
If you write a language other than English fairly well (either because you're a native speaker or you've spent the time to learn) then consider helping out with translations. Everything in Debian needs to be translated, more or less - package descriptions, debconf questions, all of our documentation, etc. There are a lot of clever people involved there - be one of them! Translation work is mostly handled through http://www.debian.org/international/. Most translation projects can be found from there.
There are many thousand open bugs in Debian packages, ranging from the trivial to the critical. Consider looking in the Bug Tracking System for packages that you use often. Try and reproduce a bug, or find the cause of the bug and submit a patch to the bug listing, so that the maintainer can fix the bug. If a bug has one or more patches that haven't been applied in a long time, especially for more serious bugs, and the maintainer hasn't commented, consider bringing the package to the attention of the Quality Assurance team (email@example.com) so they can have a look at it. You can find Release Critical bugs for packages installed on your system (in case you might like to help fix them) by running the rc-alert script, which is available in the devscripts package.
Some maintainers have requested some help with their packages, by posting a Request For Help (RFH) on the Work-needing and Prospective Packages list (http://bugs.debian.org/wnpp). A list of current requests for help posted by other people is available from http://www.debian.org/devel/wnpp/help_requested, in case you're feeling helpful.
There is also a list of random "todo" tasks at http://www.debian.org/devel/todo, one or more of which may interest you. Be warned that apparently some of them are somewhat out of date.
Firstly, you may not necessarily have to package something from scratch.
Consider the benefits of co-maintenance. Instead of having to be out on your own, you get a pre-existing, presumably fairly well-maintained package, and someone to answer your questions.
There are quite a number of packages already in the Debian archives which are orphaned - that is, their previous maintainers have given up maintenance of the package for various reasons. The best option, especially for your first packaging attempt, is to adopt one of these orphans. There are also some packages which are still maintained, but which aren't really wanted by their maintainers any more (known as "RFA" packages, for "Request For Adoption").
The benefits of an RFA package are that you have at least one person who might be willing to sponsor your uploads, and you'll have someone familiar with the package who you can ask any questions you have with the packaging.
To find a package to adopt, look for bugs whose title starts with "O:" (for orphaned) or "RFA:" (for "Request for Adoption") under the WNPP bug list. A more convenient method of finding interesting orphans is to install the devscripts package and run wnpp-alert. This will print out all the packages installed on the system you're running which are orphaned. Handy!
For "Request For Adoption" packages, you should contact the current maintainer and ask if they'd be willing to let you maintain it. Some maintainers may be unwilling to let their package go to an inexperienced maintainer for some reason. Please respect their judgement -- they usually have a good reason for not wanting to hand the package off to someone without experience. Also remember to ask the previous maintainer if they might be willing to sponsor your uploads.
Once you've selected a package to adopt, retitle the WNPP bug so it starts with "ITA:" (for Intent To Adopt) and start working on the package. Fix bugs, package new versions, and hunt for a sponsor for your new package. Remember to set the maintainer to you, and to close the WNPP bug in the changelog of your first upload.
Another place to look for packages is in packages which may not be listed as orphaned, but which are in a bad state. This is not something to take on lightly, as what constitutes "in a bad state" may not be immediately obvious. Nevertheless, if there's a program you use which you think is looking a bit shabby and might benefit from a new maintainer (you!) bring it to d-mentors or the debian-qa mailing list with your reasoning, and someone will try and help you out. Please Note: Don't go e-mailing maintainers with e-mails like "Your package looks unmaintained, I'm going to hijack your package". It helps nobody, and ensures that you will have at least one very unhappy Debian developer.
If you've got your eye on something new to package, there is a set procedure to follow. This is covered heavily elsewhere, including the excellent New Maintainers' Guide, but basically:
It is also recommended that you familiarise yourself early on with the Debian Developer's Reference and the Debian Policy, which are, respectively, the HOWTO and Do's and Don'ts (that's some ugly apostrophes) of packaging for Debian. You will need to know all about them if you apply to become a DD, so you should start studying now... <grin>
(Thanks to Paul Wise)
At the basic level, it's a good idea to keep an archive of the completed source packages that get uploaded. Although there are services which keep a record of everything in the archive (such as snapshot.debian.net) there's the hassle of having to go and retrieve your packages from there. A local copy is just that much easier to work with. The debdiff and interdiff programs (in the devscripts and patchutils packages) can help you look at the differences between package versions.
Getting into a more fine-grained approach, consider using a revision control system to store all of the changes you make to your packages. There are *-buildpackage scripts for several of the more popular revision control systems (cvs, svn, darcs, and arch), which will retrieve your package out of revision control and build it for you automatically.
Getting the right workflow with your revision control system can be tricky. A couple of quality references on managing your packages using Arch are http://arch.debian.org/arch/private/srivasta/ and http://debian.madduck.net/pkg-zope/wiki/Arch/Package
(From Matthijs Mohlmann)
It seems a hard problem to understand what a native and a non-native debian package is. And get through the trouble if upstream provide a debian directory in the source. I'll try to explain:
A non-native debian source package contains a dsc, diff.gz and a orig.tar.gz file.
The version for a non-native debian package looks like UpstreamVersion-DebianVersion for example: 2.8-1
In the dsc file contains fields containing information about the debian package it also contains information about the md5sums of the files.
In the diff.gz: These are the modifications you made to the package. It contains the debian directory and the modifications you made to the source tree, if you make use of some patch system like dpatch you have only the debian directory in it.
In the orig.tar.gz: This is the upstream tarball. You should very rarely make changes to this file, and you should never ever make changes unless you explicitly understand why you are making them. All changes should normally go into the diff.gz.
The Version number for a debian native package is only the version, it doesn't have a debian revision number or something, it looks like: 2.8
A native package contains only a dsc and a orig.tar.gz file.
Native debian packages are often accidentally built when upstream tarball (.orig.tar.gz) is named incorrectly.
But when using a native package and when a non-native package: If upstream is not actively involved to debian development then it's non-native debian package. A few examples of normal packages are: libc6, apache, phpmyadmin. But linda, lintian, dpkg and some other tools are purely developed for debian.
It seems that upstream has an debian directory. With upstream i mean the people who write the source code and maintain it. Most of the time these packages are faulty, they have lintian/linda errors and such. It is hard to modify the debian directory. (Specially for New Maintainers)
What to do in this situation: Ask upstream that they remove or rename the directory to something else. Or ask them to remove the debian directory from the released source (so that the orig.tar.gz doesn't contain the debian directory). Last option: you can ask for repository access. So that you can work on a real debian package.
A sponsor is a registered Debian Developer (DD) who takes the packages of a non-DD and uploads them to the archive on the non-DD's behalf. The sponsor is required to check the quality of the package, that there are no show-stopping bugs in it, and that it is unlikely to harm either the Debian infrastructure during build, nor user's systems when in use.
The sponsor needs to do all of this because they are ultimately responsible for what gets uploaded by them into the archive.
You need a sponsor because, as a non-DD, you do not have the ability to upload packages directly into the Debian archive. So, you need to route your packages through a sponsoring DD so they can be properly signed and uploaded.
The presence of the sponsor doesn't mean you can neglect your maintainership duties. You are listed as the maintainer - it's your reputation on the line too. You are expected to keep a handle on bugs and new upstream versions, feed information from Debian users back to upstream, and generally uphold Debian's reputation. If you "dump" poor quality packages on sponsors, or do not maintain your packages well, do not expect to get many people willing to sponsor you.
<yoda>Scared? You will be...</yoda>
A sponsor is any Debian Developer willing to upload packages on your behalf into the Debian archive. You may have multiple people who act as sponsors for your packages - different people for different types of packages, or maybe you change sponsors over time, or rotate between a few (with the knowledge of all of them) to spread the load.
An advocate is a Debian Developer who has worked with you in your capacity as a contributor to Debian, and believes you would be an asset to Debian. When you are ready to apply for New Maintainership, the advocate makes a statement to the effect that they believe you would be a worthwhile addition to Debian, and your application moves forward. Without an advocate, your application cannot proceed.
There is no point asking for an advocate on debian-mentors or any other open mailing list. No developer should be willing to advocate for you without knowing something about you.
Which Debian Developers have you done Debian-related work with? Typically, if you're ready for NM, you should have worked with at least one, if not several. Ask them. If you've done good work, they should be more than happy to say that to the Front Desk via an advocacy. Get them to ask on debian-mentors if they're not sure exactly what advocacy is, when it should be done, and how.
One of your sponsors can be your advocate, and this would probably be the most common way of obtaining an advocate. But if you've had significant contact with any other DD, you can consider asking them.
First thing - there is no guarantee that anyone will sponsor your package. It all depends on the interest level and time available from any DD who might sponsor you.
The general rule is to make a request on debian-mentors for a sponsor. Put "RFS:" (Request For Sponsor) at the beginning of the subject of your message. Things to put in the message are:
Messages without all this information are far more likely to be ignored.
Your message to -mentors is like an ad for your package. It's likely to be the only thing that prospective sponsors will judge your package on. You can have all the extra URLs you like in there where sponsors can get more information, but unless your initial message piques their interest, they'll never look at them.
So, tell us what exactly your package does, and why it should be in Debian. If there is already a program that does a similar thing, say why your one is better. Put a little "hot spice" in there to hold people's interest. in other words, think like an advertising executive. Just remember to wash the slime off afterward.
You'll notice that one of the things to have is where the package can be downloaded from. That implies that you've packaged it already. Don't bother asking for a sponsor until you've got packages (more-or-less) ready to download.
Sponsoring a package takes a lot more than just downloading it from your website and uploading it to Debian. The prospective sponsor needs to check over the quality of the packaging and ensure that it meets Debian's quality standards before uploading it. For this reason, you need to provide all of the parts which would be needed for a full upload (.changes, .dsc, .orig.tar.gz, .diff.gz, and .deb(s)). Also, it may take a few days/weeks to get the whole package checked over, and the sponsor might want to talk to you a bit, just to find out what sort of a person you are.
Think of all this as a mini-NM check - which is, basically, what it is.
Don't forget to register your need for a sponsor on http://sponsors.debian.net/ so that it doesn't get forgotten.
You shouldn't be generating a first package "just to get it in debian". The archive is already well-stocked with poorly-maintained vanity packages. A first package, especially, should be something that you really want to see in Debian but which hasn't been uploaded already for whatever reason. That personal interest will help keep your interest levels up.
It is important to remember that an upload isn't a one-off thing - you're responsible for that package forevermore, unless you request it's removal or find another suitably qualified person to maintain it for you. It's like having a child - a big responsibility.
debian-mentors isn't the only place where you can get a sponsor. In general, you're more likely to get a sponsor who is actually interested in what you've packaged, but doesn't have time to package it themselves. So, if there's a list dedicated to your "niche market", Cc: the RFS there. For instance, if you're packaging Yet Another Perl Module, try a Cc: to firstname.lastname@example.org. If it's YAPython Module, email@example.com. Apache module? firstname.lastname@example.org. Something legal-related? email@example.com. Something for kids? firstname.lastname@example.org. Getting the picture yet?
Also, if you're packaging something in a particular technological line, you'll probably want to be subscribed to the relevant speciality mailing list anyway, so you can ask technology-specific questions to the people who know all about it.
First off, don't panic. Not having your package in Debian immediately isn't the end of the world.
Solicit comments on the packaging on IRC and d-mentors. Don't just mention the package name, also fling the brief description around a bit. Typically a developer is more likely to sponsor something they might be interested in using, or which they recognise there might be a need for. Just the package name doesn't really convey the sort of information needed to make that call.
Sometimes RFS' fall through the cracks, so register your need for a sponsor on http://sponsors.debian.net/ so that it doesn't get lost in the mailing list archives. Continue updating the package. Mention the package on d-mentors every month or two; people come and go, and their available time varies, so a later mention may catch someone who couldn't help you before.
Try to get it uploaded to Ubuntu's REVU, you will probably get lots of good comments on your package in the process, and perhaps someone from Utnubu will notice that your package was uploaded to Ubuntu and offer to sponsor it for you.
Meet some Debian folk in your area or at DebConf and bribe them to sponsor you :) It's a lot easier for someone to commit some time to helping you if they've got a face and real personality to put to the e-mail address (plus it's a great excuse to get some keysigning action happening).
Fix lots of bugs, get involved in doing QA work, perhaps you will get to know a DD well enough that they will sponsor you.
Any Debian Developer with a key in the keyring can sponsor a package on behalf of another maintainer. There is no special "register" of sponsors. Note that sponsorship is rarely a one-off event; you need to be able to handle regular uploads on behalf of your "sponsee". If you can only do a once-off upload, make your prospective sponsee aware of this up-front, and try to find someone else who will be able to continue the sponsorship process in the future if required.
You need to get the *source* package from your sponsee. That is, the .dsc, .orig.tar.gz, and .diff.gz. You should check the package over carefully, perhaps with reference to my sponsorship checklist. If there are problems, provide constructive feedback to the sponsee. Work with them to make the package the best it can be. Build the package on your system, try it out -- does it install/remove properly, does the program run, is it policy compliant? All of the things you're supposed to do for your own packages. Yes, it's a lot of work, but you're responsible for any crud that lands in the archive under your key.
Immediately before upload, rebuild the package in a clean sid chroot, sign the .changes/.dsc file with your key, and then make a normal upload. Make sure your name isn't in the Maintainer: or Changed-By: headers of the .changes file. You can ensure this by either using the -k option to dpkg-buildpackage/debuild, or building without signing (-uc -us) and then using debsign to later sign the .changes file (which will sign the .dsc as part of the process). Do not use the -m or -e flags to dpkg-buildpackage/debuild, as that actually changes the maintainer/uploader information in the .changes/.dsc, which is most certainly not what you want.
Whatever you do, do *not* simply re-sign and upload the sponsee's .dsc/.changes, or (worse!) just upload what they send you (since it won't be properly signed).
You should work out a mutually-agreeable way for your sponsee to contact you to upload new versions of their package. Upload to http://mentors.debian.net/ (with notification to you, the sponsor) is a good way to go, especially if the sponsee doesn't have web space of their own.
You should do appropriate checks of each new revision your sponsee provides. The interdiff tool (from the patchutils package) is excellent for getting an overview of what has changed between Debian revisions (although it doesn't work so well between upstream versions, unfortunately).
Copyright © 2003,2004,2005 Matthew Palmer. Released under the terms of the GNU General Public License version 2. I consider both the source and binary forms of this work to be the HTML source provided in this webpage.