Making the most of our Contribution Policies

Hello people.

It seems that sometimes there are a few aspects of JME being worked on the repository, which makes a few classes not recommended for public adoption yet.

Also, I think we could benefit from a couple of policies for contributions like:

  1. Obligation Strong recommendation of reviewing/adding Javadoc for every modified/added class. Including all methods and fields. If a method or field is inherited, it’s fine to reference the parent method. If the code is complex, it should be explained internally too (not only what it does, but how it does it).

  2. A few suggestions we could add:

    3.1) If possible. Signal if the class is designed for inheritance, if it is known to be thread-safe or no thread-safe… and if it is stable (i.e. it is not known to need modifications). A simple paragraph for the class Javadoc will do it: "<p>This class has not been designed as thread-safe. Changes are expected to the constants, as they should be replaced for Enums.</p>"

    3.2) Shall any implementation be fautly, add //TODO: or //FIXME: notes accordingly.

    3.3) Reference examples, tests and related classes using @see Javadoc annotations and proper hyper-linked documentation.

    My suggestion is that we start being very picky with undopcumented classes and commits. It may take only 10 minutes the first time, and the benefit will be huge. We shouldn't be afraid of adding as much documentation as possible to every class, cross-referencing related systems and going down to the basics as much as possible. Even including examples and/or references to the appropriate tests. We shouldn't accept commits without the corresponding Javadoc and internal documentation. We should validate all documentation for each commit.

    I can imagine this will not always be possible to do, but in the end patches will follow the same process they follow now to be approved, with us just being more demanding about documentation.

    I think there is a great benefit in being a bit more strict about this… and it's also considered a best practice.



On a (somewhat) related note: I think that we should have a preferred policy for deprecating API, e.g. the old integer constants that have been replaced by enums.

I'd like to suggest that we mark in the deprecation comment when a feature will be removed, something like:

@deprecated this method will be removed on or shortly after 2009-06-15, please use {@link #fooBar(String)} instead.

where the date should be in the not too distant future (say 3-6 months, depending on the feature in question).

Obviously this will vary depending on the release (e.g. once we have a FINAL for a specific version we probably shouldn't remove stuff until the next major version number bump, but I'm talking about trunk development here).

Thats good. Makes it easy to tell that its been deprecated long enough and can come out.