Deprecating the wiki-based Packaging Guide

[Andrew Starr-Bochicchio]

Hi Emmet!

On Mon, Dec 17, 2012 at 8:11 PM, Emmet Hikory <persia at ubuntu.com> wrote:
> Andrew Starr-Bochicchio wrote:
>> On Mon, Dec 17, 2012 at 4:53 PM, Benjamin Drung <bdrung at ubuntu.com> wrote:
>> > Am Montag, den 17.12.2012, 16:01 -0500 schrieb Andrew Starr-Bochicchio:
>> > Will these bugs tracked and fixed before step four? We should only
>> > remove the wiki based guide if all missing pieces from it are available
>> > in the Sphinx-based packaging guide.
>>
>> That said, I do think it is important to point out that "all missing
>> pieces" will never be completely ported to the new guide.  A large
>> part of the reason for making the new guide in the first place has
>> been to streamline it, making opinionated decisions of what to
>> include, and eliminate the "choose your own adventure" style of the
>> old guide. For instance, do we really need to discus desktop files and
>> POD based manpages in the Packaging Guide?
>
>     While I'm all in favour of a return to a managed (and packagable)
> packaging guide, I think there is value in being clear that folk who wish to
> package have a plethora of options available: by all means, let's advocate the
> latest labour-saving mechanisms, but at the same time, I think we need to
> avoid anything that implies there is some magic one true way to package.  At

There are many acceptable toolchains and approaches to packaging. My
understanding of the aim of the "new"  packaging guide [1] is not to
suggest that there is one correct way to do things, but to provide a
much clearer point of entry than the wiki guide.

> least in the current text presented at developer.ubuntu.com, the suggestions
> on packaging new software recommend local compilation, which often hides all
> sorts of issues, although it significantly reduces the apparent setup required
> to get involved: I don't believe there is a good answer as to how folk should
> do this: some may prefer to set things up to match what they think most
> developers use, and others may just want to get something done.

I'd be interested in the exact section you are referring to. "Getting
Set Up" suggests the installation of pbuilder, and "Tutorial: Fixing a
bug in Ubuntu" uses pbuilder-dist to compile. Am I misunderstanding
what you mean by "local?"

> we're recommending use of dh-make, and then recommending deleting all the
> example files that it produces: this is another case where there may be more
> value in having two paths: one that goes through the dh-make files, and the
> other that just focuses on changelog, compat, control, copyright, and rules
> (of which 60% are trivially generated automatically).

I'm not sure how this differs from the wiki-based guide where you find
this, for example [2]:

| Running dh_make creates the basic files needed in debian/ and many template
| files (.ex) that may be needed. The Hello program is not very complicated, and
| as we have seen in the section called “Packaging From Scratch”,
packaging it does
| not require much more than the basic files. Therefore, let us remove
the .ex files:
|
| cd debian
| rm *.ex *.EX

The Sphinx-based guide also contains a "knowledge base" article about
files found in the debian directory. I'd be happy to merge a branch
that expands on the "Additional Files" section. [3]

> differently, and as long as we're documenting things that we expect to be
> used not only for new packaging, but also for patching existing packages,
> it behooves us to ensure that we have coverage of all the different ways that
> packages might behave, and some guidance on how to discover when to apply any
> given rune from some assembled grimoire (assuming it will take some practice
> for folk to learn the tools well enough to remember how to do things without
> looking at their notes).
>
>     Aside from my general belief that as long as we are careful to weave folk
> back into some central guide after each diversion, choose-your-own-adventure is
> the right model, I am *completely* certain that we should discuss .desktop
> files in the Packaging Guide: it's the means by which all XDG-compliant
> environments present applications to the user (even Unity, without XDG-menus,
> ends up using an index generated from collected .desktop files to fufill
> searches), and it's something that is often gotten wrong by upstream
> developers (because what makes a .desktop file work nicely on one's workstation
> isn't usually precisely the same as what makes a .desktop file work nicely as
> part of a distribution).  Mind you, that discussion might just be references
> to the XDG spec, the relevant software centre documentation, and a pointer
> to the desktop-file-validate utility along with a couple paragraphs explaining
> why it's important to make it themeable, unique, HIGgy, etc.

Maybe desktop files weren't the best example. While I think it is
telling that no one has mentioned the lack of a section on desktop
files until I mentioned that I personally don't see the need for it in
the packaging guide, I could actually imagine an article that
discussed various pieces needed for software to integrate nicely with
Ubuntu that included information on desktop files. My main point was
that we shouldn't necessarily carry over everything that exists on the
wiki cargo-cult style just because it exists.

Hopefully I haven't thrown us off on a tangent already. Perhaps, at
least in this thread, we should stick to a discussion of what we could
potentially loose by redirecting from (and at a later date deleting)
the wiki-based guide. "What are we lacking that is currently covered
well in the wiki based guide?" rather than a discussion of the
sphinx-based guide's distance from the ideal.


[1] The "new" guide was begun about two years ago now:
https://blueprints.launchpad.net/ubuntu/+spec/ubuntutheproject-community-n-improve-packaging-guide
[2] https://wiki.ubuntu.com/PackagingGuide/Complete#Packaging_from_Scratch
[3] http://developer.ubuntu.com/packaging/html/debian-dir-overview.html#additional-files

Thanks,

-- Andrew Starr-Bochicchio

   Ubuntu Developer <https://launchpad.net/~andrewsomething>
   Debian Developer <http://qa.debian.org/developer.php?login=asb>
   PGP/GPG Key ID: D53FDCB1