view release on metacpan or  search on metacpan

lib/Ado/Manual/Contributing.pod  view on Meta::CPAN

of software development.

=head1 RULES

This document still evolves but we have to start from somewhere...

The rules outlined in L<Mojolicious::Guides::Contributing>
apply for L<Ado> too.
For specific to L<Ado> rules see below.

=head2 PERL STYLE

The code must look uniformly as if it is written by one person.
No matter if you write code for the L<Ado> core or you write a plugin,
your code must be passed through perltidy using the C<./Build perltidy>
action in the Ado distribution. Feel free to propose more rules
to C<.perltidyrc>. Be ready to explain well your proposal.

=cut

#TODO: IMPLEMENT Ado::Command::perltidy

=head2 IMPOSING PERL BEST PRACTICES

The code must behave uniformly as if it is written by one person.
It is mandatory to have the same C<.perlcriticrc> and C<t/perl-critic.t>
in your L<Ado::Plugin>s as the C<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 C<t/.perlcriticrc>. Be ready to explain
well your proposal.

=head2 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 C<t/pod-coverage.t>, C<t/pod.t> and C<t/pod-spelling.t> must always PASS.

=head2 TESTS

Your code I<B<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 C<./Build testcover> to measure the amount of test coverage for your
code. It is up to you how much coverage is enough but B<I<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 L<PhantomJS|http://phantomjs.org/> and
L<QUnit|http://qunitjs.com/>. Use exclusively L<Test::Mojo> for REST API tests.
Looking at your tests, one should easily conclude how your code should be used.

=head2 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 L<www.RestApiTutorial.com>.
You must have a reference implementation of a browser-based user-agent(yourpluginroute.html) residing in
C<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 L<Ado::Manual::RESTAPI>(TODO). Feel free to propose additional best
practices. Be ready to explain well your proposal.

=head2 TEMPLATES

We have a minimal set of templates residing in the C<templates> directory.
Separation of concerns must be to its maximum. Strive for minimal logic in
your templates if you have such.

=head2 MODEL

Put your database related code under the L<Model> namespace.
Use L<DBIx::Simple::Class>.
Generate your classes from tables using C<dsc_dump_schema.pl> utility
that comes with DBIx::Simple::Class.
Feel free to contribute to L<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
L<SQLite|http://sqlite.org/>, L<MySQL|http://dev.mysql.com/>
and L<PostgreSQL|http://www.postgresql.org/>.
Use the L<DBIx::Simple::Class/SQL> feature to achieve this.
See L<DBIx::Simple::Class/SQL> 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'){
  ...
  }

=head2 PLUGINS

Feel free to write L<Ado::Plugin>s but first see if there isn't already
a L<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.

=head1 AUTHOR

Красимир Беров (Krasimir Berov)

=head1 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.

=cut