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. > 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. > 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
