Working on the Ubuntu Packaging Guide

[Andrew Starr-Bochicchio]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

I was recently talking with Daniel about working on the Packaging
Guide, and thought that maybe other folks might have something to add.

On Tue, Feb 28, 2012 at 4:02 AM, Daniel Holbach
<daniel.holbach at ubuntu.com> wrote:
>On 28.02.2012 06:05, Andrew Starr-Bochicchio wrote:
>> I've been wanting to contribute to the packaging guide a little more
>> deeply, but before trying to make bigger changes I feel that there's a
>> to need spec changes out a bit before digging in to the work. I'm
>> trying to think about the structure as well. Sometimes its unclear if
>> things should be in a new article or worked into existing ones. Too
>> many articles spreads out information and makes it harder to find, but
>> expanding things that work well as simple how-to's makes things seem
>> needlessly complex.
>>
>> For instance, we've got two bugs open requesting a more in-depth
>> coverage of merging (LP: #793899, LP:#827925). Of course, we already
>> have "Merging - Updating from Debian and Upstream." One approach is
>> updating/porting https://wiki.ubuntu.com/UbuntuDevelopment/Merging to
>> the new docs, but maybe the existing article should be expanded.
>> Should merge from Debian and updating from upstream be broken out into
>> two articles? How much of our structure have we simply inherited from
>> the old UDD docs unintentionally?
>
> That's a good question. I agree that the original strategy of having
> specific articles for specific tasks (and the contributor thinking "hey,
> that's exactly what I want: merging from Debian") and a number of
> knowledge-base articles about specific bits like tools, infrastructure
> or processes is getting harder and harder to maintain, but I'd actually
> prefer us doing something along those lines.
>
> Maybe it would make sense to bring the topic up on the ubuntu-devel
> mailing list, so we can discuss it there and get more people to speak up?

I think the basic original strategy still makes sense, but I think we
are currently failing at it. Take your example of the contributor
thinking "hey, that's exactly what I want: merging from Debian."
Logically they'll end up on the "Merging - Updating from Debian and
Upstream" article. [1] Because of the way we've inherited from the old
UDD docs, that page will not be very useful on its own. It dives right
into "bzr merge debianlp:squeeze/tomboy" and ends with "bzr builddeb
-S --package-merge" There's obviously some stuff you're expected to
have read before hand and more stuff you'll need to read to actually
submit your work. At the least, I guess these articles should have a
prerequisites and next steps sections.

>> This also begs the question of how much this guide should be about
>> documenting Ubuntu development processes vs. techniques. Should we
>> start migrating things like https://wiki.ubuntu.com/SponsorshipProcess
>> and https://wiki.ubuntu.com/StableReleaseUpdates
>
> The more old Wiki docs we can get rid of the better.

Maybe we need three major sections: the hands on articles, the
knowledge base stuff, and something closer to policy/process?
Incorporating these sorts of pages brings up the problem of where is
their canonical location? In the past, they have been distinct from
the "Packaging Guide." I think we'd need some broader consensus before
migrating them.

Sorry if this is a little disjointed. I guess I'm mostly hoping to
spark some discussion, and clarify my thinking on how to move forward
with the guide.

[1] http://developer.ubuntu.com/packaging/html/udd-merging.html

Thanks!

- -- Andrew Starr-Bochicchio

   Ubuntu Developer <https://launchpad.net/~andrewsomething>
   Debian Maintainer
<http://qa.debian.org/developer.php?login=a.starr.b%40gmail.com>
   PGP/GPG Key ID: D53FDCB1

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)

iQIcBAEBCAAGBQJPTRcSAAoJEDtW4rvVP9yxhwQP/iRm9YJEeMftgnw5lbanS3ur
uk3WtPjt60bB1TF4c1InBV4dIPegE1WjH8hGvmZfta47Z88Y7x2Hz6vRJIRFI7pQ
TOda4apJ0vnTc6efBzjM9LeV0IeTmnDKFoSkDjkLNnTfMZrTsP7Ku3I88K5LR7dX
9WJ4gP8hZS02dYCHCNHE/ZYjHHzHTrDo7rjLebyLag2vOCgXXMBfLULiCeVec38g
24kPR+7KjLXuJNZl+BZUiqhet8Ap6yZ1X7eALghgvRgQjivBgQj6L11QKgDSTml4
nLHGKconIKYYT/Df/vkHkV26sRxF/cJoupGqq7+CICELKM5NnKbqfsCfATAreVow
+ykylJPUtKzwFL3eSzeSm++D6wh0RJdlmnovadikXNmCQTEwldSQxSVzber/wYJx
67HV/hVRnh6YHYzkWb6QMSTTMzAXfEsPtflHK3my/BsFJRgugXzwK+25UBnql79L
pz9yAs2qm3H6qZD4mcxuBnUvk4DtvtXFwU9XTkMiALzXsvjwAdGvn/BnOXj8N4Kv
JS6LuN4qRyf0ztfQddfn3tbyOkv3+mv1dhmgyp0kyYyNeI9Ip/ChYTQxQ6T6vYAW
8wqgzjn1SBInSJomdRvPwbMF/H7lZHWAMpTSOe+amGGk3cXQoLu2jhww1w9ZGWjo
9imwpJw58PerLyPMqcLA
=q3yT
-----END PGP SIGNATURE-----