Gianluca Casati

NAME

Task::BeLike::FIBO -- Leonardo Pisano a.k.a. Fibonacci

CPAN version Build Status

SYNOPSIS

Read how I create Perl packages

    cpan Task::BeLike::FIBO
    perldoc Task::BeLike::FIBO

Create a CPAN package

    mkdir My-Package-pm
    cd My-Package-pm
    wget -q http://g14n.info/Task-BeLike-FIBO-pm/scaffolding -O - | bash

DESCRIPTION

Hi! I am FIBO, an italian mathematician. I graduated in 2005 at Università degli Studi di Genova and since then I work doing Business Intelligence and Web Analytics. My boss said: you need Perl. So I started using this language. I like many programming languages, but, Perl really help me to pay my rent.

This is a primary about my habits and a collection of modules I use when I write Perl code.

PACKAGE GUIDELINES

Here a package refers to a distribution, a set of Perl modules which could be uploaded to PAUSE.

Do not get crazy with automatic generators. I am a mathematician and a coder, not a corporation.

Every package is different and has different needings.

Just use copy and paste and your brain!

The smack of a DRY KISS is not that bad.

Learn from nature: stay as minimal as possible.

FILES

Follows a list of sample files I usually include in a package, My::Package for instance.

I use to create a GitHub repo named My-Package-pm.

I also use Travis CI.

