Code Contribution
=================

Inside the CipUX project we distinguish between several code areas where you can contribute.

  * add-on: Write a new or improve an existing application in any language, for example in PHP.
  * CipUX Administration Tool (CAT): Add a new CAT module or improve an existing on. This area is small an rather easy. Just Perl knowledge is sufficient.
  * CipUX Core Coding: The Database abstraction layers and other parts are written in Perl. Therefore you need solid Perl knowledge. Because the main target is LDAP for the moment you should have or be willingly to learn LDAP related topics too. But is also possible to specialize in some field like configuration or logging, if you do not like to deal with LDAP in the first place. For an introduction to the CipUX Core Coding see this presentation. 

Code contributors should:
-------------------------

  * work some time over the cipux-devel list with others together and send new code or patches to the list. When we see that technical and  social skills are sufficient - if we think your code match a certain style and quality, you can apply commit access on the cipx-devel list or we ask you to apply for it.
  * look at to do list and announce on the list that you will take over a point

   http://svnweb.cipux.org/index.cgi/CipUX/view/trunk/TODO

Specifications
--------------

The following ranges and rules for contributions have to be considered:

  * CipUX should run with Perl >= 5.008001 on Debian Etch

  * CipUX should run with Perl 5.10     on Debian Lenny

  * We use CPAN modules where possible. We will not write code that do the same as a available CPAN module. We will not use modules which are impossible to use on Debian Etch or which burden to much packaging effords to it. If yo are unsure, ask before.

  * We develop in CPAN  style modules: This mean, if you write code make sure it is a valid CPAN Module.

  * We use Module::Build and Module::Build::CipUX for Module handling, installation.

  * We use the following general tests:

        pod.t
        00.load.t

  * We use this tests as AUTHOR tests:
  
        pod-coverage.t
        perlcritic.t
        perlcritic_cpan.t


  * We use the cipux-devel list and the IRC for coordination 

  * We use the SVN repository on Alioth as workspace

  * We will use Git after release of 3.4.0

Style guide
-----------

  * We follow [Perl Best Practices](http://oreilly.com/catalog/9780596001735/#top) from Damian Conway as mandatory style guide.
   
  * We will enforce this style in the future.

  * We use perltidy. 

    Add .perltidy to your home directory:
 
        -l=78
        -i=4
        -ci=4
        -st
        -w
        -syn 
        -ce 
        -csc
        -vt=2
        -cti=0
        -pt=1
        -bt=1
        -sbt=1
        -bbt=1
        -nsfs
        -nolq
        -wbb="% + - * / x != == >= <= =~ !~ < > | & >= < = **= += *= &= <<= &&= -= /= |= >>= ||= .= %= ^= x="}}}  

    If you use vim you could add this to your .vimrc
 
        map ,pt <Esc>:%!perltidy <CR>

    and type `,pt` in vim to reformat your code.

    To use perltidy with Eclipse IDE see following [[CipUX/Development/Eclipse|HowTo]]

  * We use redundant -w parameter

  * We use -T parameter wherever possible

  * we use always the following pragmas:
 
        use strict;
        use warnings;
        use 5.008001;
 

  * we use where appropriate:

        use Class::Std;
        use Data::Dumper;
        use English qw( -no_match_vars);
        use Log::Log4perl;
        use Pod::Usage;
        use Readonly;
 
  * we use inside class:

        use version; our $VERSION = qv('3.4.0');
        use re 'taint';    # Keep data captured by parens tainted
        delete @ENV{qw(PATH IFS CDPATH ENV BASH_ENV)}; # Make %ENV safe


  * We avoid `''` or `""` for an empty string

    Instead we use:
 
        my $EMPTY_STRING = q{};

  * we use hash based named parameters for subroutines

        my ( $self, $arg_r ) = @_;
        my $name = exists $arg_r->{name} 
                 ? $self->l( $arg_r->{name} )
                 : $self->perr('name');
 


  * we use a _ for private subroutines

    If you have a subroutine, which should not be exported by the module, it should start with an underscore:

        sub _my_private_routine {
        ... 
        }
 

  * we should use Carp (croak or confess) and not die.

    In standard scripts

        use Carp;
        croak("value [$value] to big") if $value > 100;