How to contribute to the community

MMBase is originally build by the VPRO, a dutch broadcasting corporation (http://www.vpro.nl), and has been opensourced in april 2000. MMbase is a open-source project under a MPL-style license. A number of developers work for broadcasting corporations in the Netherlands, some work for other large companies, and many others are simply excellent volunteers who are interested in building a better general purpose object oriented content management system.

The community exists mainly through mailing lists and a source repository. To participate:

Go to http://www.mmbase.org and

There are many ways to join the project, either by writing code, or by testing and/or helping to manage the bug database. If you'd like to contribute, then look at:

The bugs/issues/wishes database. http://www.mmbase.org/bugs

To submit code, simply send your patches to developers@lists.mmbase.org after you have read the rest of this file.

To help manage the issues database, read over the issue summaries, looking and testing for issues that are either invalid, or are duplicates of other issues. Both kinds are very common, the first because bugs often get unknowingly fixed as side effects of other changes in the code, and the second because people sometimes file an issue without noticing that it has already been reported. If you are not sure about an issue, post a question to developers@lists.mmbase.org.

Before you can contribute code, you'll need to familiarize yourself with the existing code base and interfaces.

Check out a copy of MMBase (anonymously, so you can look at the code.

Within 'src/org/mmbase/bridge/' are a bunch of interfaces with doc comments. If you read through these, you'll have a pretty good understanding of the concepts of MMBase.

A rough guide to the source tree from the CVS 'all' module:

   documentation/
      User and Developer documentation.
   config/
      Default MMBase configuration files
   html/
      MMBase general web pages like editors and admin interface
   src/
      Source code to MMBase itself (as opposed to external libraries).
   tests/
      Automated test suite.
   applications/
      Stuff that works with MMBase, but that MMBase doesn't depend on.
   applications/bugtracker
      Sources of the bugs/issues database
   applications/cloudcontext
      Sources of the cloudcontext security implementation
   applications/crontab
      Sources of scheduling framework
   applications/dove
      Sources of xml communication interface
   applications/editwizard
      Sources of editors which can be defined by xml
   applications/email
      Sources of email application
   applications/media
      Sources of media framework
   applications/packaging
      Sources of packaging application
   applications/rmmci
      Sources of RMI communication
   applications/taglib
      Sources of taglibrary
   applications/xmlimporter
      Sources of xml import application
  

To understand how things work, read documentation/backenddevelopers/codingstandards We're following the Sun coding standards for Java.

Read http://java.sun.com/docs/codeconv/ for a full description of the Sun coding standards; but here is a short example demonstrating the most important formatting guidelines:

    /**
     * Documentation of method
     *
     * @param arg1 Description of parameter
     * @param arg2 Description of parameter
     * @return expected return values
     */
    private static final int foo(int arg1, int arg2) { /* Use visibility modifier first */
        try {                                          /* Brace on same line, indent 4 */
            if ((some_very_long_condition && arg2 == 1) 
                    || remaining_condition) {          /* Generally use the 8-space rule */
                int v = 10 + someFunction(arg1, arg2); /* Use space around operators */
                return v;
            } else {                                   /* Else on same line as close brace */
                return 1;                              /* Don't use magic numbers like these */
            }                                          /* close brace on own line */
        } catch (Exception e) {                        /* Catch on same line as close brace */
            //documentation of code
        } finally {                                    /* Finally on same line as close brace */
        }
        return 3;
    }
  

In general, be generous with parentheses even when you're sure about the operator precedence, and be willing to add spaces and newlines to avoid "code crunch". Don't worry too much about vertical density; it's more important to make code readable than to fit that extra line on the screen.

We understamd that formatting is a matter of taste and that many developers prefer other formmatting styles, but try to stick to the guidelines. We are using them to keep the code readable. Don't take it personally when someone points you to the coding standards when you submit some code. We will accept your code anyway.

Certain guidelines should be adhered to when writing log messages for code changes:

Make a log message for every change. The value of the log becomes much less if developers cannot rely on its completeness. Even if you've only changed comments, write a log that says "Doc fix." or something.

Start off the log message with one line indicating the general nature of the change. This helps put developers in the right frame of mind for reading the rest of the log message.

Use full sentences, not sentence fragments. Fragments are more often ambiguous, and it takes only a few more seconds to write out what you mean. Fragments like "Doc fix", "New file", or "New mewthod" are acceptable because they are standard idioms, and all further details should appear in the source code.

The log message should name every affected method, variable, etc, including the names of variables that are being removed in this commit. This helps people searching through the logs later. Don't hide names in wildcards, because the globbed portion may be what someone searches for later.

If your change is related to a specific issue in the issue tracker, then include a string like "issue #N" in the log message. For example, if a patch resolves issue 1729, then the log message might be:

Fix issue #1729: Don't crash because of a missing file.

For large changes or change groups, group the log entry into paragraphs separated by blank lines. Each paragraph should be a set of changes that accomplishes a single goal, and each group should start with a sentence or two summarizing the change. Truly independent changes should be made in separate commits, of course.

One should never need the log entries to understand the current code. If you find yourself writing a significant explanation in the log, you should consider carefully whether your text doesn't actually belong in a comment, alongside the code it explains.

There are some common-sense exceptions to the need to name everything that was changed:

In general, there is a tension between making entries easy to find by searching for identifiers, and wasting time or producing unreadable entries by being exhaustive. Use your best judgment --- and be considerate of your fellow developers. (Also, run "cvs log" to see how others have been writing their log entries.)

Log messages for documentation have somewhat looser guidelines. The requirement to name every symbol obviously does not apply, and if the change is just one more increment in a continuous process it's not even necessary to name every file. Just briefly summarize the change, When you finish a distinct stage of work, note it in the log message. Please write your log messages in English, so everybody involved in the project can understand the changes you made.

If you encounter a situation where MMBase is clearly behaving wrongly, or behaving opposite to what the documentation says, then it's okay to file the issue right away (after searching to make sure it isn't already filed, of course!). But if you're

...then please post to the dev list first. You'll get a faster response, and others won't be forced to use the issues database to have the initial real-time conversations.

Nothing is lost this way. If we eventually conclude that it should be in the issue tracker, then we can still file it later, after the description and reproduction recipe have been honed on the dev list.

*Please* be conservative about filing issues. The issues database is physically much more cumbersome than email. It wastes people's time to have conversations in the issues database that should be had in email. (This is not a libel against the issue tracker, it's just a result of the fact that the issues database is for permanent storage and flow annotation, not for real-time conversation.)