[Yum-devel] fastestmirror plugin documentaion patch

[Florian Festi]

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.

You should create your private branch ("git branch mybranch; git checkout 
mybranch"). Then you can change files and create commits with "git commit 
-a". You can export your last n commits with "git format-patch -n" or just 
use qgit.

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.

Before sending patches you should do "git pull" and "git rebase master 
mybranch" to make sure your changes apply to the current version. You can 
use gitk or qgit to have a look at the state of you repository.

I just gave a talk about git which can be found on 
http://ffesti.fedorapeople.org/. You'll need to read some of the git man 
pages. Feel free to ask on IRC or the ML.

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.

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



I am not sure if it makes sense to add epydoc doc strings to the whole 
project. They use up a lot of screen space and are only useful when using 
the right tools. So the right way would would be asking the maintainer of 
the file you are commenting if they are wanted. May be someone of the 
yum-utils maintainers can comment on this...


OK, this is a bit much at once and got a bit more preaching than I intended. 
I hope my criticism did not discourage you - keep it up!

Florian