Helping to clean CPAN: April 2016

… where I get out my virtual broom and sweep up cruft in my assigned distribution for this month’s edition of the CPAN Pull Request Challenge.

This month’s module: Net::Redmine

Net::Redmine is an API to communicate with and carry out operations on a Redmine server.

First impressions

In this section I try to get a feeling for the state of the module, how up to date it is, how often people are contributing to it, how many other distributions are depending on it, how many bugs/issues it currently has, what the CPANTS kwalitee is, etc.

• last commit 10th Feb 2012 (https://github.com/gugod/net-redmine)
• latest release 10th Feb 2012 (https://metacpan.org/pod/Net::Redmine)
• 3 open issues in GitHub (one issue asks what one could do as part of CPAN PRC)
• 0 pull requests
• 1 open issue on RT (4 years old) (https://rt.cpan.org/Public/Dist/Display.html?Name=Net-Redmine)
• 1 reverse dependency via metacpan
• no test failures on cpantesters, but lots of “unknown”, “invalid” or “na” builds: http://matrix.cpantesters.org/?dist=Net-Redmine+0.09
• CPANTS report (http://cpants.cpanauthors.org/dist/Net-Redmine)
  • core metrics: all ok
  • extra metrics
    • META.yml doesn’t declare Perl version
  • experimental metrics
    • META.yml doesn’t have a provides section
    • build prereq doesn’t match usage

Initial inspection of the source code

After forking the repo and cloning a local copy, let’s have a look at the project to see what build system it uses, if the test suite works and the tests pass, if it could do with a Travis-CI config file (or if present, if it can be updated).

• uses Module::Install (which is deprecated) -> convert to EUMM?
• README is simple text. Convert README to markdown? Mention module purpose in README (which is only mentioned in module pod)?
• no Travis-CI config; add a .travis.yml?
• uses Any::Moose which is deprecated in favour of Moo
• cpanm --installdeps . fails due to syntax error in Makefile.PL

String found where operator expected at Makefile.PL line 33, near
"author_tests 'xt'"
	(Do you need to predeclare author_tests?)
syntax error at Makefile.PL line 33, near "author_tests 'xt'"
Execution of Makefile.PL aborted due to compilation errors.
include
/home/cochrane/Projekte/OSSProjekte/net-redmine/inc/Module/Install.pm

• running perl Makefile.PL fails with the same error
• this is a Module::Install problem and means that the Module::Install::AuthorTests module is missing
• cpanm Module::Install::AuthorTests
• afterwards cpanm --installdeps . works
• … however HTML::WikiConverter (a dependency of HTML::WikiConverter::Markdown, which is required for Net::Redmine) fails its tests:

Building and testing HTML-WikiConverter-0.68 ... FAIL
! Installing HTML::WikiConverter failed. See
/home/cochrane/.cpanm/work/1460809225.6332/build.log for details. Retry with
--force to force install it.
! Installing the dependencies failed: Module 'HTML::WikiConverter' is not
installed
! Bailing out the installation for HTML-WikiConverter-Markdown-0.06.

• one problem with HTML::WikiConverter is simply a pod coverage test:

Building and testing HTML-WikiConverter-0.68 ... FAIL
! Installing HTML::WikiConverter failed. See
/home/cochrane/.cpanm/work/1460809225.6332/build.log for details. Retry with
--force to force install it.
! Installing the dependencies failed: Module 'HTML::WikiConverter' is not
installed
! Bailing out the installation for HTML-WikiConverter-Markdown-0.06.

• the other issue was:

request for <http://diberri.dyndns.org/wikipedia/html2wiki-old/test.html> failed at t/01-wikiconverter.t line 162.

• … which merely means that the test website no longer exists
• one could move on by simply using the --notest option to cpanm, or submit a patch to HTML::WikiConverter. Unfortunately, HTML::WikiConverter is only a gitpan account on GitHub (and hasn’t seen a release since 2009) so --notest looks like the way to go in this case.
• now perl Makefile.PL runs to completion
  • one warning: Cannot determine perl version info from lib/Net/Redmine.pm
• make test now passes, however gives warnings:

skipped: Need `SD_REDMINE_RAILS_ROOT` env var

• … which should be documented somewhere, because it’s not documented in the module, and …

t/ticket-status.t ........ skipped: duplicated with ticket-resolution.t
t/tickets.t .............. skipped: Need SD_REDMINE_RAILS_ROOT env var
t/user.t ................. skipped: Need SD_REDMINE_RAILS_ROOT env var
xt/01_podspell.t ......... skipped: Test::Spelling is not installed.
xt/02_perlcritic.t ....... skipped: Test::Perl::Critic is not installed.

• hence Test::Spelling and Test::Perl::Critic should be installed as well
• cpanm Test::Spelling Test::Perl::Critic
• Now we have spelling and perlcritic test errors…

xt/01_podspell.t ......... 1/6
#   Failed test 'POD spelling for lib/Net/Redmine.pm'
#   at xt/01_podspell.t line 7.
# Errors:
#     hasref
#
# All incorrect words, by number of occurrences:
#      1: hasref
# Looks like you failed 1 test of 6.
xt/01_podspell.t ......... Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/6 subtests
xt/02_perlcritic.t ....... 1/?
#   Failed test 'Test::Perl::Critic for "lib/Net/Redmine.pm"'
#   at
/home/cochrane/perl5/perlbrew/perls/perl-5.18.4/lib/site_perl/5.18.4/Test/Perl/Critic.pm
line 104.
#
#   Variable declared in conditional statement at line 35, column 5.
Declare variables outside of the condition.  (Severity: 5)

#   Failed test 'Test::Perl::Critic for "lib/Net/Redmine/Ticket.pm"'
#   at
/home/cochrane/perl5/perlbrew/perls/perl-5.18.4/lib/site_perl/5.18.4/Test/Perl/Critic.pm
line 104.
#
#   Expression form of "eval" at line 72, column 5.  See page 161 of PBP.
(Severity: 5)
xt/02_perlcritic.t ....... Dubious, test returned 1 (wstat 256, 0x100)
Failed 2/6 subtests

• the warning message concerning SD_REDMINE_RAILS_ROOT is incorrect; the correct environment variable is NET_REDMINE_RAILS_ROOT.

• need a redmine server to be installed and running. To get this going, follow the following steps:

$ wget http://www.redmine.org/releases/redmine-3.2.0.tar.gz
$ tar -xvzf redmine-3.2.0.tar.gz
$ sudo aptitude install build-essential ruby-dev sqlite3 pkg-config libmagickcore-dev libmagickwand-dev
$ cd redmine-3.2.0
$ cp config/database.yml.example config/database.yml #  -> use sqlite3 config for development db
$ cat > config/database.yml <<"EOT"
# SQLite3 configuration
development:
  adapter: sqlite3
  database: db/redmine.sqlite3
EOT
$ mkdir $PWD/.gem
$ export GEM_HOME=$PWD/.gem
$ export PATH=$PWD/.gem/bin:$PATH #  (need local bundler)
$ gem install bundler
$ bundle install
$ bundle exec rake generate_secret_token
$ RAILS_ENV=development bundle exec rake db:migrate
$ RAILS_ENV=development REDMINE_LANG=en bundle exec rake redmine:load_default_data
$ mkdir -p tmp tmp/pdf public/plugin_assets
$ bundle exec rails server webrick -e development   # to test if it works

• it turns out that the module requires at most Redmine version 1.4.7, since it needs the scripts/runner and scripts/server scripts, which are no longer avaiable from Redmine version 2.0.0

Code Coverage

Looking at the code coverage can give an indication of code quality. If the project is well covered, this means most changes made in pull requests can be made with some confidence that any problems will be caught by the test suite. If the code coverage is low, then this is something that one could address as a pull request (or set of pull requests).

In EUMM and Build::Module projects, one simply needs to install Devel::Cover and run

$ cover -test

In Dist::Zilla projects, one needs to install the Dist::Zilla::App::Command::cover plugin, after which the code coverage can be checked via:

$ dzil cover

In this distribution (without NET_REDMINE_RAILS_ROOT env setting), the coverage is:

24.7% statement coverage; 21.8% total coverage

With the NET_REDMINE_RAILS_ROOT setting

NET_REDMINE_RAILS_ROOT=redmine-3.2.0 cover -test

the coverage climbs to

40.0% statement coverage; 35.3% total coverage

which is still quite low and could do with improving.

Overview of the pull requests made

• correct SD_REDMINE_RAILS_ROOT to NET_REDMINE_RAILS_ROOT (https://github.com/gugod/net-redmine/pull/4)
• fix spelling test error (https://github.com/gugod/net-redmine/pull/5)

Conclusion

I was a bit disappointed with my effort this month: only two pull requests and many, many things I still could have looked at. For instance I’d planned to do at least these things:

• declare minimum Perl version (perlver report 5.6.0 as min version)
• fix spelling and perlcritic test errors
• add a .travis.yml
• fix SD_REDMINE_RAILS_ROOT env var warning and document what var is used for
• document development installation instructions
• rename t/net_redmine_test.pl to t/net_redmine_test.t?

I was especially disappointed since I’d wanted to try this module out at $work, since we use Redmine as a wiki and trouble ticket system. At the very least it would have been interesting to see how to use the module in a live environment. Unfortunately, due to time constraints the things on my TODO list just didn’t happen. Perhaps these ideas can be useful to someone else’s upcoming Pull Request Challenge assignment.