Working on the Ubuntu Packaging Guide

[Daniel Holbach]

Hello,

sorry for not responding earlier.

On 28.02.2012 19:07, Andrew Starr-Bochicchio wrote:
> 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.

Yes, that'd work too. There's nothing wrong with having some info at the
top of an article saying "Read 1) and 2) first please, if you haven't
already."

If the structure of the old UDD docs doesn't make sense, let's start
filing bugs where we outline where we'd rather see the content.

I don't know if sphinx let's us easily, but maybe we can even reuse some
of the content to generate a general "UDD Overview" article.


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

This makes sense, although I'm a bit unsure if we shouldn't make the
policy bits part of the hands-on docs already. If we want to link to
some policy wiki page which explains the reasoning, we can still do that.

What do you think?

Have a great day,
 Daniel

-- 
Get involved in Ubuntu development! developer.ubuntu.com/packaging
And follow @ubuntudev on identi.ca/twitter.com/facebook.com/gplus.to