Devnotes

Some notes on Ado development

Read Ado::Manual

We assume you are already fmiliar with Mojolicious and you have read Mojolicious::Guides and all its major tutorials. Go and read Ado::Manual and everything under it, especially Ado::Manual::Contributing.

Development Environment

Note! We assume a Unix environment mostly a Debian-like distribution.

If you want to be one of the authors of Ado you need to have a toolset. The following tools are needed:

1. Minimum Perl version 5.14.0. Several Perl versions is recommended to have (5.14.X-5.16.X-5.18.X). Use several Perl vendors' distributions: perlbrew, CitrusPerl, ActivePerl, Strawberry Perl interchangeably to make sure what you did works on at least 2 Perl vendors and all major versions (5.14.0 and next).

2. A decent text editor. Any of the following should work for you depending on your preferences: Vim, Sublime Text, jEdit (all of them with a ctags plugin). The ctags tool must be installed. Eclipse with the EPIC - Perl Editor and IDE for Eclipse is also fine.

3. For running author's tests set the $TEST_AUTHOR environment variable in your ~/.bashrc:

export TEST_AUTHOR=1

Source your ~/.bashrc or in a new terminal window do:

    cd /to/where/you/cloned/Ado
    perl Build.PL
    ./Build installdeps

Write author's tests in addition to regular tests for regular runtime. Put required dependencies for author's tests in Build.PL in $author HASHref in the corresponding section. See Build.PL

1. Check if your code is well covered with tests.

    user@mashine:~/dev/Ado$ ./Build testcover --test_files t/ado-build.t 
    Deleting database /home/user/dev/Ado/cover_db
    t/ado-build.t .. ok    
    All tests successful.
    Files=1, Tests=27, 24 wallclock secs ( 0.07 usr  0.00 sys + 21.05 cusr  1.84 csys = 22.96 CPU)
    Result: PASS
    Reading database from /home/user/dev/Ado/cover_db


    ---------------------------- ------ ------ ------ ------ ------ ------ ------
    File                           stmt   bran   cond    sub    pod   time  total
    ---------------------------- ------ ------ ------ ------ ------ ------ ------
    blib/lib/Ado/Build.pm          97.5   77.8   57.1  100.0  100.0  100.0   91.9
    Total                          97.5   77.8   57.1  100.0  100.0  100.0   91.9
    ---------------------------- ------ ------ ------ ------ ------ ------ ------
    
    
    HTML output written to /home/user/dev/Ado/cover_db/coverage.html
    done.

1. Add some aliases for often used commands in your ~/.bash_aliases

    user@mashine:~/dev/Ado$ cat ~/.bash_aliases 
    alias clear='reset && clear'
    alias t='./Build test --verbose 1 --test_files'
    alias test_author='clear;TEST_AUTHOR=1 ./Build distclean; perl Build.PL && t'
    alias test_user='clear;TEST_AUTHOR=0 ./Build distclean; perl Build.PL && t'
    alias build_user_dist='clear;TEST_AUTHOR=0 ./Build distclean; perl Build.PL && t \
    && ./Build dist'

    #then in the terminal..
    #run all pod tests
    t t/pod*
    #run all tests
     t
    #prepare a distribution and upload to CPAN
    test_author && build_user_dist
    mojo cpanify -u berov -p нещотайно Ado-0.25.tar.gz 
    Upload successful!

To ignore or not to ignore some files?

Since version 0.23 we ignore log files. In some cases you may wan to temporarily ignore some files

git update-index --assume-unchanged etc/plugins/my_plugin.conf
git update-index --assume-unchanged etc/ado.conf

Then you may want to restore the index:

git update-index --no-assume-unchanged  etc/ado.sqlite

For details see Ignoring versioned files, git-update-index

Releasing to CPAN

When preparing a release for CPAN unset $ENV{TEST_AUTHOR} to generate META.json and META.yml that require fewer dependencies.

    #see "Add some aliases.." above
    build_user_dist
    mojo cpanify -u berov -p нещотайно Ado-0.25.tar.gz 
    Upload successful!

Re-flowing a pod document

cat lib/Ado/Manual.pod | perl -MPod::Wrap -E \
'$w=Pod::Wrap->new;$w->parse_from_filehandle' > lib/Ado/Manual.pod

Then fix the code examples.