
WebMacro Development Policy
===========================

WebMacro developers must follow this policy when working on the WebMacro
project. It specifies how you get approval to make a change, coding
conventions you must follow when making that change, and what you must
do to tell everyone else about your change.

I've tried not to specify very much here, leaving a lot to your 
common sense--but do please try and follow what is specified.

Read the policy carefully before committing any changes. The short
story is:

  -- Anyone can become a developer, just ask!

  -- You need to build consensus before making a change

  -- You must record your change in the CHANGES file, as well
     as properly comment and document it. 

  -- You must follow the coding standards set out here

  -- You can escape this policy by submitting to /contrib 

By submitting code to the WebMacro source repository you agree to be
bound by this policy statement.


BECOMING A DEVELOPER
--------------------

Send email to justin@webmacro.org asking to become a WebMacro 
developer. Describe what you would like to work on. A good way 
to introduce yourself is to post some useful bug fixes or 
extensions to the mailing list, and then ask for access so that
you can commit your work once your change is approved :-)


CREDIT FOR YOUR WORK
--------------------

Each major package should have a CONTRIBUTORS file. When you make a 
change add yourself to the CONTRIBUTORS file and include a note 
mentioning what you have done. You will receive credit for your 
work in the release and on the website. 

Please note that you must make a contributor grant giving us the 
right to redistribute your change under all of the licenses which
WebMacro is available under (currently the GPL and an Apache style
license). We must also be able to relicense under different license
terms in the future, as the need arises. 


GAINING APPROVAL FOR YOUR CHANGE
--------------------------------

You must not make any change to the WebMacro source tree until 
you have approval from the mailing list. What kind of approval you
need depends on what kind of change you want to make:

   Bug Fixes: 
      Report the bug to the list. If there is consensus that
      it is a real bug then go ahead and fix it. You don't need
      a vote of any kind  to fix a bug.

   Feature Changes:
      Propose your new feature on the list. You need +1 from three
      people in order to make your change, and no -1. If someone 
      votes -1 you must wait for consensus before changing the code.

   Contributions:
      You can add new packages to /contrib and upload things there
      without gaining approval from the list. Things in /contrib are
      understood to be external "add-ons" to WebMacro, and since they
      are not part of the core, this policy does nto apply.

You should allow at least a couple of business days between posting
your intent to make a change and actually committing your change. If
something proves unpopular but you want to commit it anyway you can 
move it to /contrib while you build consensus--making it available
to everyone, so they can see its value.


BEFORE YOU COMMIT
-----------------

Once you have approval for your change, and you have code that you 
would like to commit, here is what you must do:

   1. Working & Tested: 
       Never commit until your change is working and you've tested it.

   2. You must adequately document the new functionality:
       Always update the JavaDoc API to reflect your change. Remember
       that users have no other way to learn about the behavior of the 
       class. Write assuming users have no knowledge of the code.

   3. You must report your change in two ways:
       a. Write a good description of your change in the CVS 
          commit log, so that other developers can review your work.
       b. Put a note at the top of org/webmacro/CHANGES with a good 
          enough explanation that I can write up a decent README
          when I do the next release

Please report and document your changes properly: otherwise features
will creep into WebMacro that nobody knows about!



CODING CONVENTIONS
------------------

Just some simple rules to keep us all sane:

   1. DO NOT USE TABS. They mess up the indenting since they are
      a different width on my computer than on yours.

   2. Follow the indentation of the code you are editing.

   3. Variable names must be nouns or noun phrases. Class and
      instance variables must be preceeded by a _. For example,
      _orderNumber is an instance variable. 

   4. All public methods and classes must have good JavaDoc 
      documentation, including return types, parameters, and
      exceptions that may be thrown. WebMacro users do not 
      want to read the code. 

   5. Do not comment out code. Delete it. I can use "cvs diff" 
      to compare the current code with the previous version.

   6. Put a comment with your name in it next to any change you
      make, this makes it easier to review and edit changes. 
      These comments will be removed following code reviews.



COMMON MISTAKES TO AVOID
------------------------

Here is a checklist of things to consider before making a change:

  1. WebMacro is a highly concurrent application. Spend a lot of 
     time thinking about concurrency issues before making a change:
     how many threads will be accessing your code? 

  2. Some sections of WebMacro are performance critical. Be careful
     about creating too many temporary objects in these sections.

  3. WebMacro is a framework. As such it requires a clean and 
     simple design. Be wary of quick hacks that fix your current
     problem but reduce the cleanliness of the framework.

In general: TEST YOUR CODE BEFORE YOU COMMIT.


LICENSING
---------

The following conditions ensure that WebMacro will remain available
to everyone who currently uses it, as an opensource software project.
Contributions to the WebMacro CVS archive (other than /contrib) are
covered by the following terms:

   You grant Semiotek Inc. a non-exclusive, perpetual, fully paid-up,
   worldwide right to use, distribute, modify, display, perform, and
   sublicense any software or other materials which you contribute to
   the WebMacro CVS archive, either on its own or as a part of a larger
   work. Semiotek Inc. promises to relicense the software to the public
   under an opensource license listed at www.opensource.org. These 
   terms do not apply to contributions uploaded in the "/contrib" 
   area of the CVS archive.

Currently WebMacro is relicensed to the public under two opensource
software licenses:

   1. The GNU General Public License (GPL), version 2
   2. The Semiotek Public License (see the attached LICENSE file)

From time to time Semiotek Inc. may grant change the terms of the 
Semiotek Public License, or permit uses of the software not covered
by the above licenses. WebMacro will always be available for use 
under the terms of the GNU General Public License, version 2.

