Playbook One

[Nathan Handler]

On Sat, Apr 25, 2009 at 11:42 AM, Dougie Richardson
<dougierichardson at ubuntu.com> wrote:
>> 2) If this document is meant to be an introduction to someone who
>> wants to learn about working with documentation in Ubuntu, you should
>> at least briefly explain the core-doc team (although this will most
>> likely need to be updated in the near future).
>
> I'm not sure about this because the idea is that this is something
> that a user would download from a page where our structure is
> mentioned. With space at a premium I'd rather leave out details that
> don't affect contributing directly - unless you feel there is a strong
> need for this.

I would not assume that the user had seen/read that wiki page. The
great thing about this pdf is that people can pass it out at LoCo
meetings or stuff it in a drawer until needed. I am willing to bet
that a large number of the users who end up printing this PDF will not
have read/seen the wiki page that it was downloaded from.

>> 3) In the "Patch it..." section, you only demonstrate how to create a
>> bundle. I understand that this is one of the ways that users are
>> recommended to contribute patches. However, from my experience, it is
>> much easier to get a 'bzr diff' sponsored than a bundle. Another
>> method is creating a separate bzr branch and then requesting that it
>> be merged into the main branch. I have had a much easier time getting
>> patches sponsored when I follow one of these two approaches than with
>> the bundle. As another note, users should be encouraged to use the
>> --fixes flag when running bzr commit. This will allow them to clearly
>> show that that commit resolves a certain bug on Launchpad.
>
> I've changed it to bzr diff.

You do not need to change it to bzr diff. I would briefly explain both
the diff and bundle, since both are mentioned at [1].

> Can you expand on the use of the --fixes flag as I haven't used it -
> does it mark the bug as "Fix Commited" in Launchpad? If so then I'd be
> keen not to use it as the person checking and pushing the patch should
> be changing its status otherwise bugs will get missed.

The --fixes flag is explained at [2]. From my understanding, it has
the same effect as the +linkbug page for a bzr branch. It simply links
the branch to the bug report. This is also an easy way to track what
bugs we fix during a certain release (which would make it easier to
prepare the changelog entry). Last time I checked, I do not believe
that it changed the status to Fix Commited. However, this might have
changed.

Nathan

[1] https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Submitting
[2] http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html#bug-trackers