Deprecating the wiki-based Packaging Guide

[Emmet Hikory]

Andrew Starr-Bochicchio wrote:
> Hi Emmet!

Hi!

> On Mon, Dec 17, 2012 at 8:11 PM, Emmet Hikory <persia at ubuntu.com> wrote:
> >     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.

    Excellent.  This is precisely what the old docbook packaging guide did
before we moved to the wiki.  My apologies for being oversensitive to the idea
of streamlining.

> > 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?"

    I was looking at "Packaging New Software"
http://developer.ubuntu.com/packaging/html/packaging-new-software.html

    The local build in question is `bzr builddeb -- -us -uc`

    Yes, later it recommends pbuilder and PPAs, etc.: the criticism above was
not intended as blanket criticism, but rather a pointer to a possible point of
variance between different ways to address the issue.  Some folk would regard
having performed the local build hard, painful, and bad (especially if the
software in question had many build-deps that were unsatisfied locally).  Others
almost always start with local compilation, considering a build in a structured
environment to be part of the test and deployment phase of their work.  I don't
believe either school of thought is inherently right or wrong, but I do believe
that it is important to make clear that folk who have already set up pbuilder
(as documented in the "Getting Set Up") may alternately do a source-only build
and run the binary build in pbuilder (No, it doesn't matter much for hello, but
nearly all the cross-platform tools that provide front-ends for a variety of
desktop environments can significantly impact the user experience just by having
the build-deps installed).

> > 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

    It doesn't differ significantly at all.  My point was only that I don't think
this represents the best of what we could achieve if we attempt to "streamline it,
making opinionated decisions of what to include and eliminate 'choose your own
adventure' style".  Plus, because there are so clearly two different ways to
introduce folk to all the various sorts of helper files (generally dh_*, but
also some of the older ones), it seemed a good candidate to illustrate the value
of multiple possible streams of documentation.

> 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]

    Heh.  If I had such a branch, I'd be happy to propose it :)  For that matter,
I think we'd both prefer to review how to improve the current document from the
results of a real review, rather than issues cherrypicked for the sake of a
(somewhat) unrelated assertion.

> >     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.

    I entirely agree, and would much rather see .desktop files documented
as part of a general guide on "Best practices for software developers who
seek to interoperate with the several free desktop environments".  I would
hope this would be an expansion of some of the Upstream Development documentation
Morten worked on some years back [4].  Mind you, this would need to be combined
with the many other sources of similar information, and be maintained as a living
document to do any good.  Sphinx might be a good tool :)

    In the presence of such documentation (either actually present, or just
a subset of the current overbroad "packaging" section of the wiki), I would like
to see a reference from the Packaging Guide suggesting one review a checklist
for the software being packaged (licensing, uscan support, .desktop file for GUIs,
sane build system, etc.).  When everything is good, packaging should be very easy.
When many things are less good, the packager is provided with the appropriate hint
that these are upstream issues, and so may be more likely to submit patches
against upstream source, rather than embedding workarounds in the packaging.

> 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.

    My apologies: I hadn't meant to draw attention to specific issues except by
way of example (that rather belongs in some comprehensive review of the
packaging guide that I may never actually get around to doing), but instead to
suggest that we do lose something by moving from the maze of twisty little links
all subtly different on the current wiki to the new few-paged guide: that being
the variety and description of the various different ways things can be done (I
acknowledge that most of what is presently on the wiki is unmaintained, especially
for rarer or older methods, often ranging from useless to entirely incorrect).
To me this is insufficient reason not to retire the wiki in favour of structured
documentation, but I do want to raise the request that such alternate methods
of doing things for unusual packages (or at least means by which to identify
unusual packages), or alternate procedures (like the local vs. contained build
considerations) be at least included in the notional TODO for the structured
documentation as a part of the migration.

> [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
[4] https://wiki.ubuntu.com/UpstreamGuide

-- 
Emmet HIKORY