[Debian-olpc-devel] Feedback on Debian/Ubuntu Sugar packaging guide

Fri May 14 17:53:17 UTC 2010

Hi Luke (and others),

[cc'ing only non-subscribers of the Alioth OLPC list]

On Fri, May 14, 2010 at 12:02:44PM -0400, Luke Faraone wrote:

>On 05/14/2010 11:04 AM, Jonas Smedegaard wrote:
>> Would you mind instead (or in addition) to publish it up at
>> http://wiki.debian.org/Sugar or a subpage of that?
>
>Done. See http://wiki.debian.org/Sugar/GettingStartedGuide for the
>wiki-fyed version of that.

Great initiative!

Here are some comments:

I suggest generalizing to talk about "Debian and derivatives", rather 
than "Ubuntu and Debian".  I imagine that only slight loss for your 
specific target group and a potential bigger gain (others reading it, 
and more people interesting in maintaining the text) if generalized.

You might want to mention setting git username and email too, in 
addition to dpkg hints.

The "Debian way" to check out already released packaging projects is 
using "debcheckout"ma git-buildpackage way is using "gbp-clone".  You 
might want to mention those (in that order) before the "git checkout" 
approach.

Please instruct (early in the text!) to always read debian/README.source 
if it exists!  As an example, sugar-browse-activity (and most other 
activities) track not only tarball releases but also upstream git, so is 
slightly more convoluted to upgrade to newer upstream release.

You describe importing a new upstream release.  I would suggest to first 
use a simpler example of e.g. adjusting a grammatical typo in a long 
description field in debian/control (and then mention to instead edit 
debian/control.in instead if that file exist, commit the change, 
regenerate debian/control, and commit the autogenerated change 
separately).

Your description of importing new upstream source is wrong: The tarball 
needs to be renamed to the proper Debian naming format _before_ imported 
- else some git-buildpackage magic won't work.

Also, when using the CDBS snippet upstream-tarball.mk, download and 
renaming is done automagically: debian/rules get-orig-source

You instruct to commit changes to Alioth _after_ releasing to derived 
distro.  I recommend to work mostly at Alioth, and only apply the parts 
specific to that derived distro locally.  Example:

 1. Checkout from Alioth
 2. Edit that generally useful change (e.g. typo in description)
 3. Push to Alioth
 4. Prepare release for derived distro (using "git dch" and editor)
 5. Build with --git-ignore-new (or push to custom Git repo, then build)

You introduce CDBS as hiding details and that "it can often be difficult 
to understand."  I do not disagree with either, but find the remark 
might be either of little use or outright confusing, depending on the 
knowledge and experience of the audionce:  Same remarks can be equally 
be applied to debhelper!

I suggest to instead mention that CDBS hides details _differently_ than 
short-form debhelper v7, and is actually _less_ hidden than debhelper, 
which I believe is what makes it difficult for some: it is a bunch of 
include files in the "make" language which we all use but some do not 
understand intimately.

I dislike how you encourage using a pre-made template for their 
packaging efforts.  Do you intend to maintain that template?  It has 
some bugs in it already - like not conforming to draft 135 of DEP-5 
(e.g. wrong ordering of files sections).

I suggest to instead encourage looking at existing packages.  Not a 
single one, but multiple.  Mention a couple of good - and varying - 
examples, and tell what more specifically to look for.  Like read the 
changelog entries (and the git commit messages, to understand how 
changes evolved). And which things are frequently updated, which almost 
only declared initially, and which are autogenerated (e.g. using CDBS).

You instruct to "branch off the upstream-branch branch"?  That one is 
tied to tracking upstream git (not upstream tarball releases), which you 
seem to not use at all.

You mention using dh_make.  That contradicts somewhat your earlier 
encouraging use of your prepared skeleton tarball.  If you do want to 
mention dh_make, then perhaps also mention its --cdbs option.  (I used 
dh_make only long time ago, before CDBS and even its predecessor, DBS, 
so cannot speak of its quality).

You mention max line width of 80 chars.  I would recommend to keep it 
below 72 chars (and believe that is what automated tools do too).

Instead of adding additional build-dependencies to the control.in file, 
they can instead be included to DEB_BUID_DEPENDS variable in the rules 
file.  This has the benefit of being easy to add comments, and do 
variable expansions (good examples of this are source packages like 
"sugar-0.86" and ghostscript package which would be a nightmare to 
maintain if throwing their many many package relations directly into the 
control(.in) file.

Please do not use debcommit to commit changes.  Instead, use "git 
commit" and from time to time "git dch" + manual cleanup + git commit of 
the changelog file separately.

The reason for this is that if "real" changes and autogenerated ones are 
commited separately, then it is much easier to later use the more 
advanced parts of git, like revert or cherry-pick.

Please do not encourage working outside Alioth and then pass the results 
to "a member of the collab-maint group".  Instead instruct to become 
members of Alioth and the collab-maint team at the top.  Let us all work 
together - and be on a mailinglist together, to learn from discussions 
of others too.  As I see it, everyone interested in packaging Sugar 
activities the Debian way should join this mailinglist and get access to 
our Git (i.e. become members of the collab-maint group) - even if only 
to hang out here and do any real work some other secret place.

Phew.

Hope this is useful.  I really appreciate your effort.  Even as-is it is 
very useful, don't take my massive amounts of comments as sign of the 
opposite :-)

 - Jonas

P.S.

Manusheel, please do consider joining our mailinglist.  You can 
subscribe here: 
http://lists.alioth.debian.org/mailman/listinfo/debian-olpc-devel

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

  [x] quote me freely  [ ] ask before reusing  [ ] keep private
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.alioth.debian.org/pipermail/debian-olpc-devel/attachments/20100514/b7c50094/attachment-0001.pgp>