Contributing to Open-ovf
========================

License
-------

The project is licensed under EPL v1.0, so any contribution will be made
under this license. Make sure you read the LICENSE file, in case you have
doubts about the license.


Code/Patches
------------

1) Always run the test suite before sending out patches. Please ensure all
tests still pass and you didn't introduce any new bug.

The scripts available in examples are also good for testing, and should be
used to perform complete tests. Later the test suite will include
complete tests as well.

2) Use pylint to check the coding style and possible errors. Please
do not add code that makes pylint complain. A 10/10 rating is the goal.
Check the Coding style section below to see how to use pylint.

3) Use epydoc syntax to document new classes/methods/functions/etc.
Check http://epydoc.sourceforge.net/ for help.

You can use "epydoc --check <package/file.py>" to verify what is not
documented yet.

4) Patches should be in unified diff format (preferably using git).

5) Make sure your patch applies correctly in the git tree in the day
you're sending the patch out. Use a local personal branch to develop
your feature and keep that in sync with the main tree (check
"git rebase").

6) Patches should be sent to open-ovf-devel@lists.sourceforge.net


Sign your work
------------
  [The following is taken from Documentation/SubmittingPatches 
   in the linux kernel source]

To improve tracking of who did what, especially with patches that can
percolate to their final resting place through several
layers of maintainers, we've introduced a "sign-off" procedure on
patches that are being emailed around.

The sign-off is a simple line at the end of the explanation for the
patch, which certifies that you wrote it or otherwise have the right to
pass it on as a open-source patch.  The rules are pretty simple: if you
can certify the below:

        Developer's Certificate of Origin 1.1

        By making a contribution to this project, I certify that:

        (a) The contribution was created in whole or in part by me and I
            have the right to submit it under the open source license
            indicated in the file; or

        (b) The contribution is based upon previous work that, to the best
            of my knowledge, is covered under an appropriate open source
            license and I have the right under that license to submit that
            work with modifications, whether created in whole or in part
            by me, under the same open source license (unless I am
            permitted to submit under a different license), as indicated
            in the file; or

        (c) The contribution was provided directly to me by some other
            person who certified (a), (b) or (c) and I have not modified
            it.

        (d) I understand and agree that this project and the contribution
            are public and that a record of the contribution (including all
            personal information I submit with it, including my sign-off) is
            maintained indefinitely and may be redistributed consistent with
            this project or the open source license(s) involved.

then you just add a line saying

        Signed-off-by: Random J Developer <random@developer.example.org>

using your real name (sorry, no pseudonyms or anonymous contributions.)

Some people also put extra tags at the end.  They'll just be ignored for
now, but you can do this to mark internal company procedures or just
point out some special detail about the sign-off. 

If you are a subsystem or branch maintainer, sometimes you need to slightly
modify patches you receive in order to merge them, because the code is not
exactly the same in your tree and the submitters'. If you stick strictly to
rule (c), you should ask the submitter to rediff, but this is a totally
counter-productive waste of time and energy. Rule (b) allows you to adjust
the code, but then it is very impolite to change one submitter's code and
make him endorse your bugs. To solve this problem, it is recommended that
you add a line between the last Signed-off-by header and yours, indicating
the nature of your changes. While there is nothing mandatory about this, it
seems like prepending the description with your mail and/or name, all
enclosed in square brackets, is noticeable enough to make it obvious that
you are responsible for last-minute changes. Example :

        Signed-off-by: Random J Developer <random@developer.example.org>
        [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
        Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>

This practise is particularly helpful if you maintain a stable branch and
want at the same time to credit the author, track changes, merge the fix,
and protect the submitter from complaints. Note that under no circumstances
can you change the author's identity (the From header), as it is the one
which appears in the changelog.

Coding style
------------

The coding style used in open-ovf is mostly what is defined on
http://www.python.org/dev/peps/pep-0008/, except for the naming
convention, that follows CapitalizedWords/camelCase.

There is a pylintrc config file (extras/pylintrc), that can be used
to tell pylint to accept CapitalizedWords names.

You can save pylintrc as ~/.pylintrc and that will be used
by default, or you can call pylint like this:

  pylint --rcfile=<path_to_open-ovf>/extras/pylintrc <module/file>


