Deprecating the wiki-based Packaging Guide

[Emmet Hikory]

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:
> >> 1) Send a last-call anouncement to ubuntu-devel requesting bug reports
> >> about any missing material. Announce steps 2 and 3 will take place
> >> after one month.
> >> 2) Move the entire PackagingGuide wiki namespace en masse to
> >> PackagingGuideDeprecated.
> >> 3) Redirect wiki.ubuntu.com/PackagingGuide to
> >> developer.ubuntu.com/packaging/html/
> >> 4) After six months (one full development cycle)
> >> PackagingGuideDeprecated will be deleted.
> >>
> >> This is the mail referred to in step 1. In one month, I will move the
> >> entire PackagingGuide wiki namespace enmass to
> >> PackagingGuideDeprecated and set up a redirect. If you feel that there
> >> are any critical pieces of information that are missing from the
> >> Sphinx-based Ubuntu Packaging Guide, now is the time to file bugs (and
> >> provide patches). [4]
> >
> > 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
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.  Similarly,
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).  Different folk learn
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.

-- 
Emmet HIKORY