Tommy, 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. <<snip>> 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. <</snip>> 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. Tom -----Original Message----- From: Tommy Trussell [mailto:[email protected]] Sent: Tuesday, July 27, 2010 7:40 PM To: Thomas Bullock Cc: gnucash-devel ([email protected]) 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 <[email protected]> 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 and/or 2) Publish an html version people can review I just looked at http://svn.gnucash.org/trac/browser/gnucash-docs/trunk/HACKING 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 bugzilla.gnome.org. (Alternatively you could post the entire updated file but a patch would make it clearer exactly where your changes are.) 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 bugzilla.gnome.org (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 https://bugzilla.gnome.org/show_bug.cgi?id=568244 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 report. (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 http://svn.gnucash.org/trac/browser/gnucash-docs/trunk/README 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. _______________________________________________ gnucash-devel mailing list [email protected] https://lists.gnucash.org/mailman/listinfo/gnucash-devel
