Developing OIIO
From OpenImageIO Wiki
Right now, read access to our SVN repositories is open, but write permission is available only to a few people. If you have modifications to OpenImageIO that you wish to submit, please email diffs to the oiio-dev mail list, and somebody will review your code and check into SVN if approved.
More detailed instructions will be here soon.
Contents |
Contributor License Agreement and Intellectual Property
To protect the project -- and the contributors! -- we do require a Contributor License Agreement (CLA) for anybody submitting changes. Trivial changes (such as an alteration to the Makefiles, a one-line bug fix, etc.) may be accepted without a CLA, at the sole discretion of the project leader, but anything complex needs a CLA. This is for your own safety.
After downloading the OIIO source code, look in src/doc/CLA-INDIVIDUAL, print and sign it, and either scan it and email it to us or snail mail us a physical copy (email me for physical address).
If you are contributing to OpenImageIO while "on the job" working for a company, or even on your own time if you work for a company that does not explicitly give you permission to contribute to open source projects on your own time, you also need your employers to send us a corporate CLA, which can be found in src/doc/CLA-CORPORATE.
Our CLA's are identical to those used by the Apache project.
Issue tracking
We have a "trac" issue tracking system for bugs and enhancements: OpenImageIO trac.
You cannot get into the system without a login, but you may log in as "anonymous" (yes, actually type "anonymous" for the login) in order to see the tickets. If you are a developer and wish to add new tickets or edit existing tickets, just email me (lg AT openimageio DOT org) and send me your preferred userid and password, and I'll set it up for you.
Subversion configuration and line endings
We officially use Unix (LF) line endings. You can instruct subversion to check out files so that they look like your native line endings (CF-LF on Windows, LF on Unix-like systems) by putting the following in your subversion configuration file (~/.subversion/config on Linux/OSX):
*.cpp = svn:eol-style=native *.h = svn:eol-style=native *.txt = svn:eol-style=native *.tex = svn:eol-style=native
Coding Standards
We have a Coding Style Guide and expect you to stick to it. Lead developers with commit permissions will do minor edits to make your code conform if it's close, but submissions will be rejected if they are wholesale different from the prevailing style of the project.
Generating Patches and Code Reviews
When you have made modifications to the code, you will need somebody with commit privileges to merge the code for you. Even if you have commit privileges, you must have all code reviewed before merge. To show the rest of us what you've done, generate a diff like this:
svn diff --diff-cmd=diff > mypatch
Viewing Patches
My ~/.subversion/config file contains the line
diff-cmd = xxdiff-subversion
The xxdiff-subversion script is part of the xxdiff.
That way, all my 'svn diff' commands will use xxdiff to show me the diffs graphically. To override, you may try 'svn diff --diff-cmd=blah', where blah==diff will use the old fashioned text diff, handy when generating patches.
So when somebody sends me a patch to review (or if approved, to apply), I check out a fresh trunk (actually, I keep one checked out at all times for just such an occasion), then apply the patch,
patch -p0 < dans-patch svn diff
This is much easier than trying to make sense of the raw patches.
Alternative way to use xxdiff
Instead of putting xxdiff-subversion in ~/.subversion/config and calling svn diff you can call:
patch -p0 < dans-patch xx-svn-diff
Code Review Protocol
We strive for all code changes to be reviewed BEFORE being committed (even if authored by senior developers with commit privileges).
Reviewee -- Email oiio-dev with a descriptive subject like "Review: add cut-and-paste to iv". The text of the email should provide background and explanation of what you've done, and add the patch you generated as an attachment to the email. Do NOT email with a cryptic subject line like "ticket 102". Think about whether the review discussion is likely to be found in a Google search. The text of your email should also point out exactly which platform(s) you used to compile and test your patch.
Reviewer -- Patch a local copy and look over or test the changes (or for very short reviews, you may be able to just read the raw diffs and understand them). Email back with the critique. You can ask for changes, explain problems you found, congratulate them on a clever solution, etc. But until somebody says "LGTM" (looks good to me), or "Ship it" or something that indicates the review is passed, the code should not be committed.
Note that for patches that alter the GUI (i.e., iv code that calls Qt), make significant changes to the cmake scripts, or in other ways do things that have a high chance of behaving differently on each platform, it is prudent to make sure that it has been tested on each of Windows, Linux, and Mac OS X before it is committed.
Sometimes this takes a few rounds of give and take. Please don't take it hard if your first try is not accepted. It happens to all of us.
Branches
See Working with Branches for information on how to create and merge branches.
