NAME

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

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

App::Ack

Yes, I was hooked by ack. See also ack.vim and ack-tutorial.
CPAN

See how to setup A CPAN client that works like a charm.
CPAN::Uploader to release modules using a cli. It also depends on LWP::Protocol::https which depends on IO::Socket::SSL which I think should be a core module.
Devel::Cover to add code coverage metrics. It is installed only for Perl <v5.22 otherwise, at the time of this writing (2015-07-05) it will fail installation.
ExtUtils::MakeMaker version 6.64, cause I use the TEST_REQUIRES option.
Module::CoreList

It is a core module since Perl v5.8.9.
Perl::Tidy

Get a .perltidyrc file
```
$ wget http://g14n.info/Task-BeLike-FIBO-pm/perltidyrc -O .perltidyrc
```
However, do not indent every source file automatically. Indent by hand and use your creativity.

See Perl section in My Vim preferences to see how you can use perltidy with Vim.
PPI::HTML

Used to generate code coverage reports with highlighted syntax.

Test::Compile

Create a t/_compile.t file

$ mkdir -p t; wget http://g14n.info/Task-BeLike-FIBO-pm/t/compile.t -O t/_compile.t

Test::More

Test::Pod

Create a t/_pod.t file

$ mkdir -p t; wget http://g14n.info/Task-BeLike-FIBO-pm/t/pod.t -O t/_pod.t

Term::ReadLine::Perl and Term::ReadKey to enable cpan history of cpan client.
V

I find it very comfortable to know a package Foo version with
```
$ perl -MV=Foo
```

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 is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install Task::BeLike::FIBO, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Task::BeLike::FIBO

CPAN shell

perl -MCPAN -e shell
install Task::BeLike::FIBO

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

PACKAGE GUIDELINES

FILES

WORKFLOW

STUFF INCLUDED

MISCELLANEA

GITHUB PAGES

CODE COVERAGE

VERSION NUMBERS IDIOSYNCRASY

CODE COVERAGE

COPYRIGHT AND LICENSE

Module Install Instructions