NAME
Ado::Manual::Contributing - Making Ado the ERP solution for the enterprise
DESCRIPTION
Ado is a community project. Changes and improvements need to be discussed and well understood by the pumpkin-holder and at least two other members of the core development team before proceeding to implementation. We follow Lean principles of software development.
RULES
This document still evolves but we have to start from somewhere...
The rules outlined in Mojolicious::Guides::Contributing apply for Ado too. For specific to Ado rules see below.
PERL STYLE
The code must look uniformly as if it is written by one person. No matter if you write code for the Ado core or you write a plugin, your code must be passed through perltidy using the ./Build perltidy action in the Ado distribution. Feel free to propose more rules to .perltidyrc. Be ready to explain well your proposal.
IMPOSING PERL BEST PRACTICES
The code must behave uniformly as if it is written by one person. It is mandatory to have the same .perlcriticrc and t/perl-critic.t in your Ado::Plugins as the t/.perlcriticrc found in the Ado distribution. This saves us a lot of headaches beforehand and makes the code easier to understand by more people. Feel free to propose more rules to t/.perlcriticrc. Be ready to explain well your proposal.
DOCUMENTATION
Your code must be covered by documentation. Every subroutine should have small one-line comment before it, stating what it does. More explanations are to be placed in POD for the respective package. The t/pod-coverage.t, t/pod.t and t/pod-spelling.t must always PASS.
TESTS
Your code must at least prove that it behaves as expected. This is achieved by writing tests. By Imposing Perl Best Practices we also decrease the amount and complexity of needed test code. Use ./Build testcover to measure the amount of test coverage for your code. It is up to you how much coverage is enough but coverage under 70% is not acceptable (TODO).
When writing code for the end user it can be also easily automatically tested with tools such as PhantomJS and QUnit. Use exclusively Test::Mojo for REST API tests. Looking at your tests, one should easily conclude how your code should be used.
REST AND CORS
Ado is a system that will provide REST services out of the box. Separation of concerns must be to its maximum. Your REST API must be self describing. Elaborate on the recommendations in "RESTful Service Best Practices" at www.RestApiTutorial.com. You must have a reference implementation of a browser-based user-agent(yourpluginroute.html) residing in Ado/public/. It would be best if your code is CORS-ready this should be easy if your code depends on Ado::Plugin::CORS(TODO). See Ado::Manual::RESTAPI(TODO). Feel free to propose additional best practices. Be ready to explain well your proposal.
TEMPLATES
We have a minimal set of templates residing in the templates directory. Separation of concerns must be to its maximum. Strive for minimal logic in your templates if you have such.
MODEL
Put your database related code under the Model namespace. Use DBIx::Simple::Class. Generate your classes from tables using dsc_dump_schema.pl utility that comes with DBIx::Simple::Class. Feel free to contribute to DBIx::Simple::Class. Minimize SQL complexity. Write ANSI SQL if you need to write SQL. Write your SQL in a way to be compatible with SQLite, MySQL and PostgreSQL. Use the "SQL" in DBIx::Simple::Class feature to achieve this. See "SQL" in DBIx::Simple::Class and its source to figure out how to do it. To guess the current driver:
use DBI::Const::GetInfoType;
#...
my $dbms = $self->dbh->get_info( $GetInfoType{SQL_DBMS_NAME} );
if($dbms eq 'SQLite'){
...
}PLUGINS
Feel free to write Ado::Plugins but first see if there isn't already a Mojolicious::Plugin::* that meets your needs. Try first to contribute to the respective plugin. Feel free to suggest Mojolicious plugins to be added as dependencies to Ado. Be ready to explain well your proposal.
AUTHOR
Красимир Беров (Krasimir Berov)
COPYRIGHT AND LICENSE
Copyright 2013-2014 Красимир Беров (Krasimir Berov).
This program is free software, you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License v3 (LGPL-3.0). You may copy, distribute and modify the software provided that modifications are open source. However, software that includes the license may release under a different license.
See http://opensource.org/licenses/lgpl-3.0.html for more information.