Hi! > > On Thu, 2007-12-13 at 15:21 +0100, Florian Festi wrote: >> Hi! >> >> > I am a newbie to yum-development. I have written complete documentation >> > for the fastestmirror Yum plugin. I am not sure how to commit it to the >> > original code of the fastestmirror. Please help me to commit the code. >> >> You should work on the current development version. See >> http://linux.duke.edu/projects/yum/scm.ptml how to get them. >> >> We use git as source management system. So you'll have to learn git to some >> extend. > > no he doesn't. He can just download the tree and submit patches via > email. Learning git is a barrier to participation and should not be > considered a requirement to helping out with yum.
Well, I tried git, but I wasn't able to checkout the Yum source code. https://lists.dulug.duke.edu/pipermail/yum-devel/2007-November/004614.html . So, I just downloaded the plugin and made the changes. I would love the know git, if the I can get rid of the above error. >> Such patches are the only legitimate format for sending code to the mailing >> list as it is the only way that it is clear which version was changed, avoid >> encoding problem, add a proper commit message and be easy to import into the >> upstream git repository again. > > No, they're not. You can generate patches using plain diff. Don't put > barriers up like this and please don't act like you're speaking for > everyone. > > > >> OK, now to your changes: >> >> For my personal taste they are a bit too verbose. Doc strings should give >> the reader a short summary of the things he really needs to know. Avoid >> stating the obvious - like that there are no parameters. On the other hand I >> like that you state that the function uses global variables - a cause for a >> lot of fun if missed. But as most function do so you can consider stating >> this at the module level. Same applies to the description of the global >> variables. > > Stating the obvious is what documentation is about. Being clever in docs > just means someone else is confused. Now, I am a bit confused. Please guide me what to follow ? Because if two developers will ask me to do the two opposite things, I will not to able to excel. >> As a general hint I'd ask you to shorten your language a bit. The shorter >> you can express what you want to/need to say the faster can developers read >> and understand what this piece of code is about. No one is looking for a >> pleasant reading experience but for a short info that's easy to read and to >> keep up to date. There is no need for using whole English sentences. Terms >> like "This function" are simply superfluous - "It uses global variables to >> communicate with other functions." can be shorten to "uses global >> variables". > > Except it's a crappy sentence and doesn't explain WHY the globals are > there, which is a better sentence. Verbosity in documentation, provided > it's not like the god-awful dissertations in the git documentation, is a > plus. Clarity is an even bigger plus. > > -sv > > > _______________________________________________ > Yum-devel mailing list > [email protected] > https://lists.dulug.duke.edu/mailman/listinfo/yum-devel > > ------------------------------------------------------- Thank you, Kulbir Saini, Computer Science and Engineering, International Institute of Information Technology, Hyderbad, India - 500032. My Home-Page: http://saini.co.in/ My Institute: http://www.iiit.ac.in/ My Linux-Blog: http://linux.saini.co.in/ My Web-Blog: http://life.saini.co.in/ IRC nick : generalBordeaux Channels : #fedora, #fedora-devel, #yum on freenode ------------------------------------------------------- _______________________________________________ Yum-devel mailing list [email protected] https://lists.dulug.duke.edu/mailman/listinfo/yum-devel
