X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=beyond-pkging.dbk;h=1562f8f6c87f0f1fdff8bbbec052af16032d834b;hp=cafbbd39f0a7f9a9318bee4a7dcceab416fe1f82;hb=b5bd78d4bb84a0450d509fc20ec0df7c34fd040b;hpb=81c0e6409c7dfef4af519821a76dbfadb7dd4758 diff --git a/beyond-pkging.dbk b/beyond-pkging.dbk index cafbbd3..1562f8f 100644 --- a/beyond-pkging.dbk +++ b/beyond-pkging.dbk @@ -326,85 +326,233 @@ describes how to help new prospective developers. Sponsoring packages Sponsoring a package means uploading a package for a maintainer who is not able -to do it on their own, a new maintainer applicant. Sponsoring a package also -means accepting responsibility for it. +to do it on their own. It's not a trivial matter, the sponsor must verify +the packaging and ensure that it is of the high level of quality that +Debian strives to have. - -New maintainers usually have certain difficulties creating Debian packages — -this is quite understandable. That is why the sponsor is there, to check the -package and verify that it is good enough for inclusion in Debian. (Note that -if the sponsored package is new, the ftpmasters will also have to inspect it -before letting it in.) +The process of sponsoring a package is: + + +The maintainer prepares a source package (.dsc) and puts it online +somewhere (like on mentors.debian.net) or even better, provides +a link to a public VCS repository (see ) where +the package is maintained. + + +The sponsor downloads (or checkouts) the source package. + + +The sponsor reviews the source package. If she finds issues, she +informs the maintainer and asks her to provide a fixed version (the +process starts over at step 1). + + +The sponsor could not find any remaining problem. She builds the +package, signs it, and uploads it to Debian. + + -Sponsoring merely by signing the upload or just recompiling is definitely not recommended. You need to build the -source package just like you would build a package of your own. Remember that -it doesn't matter that you left the prospective developer's name both in the -changelog and the control file, the upload can still be traced to you. +Before delving in the details of how to sponsor a package, you should +ask yourself whether adding the proposed package is beneficial to Debian. -If you are an application manager for a prospective developer, you can also be -their sponsor. That way you can also verify how the applicant is handling the -'Tasks and Skills' part of their application. +There's no simple rule to answer this question, it can depend on many +factors: is the upstream codebase mature and not full of security holes? +Are there pre-existing packages that can do the same task and how do they +compare to this new package? Has the new package been requested by users +and how large is the user base? How active are the upstream developers? + + +You should also ensure that the prospective maintainer is going +to be a good maintainer. Does she already have some experience with other +packages? If yes, is she doing a good job with them (check out some bugs)? +Is she familiar with the package and its programming language? +Does she have the skills needed for this package? If not, is she able +to learn them? - - -
-Managing sponsored packages -By uploading a sponsored package to Debian, you are certifying that the package -meets minimum Debian standards. That implies that you must build and test the -package on your own system before uploading. +It's also a good idea to know where she stands towards Debian: does +she agree with Debian's philosophy and does she intend to join Debian? +Given how easy it is to become a Debian Maintainer, you might want +to only sponsor people who plan to join. That way you know from the start +that you won't have to act as a sponsor indefinitely. +
+Sponsoring a new package -You cannot simply upload a binary .deb from the sponsoree. -In theory, you should only ask for the diff file and the location of the -original source tarball, and then you should download the source and apply the -diff yourself. In practice, you may want to use the source package built by -your sponsoree. In that case, you have to check that they haven't altered the -upstream files in the .orig.tar.{gz,bz2,lzma} file that they're -providing. +New maintainers usually have certain difficulties creating Debian packages — +this is quite understandable. They will do mistakes. That's why sponsoring +a brand new package into Debian requires a thorough review of the Debian +packaging. Sometimes several iterations will be needed until the package +is good enough to be uploaded to Debian. Thus being a sponsor implies being +a mentor. + + +Don't ever sponsor a new package without reviewing it. The review +of new packages done by ftpmasters mainly ensures that the software +is really free. Of course, it happens that they stumble on packaging +problems but they really should not. It's your task to ensure that +the uploaded package complies with the Debian Free Software Guidelines and +is of good quality. + + +Building the package and testing the software is part of the review, but +it's also not enough. The rest of this section contains a non-exhaustive +list of points to check in your review. + + +You can find more checks in the wiki where several developers share their own +sponsorship checklists. + + + + + +Verify that the upstream tarball provided is the same that has been +distributed by the upstream author (when the sources are repackaged for +Debian, generate the modified tarball yourself). + + +Run lintian (see ). It will catch many common +problems. Be sure to verify that any lintian overrides setup by the +maintainer is fully justified. + + +Run licensecheck (part of ) and verify that +debian/copyright seems correct and complete. Look for +license problems (like files with “All rights reserved” +headers, or with a non-DFSG compliant license). grep -ri +is your friend for this task. + + +Build the package with pbuilder (or any similar tool, see ) to ensure that the build-dependencies are +complete. + + +Proofread debian/control: does it follow the +best practices (see )? Are the dependencies +complete? + + +Proofread debian/rules: does it follow the +best practices (see )? Do you see some +possible improvements? + + +Proofread the maintainer scripts (preinst, +postinst, prerm, +postrm, config): will the +preinst/postrm work when the dependencies are not +installed? Are all the scripts idempotent (i.e. can you run them multiple +times without consequences)? + + +Review any change to upstream files (either in .diff.gz, or in +debian/patches/ or directly embedded in the debian +tarball for binary files). Are they justified? Are they properly +documented (with DEP-3 for patches)? + + +For every file, ask yourself why the file is there and whether it's +the right way to achieve the desired result. Is the maintainer following +the best packaging practices (see )? + + +Build the packages, install them and try the software. Ensure you can +remove and purge the packages. Maybe test them with piuparts. + + -Do not be afraid to write the sponsoree back and point out changes that need to -be made. It often takes several rounds of back-and-forth email before the -package is in acceptable shape. Being a sponsor means being a mentor. +If the audit did not reveal any problem, you can build the package and +upload it to Debian. Remember that even if you're not the maintainer, +the sponsor is still responsible of what he uploaded to Debian. That's +why you're encouraged to keep up with the package through the +. -Once the package meets Debian standards, build and sign it with +Note that you should not need to modify the source package to put your name +in the changelog or in the control file. The Maintainer +field of the control file and the +changelog should list the person who did the +packaging, i.e. the sponsoree. That way she will get all the BTS mail. +Instead you should instruct dpkg-buildpackage to use your key for +the signature. You do that with the -k option: dpkg-buildpackage -kKEY-ID +If you use debuild and debsign, you can even configure it permanently +in ~/.devscripts: + +DEBSIGN_KEYID=KEY-ID + +
+ +
+Sponsoring an update of an existing package -before uploading it to the incoming directory. Of course, you can also use any -part of your KEY-ID, as long as it's unique in your -secret keyring. +You will usually assume that the package has already gone through a full +review. So instead of doing it again, you will carefully analyze the +difference between the current version and the new version prepared by the +maintainer. If you have not done the initial review yourself, you might +still want to have a more deeper look just in case the initial reviewer +was sloppy. -The Maintainer field of the control file and the -changelog should list the person who did the packaging, -i.e., the sponsoree. The sponsoree will therefore get all the BTS mail about -the package. +To be able to analyze the difference you need both versions. Download the +current version of the source package (with apt-get source) +and rebuild it (or download the current binary packages with +aptitude download). Download the source package to sponsor +(usually with dget). -If you prefer to leave a more evident trace of your sponsorship job, you can -add a line stating it in the most recent changelog entry. +Read the new changelog entry, it should tell you what to expect during the +review. The main tool you will use is debdiff (provide by +the devscripts package), you can run it with two source packages (.dsc +files), or two binary packages, or two .changes files (it will then +compare all the binary packages listed in the .changes). -You are encouraged to keep tabs on the package you sponsor using . +If you compare the source packages (excluding upstream files in the case +of a new upstream version, for example by filtering the output of debdiff +with filterdiff -i '*/debian/*'), you must understand all the +changes you see and they should be properly documented in the Debian +changelog. + +If everything is fine, build the package and compare the binary packages +to verify that the changes on the source package have no unexpected +consequences (like some files dropped by mistake, missing dependencies, +etc.). + + +You might want to check out the Package Tracking System (see ) to verify if the +maintainer has not missed something important. Maybe there are translations +updates sitting in the BTS that could have been integrated. Maybe the package +has been NMUed and the maintainer forgot to integrate the changes from the +NMU in his package. Maybe there's a release critical bug that he has left +unhandled and that's blocking migration to testing. Whatever. If you find +something that she could have done (better), it's time to tell her so that +she can improve for next time, and so that she has a better understanding +of her responsibilities. + + +If you have found no major problem, upload the new version. Otherwise +ask the maintainer to provide you a fixed version. + +
-
+
Advocating new developers See the page about at the Debian web site.
-
+
Handling new maintainer applications Please see Checklist