See below… > On Jan 22, 2017, at 12:28 PM, Chris Good <chris.g...@ozemail.com.au> wrote: > > From: David T. [mailto:sunfis...@yahoo.com <mailto:sunfis...@yahoo.com>] > Sent: Sunday, 22 January 2017 5:30 AM > To: Chris Good <chris.g...@ozemail.com.au <mailto:chris.g...@ozemail.com.au>> > Cc: Geert Janssens <geert.gnuc...@kobaltwit.be > <mailto:geert.gnuc...@kobaltwit.be>>; GnuCash Developers > <gnucash-devel@gnucash.org <mailto:gnucash-devel@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. > > David > > 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 _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