And yes, Task::BeLike::FIBO was created with these guidelines too! So it is a good example of a meta package (I am a mathematician, I told you ☺).

  • lib/My/Package.pm

    This is the main file of the package and looks something like this

        package My::Package;
    
        our $VERSION = '0.01';
    
        1;
    
        __END__
    
        =encoding utf8
    
        =head1 NAME
    
        My::Package -- is yet another Perl package
    
        =begin HTML
    
        <p><a href="https://metacpan.org/pod/My::Package" target="_blank"><img alt="CPAN version" src="https://badge.fury.io/pl/My-Package.svg"></a> <a href="https://travis-ci.org/fibo/My-Package-pm" target="_blank"><img alt="Build Status" src="https://travis-ci.org/fibo/My-Package-pm.svg?branch=master"></a></p>
    
        =end HTML
    
        =head1 SYNOPSIS
    
            package Your:Package;
            use My::Package;
    
            # Create a My::Package instance.
            my $foo = My::Package->new;
    
            # foo goes to a bar, ehm ... to have a coffee.
            $foo->bar;
    
        =head1 DESCRIPTION
    
        This is a description of what <My::Package> does, why you maybe want to use it, the motivations behind him.
    
        =head1 COPYRIGHT AND LICENSE
    
        This software is copyright © 2015 by L<G. Casati|http://g14n.info>.
    
        This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
    
        =cut
  • README.md

        My-Package
        ==========
    
        My-Package description ...
    
        To install, pray the mantra
    
            perl Makefile.PL
            make
            make test
            make install
    
        For more information point your browser to [online docs](https://metacpan.org/pod/My::Package).
    
        --------
        [![CPAN version](https://badge.fury.io/pl/My-Package.svg)](https://metacpan.org/pod/My::Package)
        [![Build Status](https://travis-ci.org/fibo/My-Package-pm.png?branch=master)](https://travis-ci.org/fibo/My-Package-pm)

    Yes, it is always a good idea to add a README. If the package is not open sourced, i.e. will be delivered to a customer on premise and will not be hosted on GitHub, create a README.txt instead.

  • .travis.yml

    Get it with this command

        $ wget http://g14n.info/Task-BeLike-FIBO-pm/travis.yml -O .travis.yml
  • .gitignore

    Get it with this command

        $ wget http://g14n.info/Task-BeLike-FIBO-pm/gitignore -O .gitignore
  • Makefile.PL

        use strict;
        use warnings;
    
        use ExtUtils::MakeMaker 6.64;
    
        WriteMakefile(
            ABSTRACT_FROM => 'lib/My/Package.pm',
            VERSION_FROM  => 'lib/My/Package.pm',
            AUTHOR        => 'G. Casati <fibo@cpan.org>',
            NAME          => 'My::Package',
            LICENSE      => 'artistic_2',
            MIN_PERL_VERSION => '5.12.0',
            META_MERGE => {
                resources => {
                    homepage   => 'https://metacpan.org/pod/My::Package',
                    license    => 'http://g14n.info/artistic-license',
                    repository => 'https://github.com/fibo/My-Package-pm',
                    bugtracker => 'https://github.com/fibo/My-Package-pm/issues'
                },
            },
            PREREQ_PM => {
                # 'Some::Package' => '0',
                # 'Other::Package' => '1.2.3'
            },
            # EXE_FILES => ['bin/foo', 'bin/bar'],
            BUILD_REQUIRES => {
                'ExtUtils::MakeMaker' => '6.64'
            },
            test => { TESTS => 't/*.t' },
            TEST_REQUIRES => {
                'Test::Compile'      => '1.2.1',
                'Test::More'         => '1.001009',
                'Test::Pod'          => '1.48'
            }
        );

    A note about versions in PREREQ_PM: keep in mind that when specifying a version for core modules, it should match the version shipped with Perl version MIN_PERL_VERSION.

    The corelist app is your friend.

    For example if I want to figure out which version of File::Path I should require, if the lower Perl version I am supporting is 5.8.0 I launch

        $ corelist -a File::Path | grep v5.8.0
          v5.8.0     1.05

    so I know I should go for 1.05.

    Note that MIN_PERL_VERSION defaults to 5.12.0, which is the first modern Perl release, you know. See also Perl 5.12 for Everyday Use. Anyway, I admire a lot the veterans that dig into ancient versions of Perl and support them in their packages.

  • MANIFEST.SKIP

    Get it with this command

        $ wget http://g14n.info/Task-BeLike-FIBO-pm/MANIFEST.SKIP
  • Changes

    It is considered a good habit to keep track of at least major changes to inform users what they should expect when upgrading version.

        0.01 2014-12-02
        + First release

WORKFLOW

  • Start a feature branch

        $ git checkout -b somefeature
  • Write documentation about new feature. Then write tests to check it and code to implement it.

  • Run tests

        $ prove -l --state=save
  • If some test does not pass, fix code and run tests that failed

        $ prove -l --state=save,failed
  • Commit changes

        $ git commit -am 'added some feature'

    Merge feature branch and push

        $ git rebase master
        $ git checkout master
        $ git merge somefeature
        $ git push

    Delete feature branch

        $ git branch -d somefeature
  • Update version, usually in file lib/My/Package.pm.

    Use Semantic Versioning.

    Check that Changes file is updated with information about modifications done.

    Update code coverage report if it is in place, see "#CODE-COVERAGE" in CODE COVERAGE section.

    Update GitHub Pages if used, see "#GITHUB-PAGES" in GITHUB PAGES section.

    Create a new release

        $ perl Makefile.PL
        $ make
        $ make test
        $ make manifest
        $ make dist
        $ make realclean

    Create a git tag

        $ git tag v0.01
        $ git push origin v0.01
  • Upload to PAUSE

        $ cpan-upload -u fibo My-Package-0.01.tar.gz
        PAUSE Password:
        registering upload with PAUSE web server
        POSTing upload for My-Package-0.01.tar.gz to https://pause.perl.org/pause/authenquery
        PAUSE add message sent ok [200]

STUFF INCLUDED

MISCELLANEA

GITHUB PAGES

It can be useful to put some content online, and GitHub Pages is really comfortable.

Just create a gh-pages folder

    $ mkdir gh-pages

Add some content, commit and then push it on gh-pages branchusing git subtree

    $ git commit -a
    $ git subtree --prefix gh-pages push origin gh-pages

Since I have a CNAME file in my fibo.github.io repo, where fibo is my GitHub username, if I add somefile to gh-pages folder

    $ touch gh-pages/somefile

if my repo name is My-Package-pm, it will be served with url http://g14n.info/My-Package-pm/somefile with proper mime type.

CODE COVERAGE

Create a folder that will contain code coverage metrics report

    $ mkdir -p gh-pages/code

Run tests with a Devel::Cover harness, it will take more time than running bare tests

    $ export HARNESS_PERL_SWITCHES=-MDevel::Cover
    $ prove -l

Remove harness flag, otherwise all tests in your current session will run and compute coverage.

    $ unset HARNESS_PERL_SWITCHES

Generate html report

    $ cover -outputdir gh-pages/code -report html_basic

See also GitHub Pages section for instructions about how to commit generated html report.

Don't forget to add a link to the html report somewhere in your documentation, something like

    =head1 CODE COVERAGE

    Code coverage metrics report available L<here|http://g14n.info/My-Package-pm/code/coverage.html>

VERSION NUMBERS IDIOSYNCRASY

Avoid to release versions like 0.13 or even worse 1.13 or any number that do not make you feel comfortable: skip it and go straight to 0.14! You never knows which strange entanglements there are in this Universe.

CODE COVERAGE

Code coverage metrics report available here. By the way, tests in this meta package are not relevant.

COPYRIGHT AND LICENSE

This software is copyright © 2015 by G. Casati.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.