Document Update Instructions have been revised
sunfish62 at yahoo.com
Sun Jan 22 03:36:46 EST 2017
> On Jan 22, 2017, at 12:28 PM, Chris Good <chris.good at ozemail.com.au> wrote:
> From: David T. [mailto:sunfish62 at yahoo.com <mailto:sunfish62 at yahoo.com>]
> Sent: Sunday, 22 January 2017 5:30 AM
> To: Chris Good <chris.good at ozemail.com.au <mailto:chris.good at ozemail.com.au>>
> Cc: Geert Janssens <geert.gnucash at kobaltwit.be <mailto:geert.gnucash at kobaltwit.be>>; GnuCash Developers <gnucash-devel at gnucash.org <mailto:gnucash-devel at gnucash.org>>
> Subject: Re: Document Update Instructions have been revised
> It seems to me that this instruction set is meant for new contributors to the documentation. Personally, I think such a set of instructions should focus primarily on ONE method for contributing, with passing mention of other possibilities. As I understand it, the git way is the currently-preferred method for offering contributions, and IMHO, this wiki page should focus primarily on that. Passing mention of other methods can be included for those who already have the understanding of the technologies. Thus, the discussions about formatting a patch and attaching it to the bug could be mentioned in passing, while the git pull request method could be brought forward and promoted.
> In the same spirit of giving simpler advice to new contributors, I would prefer that the git process described here refer to the other Git page (wiki.gnucash.org/wiki/Git <http://wiki.gnucash.org/wiki/Git>), which I think should be cleaned up by someone who knows more about git than I do.
> FWIW, I think the other Git page should focus on one preferred git modality, said modality being the one where contributors fork the main GC repository on github.com <http://github.com/>, push their changes to that fork, and then issue pull requests to the main repo. Again, other options could be mentioned in passing, but the focus should be on the GnuCash Preferred Method.
> As for the whole “testing the help on Linux” section, as a Mac user, I have NEVER attempted any of this, and if it is an important part of the documentation creation process, then I haven’t done it correctly ever. Since I have been successfully adding to the documentation for a while now, I can assume that this section is, in fact, superfluous to the actual documentation update process. I would propose moving it into some other area of the wiki, perhaps with an advanced Linux developer’s page, where true geeks (I say this with admiration) can plumb the depths of providing this added Linux functionality.
> Hi David,
> You seem to be a little confused between git and github. Both the patch and pull request methods use git on your PC.
> Both the patch and pull request methods get the local repo from github. Only the pull request method uses github for the submitting of the modification request. A github pull request is the method the developers currently prefer for offering contributions.
As I stated at the beginning of this thread, I am not an expert when it comes to using Git. John, Geert, and others on the list can verify my ability to take even the most basic aspect of Git and screw it up. That is also why I suggest focusing on one GnuCash Preferred Method; I am proof positive that you can’t make it simple enough.
> Yes, the Documentation Update Instructions are aimed at new contributors. For non-technical people, submitting a patch is the easiest way, so that is historically the primary focus of this page. I think this is so as not to confuse them by making them jump to another page.
As the epitome of a non-technical person, I am not sure I agree with your assesment of patches being easier. My experience of the patch process was painful and ugly, and I do not believe I ever got a “patch” submitted without major handholding from others on the list. In contrast, I have been able in recent months to actually edit the documentation (in some substantial ways, on occasion), submit the changes, and get them integrated into the distributed document set numerous times. In my experience, pull requests are easier...
> Maybe others will disagree but I don’t think changing the primary focus of this page from patches to pull requests is really the best use of your time. :-)
> It seems people are skipping the reference to http://wiki.gnucash.org/wiki/Git_For_Newbies <http://wiki.gnucash.org/wiki/Git_For_Newbies> from http://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Step_2_Git_Clone <http://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Step_2_Git_Clone>. Do you think it should be made clearer that this discusses Patches and Pull Request procedures as well as basic git commands?
I personally believe that the process of getting set up with Git (whether for documentation or for code) should be handled in a single separate page, so that THIS page can focus on the process of updating documentation. Explaining how to set up git in three different places is the way of madness.
> I did in the past try to improve wiki.gnucash.org/wiki/Git <http://wiki.gnucash.org/wiki/Git> but this was deemed to be a backward step for git experts, and thus I put my changes into new page Git_For_Newbies instead.
I will return to the question of who these pages are meant to serve. You and I agree that the focus should be on getting a raw recruit up and contributing to the project in a meaningful way; to that end, the git content here should be directed that way. Git experts will have their own resources for applying their knowledge in the GC realm, ISTM.
> Re: “testing the help on Linux”:
> This is only really necessary if testing context sensitive help. (I.e. invoking a particular help section using the F1 key from within GnuCash) where that invocation is only in new code, so cannot be tested from an already existing GnuCash installation. Geert has recently made that clearer. I think this page is an appropriate place for this info.
My point is this: testing whether the context help works in Linux is, technically speaking, not a function of editing the documentation, and doesn’t belong on this page. I don’t have a Linux box, and I don’t plan on getting one or setting one up just so I can test this aspect of the software. I don’t think that disallows me from editing the documentation, and since it is not an actual requirement for updating the documentation, then it should be moved elsewhere.
> Regards, Chris Good
More information about the gnucash-devel