Harmony Developer Agreements and Recommendations

The summary of agreements and recommendations that were discussed on the development mailing list dev@harmony.apache.org. Please feel free to send your comments and questions there.

Development

serialVersionUID MUST be explicitly specified for each Serializable class to provide compatibility.
[classlib] serialVersionUIDs for Serializable classes
Exception messages MUST be internationalized.
Internationalized messages
A golden ticket MUST be acquired to update the java.lang.String class.
[classlib] String is special
Mark deprecated stuff with @deprecated keyword.
deprecated methods, javadocs
Error messages should contain helpful information.
More helpful error messages
We clarify/add Harmony classlib-specific details to javadoc and provide examples. Also javadoc should contain a reference to Sun's javadoc.
Writing JavaDoc
Implementation code should not contain logging.
[classlib] JNDI provider's dependency on logging and [classlib] logging from within our implementation
The java.util.concurrent issue was resolved by taking code from independent source (Doug Lea). And we'll offer fixes made in Harmony back to original repository.
[classlib] proposal - resolution to java.util.concurrent issue, [classlib][concurrent] java.util.concurrent module proposal and [legal] taking concurrency utils code into the project
Ant build files should use 1.6 style (using macros and avoiding antcall invocations).
[classlib] build file stuff
It is OK to use Sun's messages for expections and toString() methods.
[general] Sun's permission to use exception messages and toString() formats
We use Apache Yoko as CORBA for Harmony.
[classlib] Using Yoko as CORBA for Harmony
And CORBA v.2.4 is acceptable (1.5 spec requires CORBA v.2.3.1).
Yoko is CORBA 2.4. Is this acceptable for Harmony?
We will support 3.2 and 4.01 versions of HTML (RI is based on 3.2).
[classlib][html] HTML 3.2 or 4.01
sun.* classes issue was resolved by creating suncompat.jar.
[classlib][suncompat] created
Throws clause of stub method should include NotImplementedException to be recognized by Japi tool.
Japi diffs for harmony

Testing

Follow guidelines for unit tests.
[Testing Convention] Keep tests small and fast
There is no separate regression test suite. Regression tests are added to unit tests with comments pointing out to JIRA bug.
regression test suite and Regression tests
Create separate test suites for exotic configurations.
[testing] code for exotic configurations
No logging for unit tests.
[classlib] Unit and performance testing
All resource files are located in <module root>/src/test/resources folder and added to classpath.
Location of test data files
Network tests should use embedded jetty server.
[classlib] jetty based tests

Others

Separate module for providers should be created.
componentization: more modules might be necessary
JIRA issue can be reassigned if it is not marked as 'In Progress'.
Stealing JIRA issues
New files should be created with svn property eol-style=native.
EOL differences in svn diffs
Mail threads should have subject with prefix.
[admin] prefixes?
Create component status pages and keep them up to date.
Component status pages
Commit log message should contain full JIRA issue name (for example, HARMONY-2150)
[general] log messages