Documentation patching process

Thomas Bullock tbullock at
Wed Jul 28 07:50:43 EDT 2010


Thanks for your thoughtful and researched reply.

Of the 3 options (bugzilla, html, patches-mail-list) you suggest, I have no experience with any.  So my reaction favors the bugzilla approach, since it seems to provide the most flexibility for reporting, tracking, and obtaining interested party comments.  Using that venue also provides the possibility of specifying a date for comments to be received by prior to developers having to decide to accept, defer, or reject.  If I visualize it properly it should offer a reliable, public way to find quickly and easily all pending patches for GC.

It also provides the possibility that those on the user list who don't subscribe to the developers' list could also participate in the review.  The eyes of newbies have a different perception than that of experienced users.

P.S.: Whatever you decide to do I think an explicit procedure should
go in the wiki and/or the source files so we can point people to it.

This idea has come up before and I want to affirm that as I go thru this step-by-step process, whatever ideas I get that clarify the process for me I plan to include in my description of how-to create a patch.  Basically, since I have never done this and am learning linux, xml, and other things as I proceed, it is taking me longer than someone who knows all this already.  For that reason my write-up will have both a verbose and a succinct statement; the first for a newcomer like me, the later for experienced persons who have already learned how to create a patch and need only a check list as a memory aid.

When that is ready, I will need someone to put it on the appropriate wiki, since I don't know anything about creating or modifying same.  If you want to volunteer, I will be glad for your participation, but no pressure from me if you cannot.

Thanks again.


-----Original Message-----
From: Tommy Trussell [mailto:tommy.trussell at] 
Sent: Tuesday, July 27, 2010 7:40 PM
To: Thomas Bullock
Cc: gnucash-devel (gnucash-devel at
Subject: Re: Confirming that no one else is working on Guide Documentation, Chapter 3

On Mon, Jul 26, 2010 at 11:27 AM, Thomas Bullock <tbullock at> wrote:
> Thanks for your offer to review drafts of documentation changes. What is the customary way of
> Handling that?  I would not want to send a draft to the devel list, lest it be confused as a patch.
> Or should that concern be handled by bold identification that the attached is a draft and not
> A final proposed patch?

As far as customary goes, I am getting the idea that your predecessors
have experimented and improvised as they went along. I'm going to
suggest two options and you can pick and choose or suggest another
option. In a nutshell, I think you can

1) Create a patch and file it in bugzilla
2) Publish an html version people can review

I just looked at and of
the things it says I think the most careful way would be to create a
patch file (using diff) and file it as a documentation bug in (Alternatively you could post the entire updated
file but a patch would make it clearer exactly where your changes

For example, once you revise a section then you could create a patch
against trunk in svn and post the patch as a documentation bug against
gnucash in (identifying the particular patch as a
draft you want people to review).

If I want to review your patch I could copy the documentation trunk to
my local machine and download and apply the patch to the local files
and have a look. I can then make my comments to the bug in bugzilla.

I think there are some advantages to this procedure. There haven't
apparently been many documentation patches in bugzilla, but I found a
couple examples so you can see. For example Note that you can
view the patch as a diff and see the exact changes in context. To me
that might make it worth the effort of creating the patch and the bug

(The HACKING doc also suggests posting patches to the gnucash-patches
mailing list. I haven't subscribed to that list, however, and it seems
like bugzilla might have some advantages.)

Since you can alternatively output HTML as described in you
could post the draft to a public site (a free one such as google sites
or google docs would probably do) and invite comments by posting a
notice on the developer's list and include the url there and in the
bug report. I think the reviewers can most efficiently make their
comments in bugzilla.

P.S.: Whatever you decide to do I think an explicit procedure should
go in the wiki and/or the source files so we can point people to it.

More information about the gnucash-devel mailing list