ImprovePackagingGuide

Summary

The Packaging Guide is the first stop for many future Ubuntu Developers. It was never meant to replace the Debian policy or the Debian New Maintainers' Guide, but instead give new developers a good idea what packaging is about and expose them to the basics of packaging and the packaging tools in a practical way.

The current Packaging Guide leaves a lot to be desired. It needs an update, it needs to be better at listing one good way to do things, it needs to explain launchpad usage, explain how to collaborate with upstreams, explain common Ubuntu processes. Also would it be good to make it available in web, ebook, etc. format and make it translatable.

We want to transform as many wiki documents as possible into separate packaging articles.

Release Note

We started moving packaging documentation into separate, easy-to-read articles. They are available in HTML form and are packaged for Ubuntu.

Rationale

The wiki has served us well for aggregating packaging-related content, but it's very hard to translate, to file bugs on it and to ship it in other forms. A separate problem is that the "complete guide" is not particularly easy to read. A set of dedicated articles and a task-based introduction page will work out much better.

User stories

Paula follows a link to the packaging articles, finds the task she's interested in and reads the article. At the end she finds links to related articles and soon has a very good idea of where to go.

Eve found a bug in one of the packaging articles. She follows the link to "report problem with this article" and fills out the form in Launchpad.

Design

We will set up a Launchpad project in which we will edit the articles via Launchpad's code hosting and merge proposals. The main page will have be task-based, so newcomers find their way easier. We will identify which content from the wiki can easily be reused and separated out into distinct articles.

It will be easy to set up daily builds of it, package it, put the generated HTML on some website, etc. Over time the number of articles will increase and as soon as everybody's familiar with it, we can abandon the old wiki infrastructure.

Implementation

The preparation phase will include the following steps:

  • Research: we need to find out which toolkit serves us best and solves most of our problems. Current contestants are Mallard and Sphinx.
  • Set up Launchpad project.

  • Identify which content of PackagingGuide can be re-used.

  • Set up list of possible topics, currently on the list are
    • Getting set up
    • Discuss simple example package
      • minimum basic package
      • discuss specific files
    • Fixing a bug
    • Guide for upstreams
    • Get the source of a package
    • Patch an existing package
    • Build a source package
    • Upgrade a package to a new version
    • Create a new package
      • write an apport hook
      • set package bug guidelines and acknowledgement
      • subscribing to bug reports
    • Request sponsorship
    • Package with bzr
    • Create a debdiff
    • Collaboration with external projects
    • Merging / Syncing

Once the preparations are finished, we will

When we have a few articles available, we will

  • package it
  • set up an ubuntu.com location where the newest version of the guide can be viewed online

Migration

Leave Packaging Guide wiki around for now, place huge warnings at the top of each page.

Unresolved issues

  • We need to identify which toolkit to use:
    • Mallard
      • CON: does not do .pdf
      • CON: is XML

      • PRO: can be easily viewed in yelp

      • PRO: uses gettext infrastructure for translations
    • Sphinx
      • CON: translations are not straight-forward

        • this will change in sphinx 1.1; we have 1.0 in natty and could easily start without translations and add them later on

      • PRO: easy to write
      • PRO: does .html, .pdf, .info, etc.

BoF agenda and discussion

FORMAT
======

Mallard(?)

Courtesy of Jim Campbell(j1mc):
 
To view the guide in yelp, just do "bzr branch lp:~ubuntu-core-doc/+junk/packaging-guide" and then (from outside of the directory) do "yelp packaging-guide/"



CONTENT
=======

 - maybe rename to "Ubuntu Development Guide"
 - task-driven
 - Articles:
  + Discuss simple example package
   . minimum basic package
    . discuss specific files
  + Getting set up
  + Fixing a bug
  + Packaging something new
  + guide for upstream
  + Get the source of a package
  + Patch an existing package
  + Create a source package
  + Build a source package
  + Create a debdiff
  + Upgrade a package to a new version
  + Create a new package
   * write an apport hook
   * set package bug guidelines and acknowledgement
   * subscribing to bug reports
  + Request sponsorship
  + Package with bzr
  + Collaboration with external projects
  + Merging / Syncing

Add references to:
 - debian policy
 - ubuntu development processes
 - 
 
 
ACTIONS:
 - dholbach/barry to investigate if sphinx somehow supports translations
 - dholbach to investigate if we can have a complete guide in mallard
 - dholbach to investigate if html2pdf solves our mallard problems
 - Sphinx: http://sphinx.pocoo.org/
 - dholbach to set up launchpad project (add dev and doc teams to committers)
 - iain to ask devel list about identifying which of the current packging guide content can be reused for the articles


[stefanlsd] merge in UDD: POSTPONED
[dholbach] Flow chart of steps required: POSTPONED
[stefanlsd] Flow chart of steps required: POSTPONED
[dholbach] schedule meetings: POSTPONED
[dholbach] Hold series of Packaging Doc Days: POSTPONED
[laney] make the landing page tasks-driven (ie: "make a debdiff" → "write a patch / fix a bug"): INPROGRESS
[laney] Pre-req knowledge required for a specific task. Documentation should point them the knowledge: POSTPONED
[laney] emphasise working with upstream (debian): POSTPONED

CategorySpec

Specs/ImprovePackagingGuide (last edited 2010-11-17 15:54:22 by p5DDC2F07)