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
_______________________________________________
Yum-devel mailing list
[email protected]
https://lists.dulug.duke.edu/mailman/listinfo/yum-devel
