NAME¶

Perl::Critic::CORE_DEVELOPER - Hints for working on the Perl::Critic core.

DESCRIPTION¶

This document is a grab-bag of notes for those who are working on the underpinnings of Perl::Critic. They are intended to be informative, but unfortunately can not really be considered authoritative. It is in the nature of the task being described that the user of this document will end up working out the details for him- or herself based on the actual work being performed. Caveat lector.

BECOMING A CORE DEVELOPER¶

Here are my thoughts on how to get started. Note that the steps are not numbered because I'm not sure there is a clear order to them. The items with two stars in front of them are from the mailing list; the ones with one star are my opinion. Although sometimes I have felt it helpful to comment on the two-star items, just to make things thoroughly unclear.

* If you're unsure of yourself, install Perl::Critic, then download the source and rummage around in it.

** Subscribe to the developers' mailing list. There are instructions in "EXTENDING THE CRITIC" in Perl::Critic. The commits mailing list is another good one.

** You will need to be registered as a developer before you can actually change code. <http://perlcritic.tigris.org/> only lets you register as an observer. I got promoted on registration, but if that doesn't happen, a note to the developers' mailing list might help.

** If you are working on an RT ticket, you should update the ticket to say that you are, to keep other people from duplicating your effort.

* I personally would update RT at the point I was reasonably confident I could hack it, just to prevent myself from having to update RT again in a week or so saying "oops, bit off more than I could chew." But that's me talking.

* Subversion (also known as svn, which is the command name) is a version control system. It provides a repository for the code being worked on. Developers check out the code into a local directory, work on that, and and then commit changes back to the repository. Any previous version of the code is available from the repository - a bad change can be backed out, though the longer the bad change hangs around the harder it may be to deal with.

* Install Subversion if you don't already have it. You can get it from <http://subversion.tigris.org/>. The current version is Subversion 1.6, but as of mid-2009, the 1.4.4 client seems to be adequate. The O'Reilly book, "Version Control with Subversion", is available online at <http://svnbook.red-bean.com/>. The English version of the 1.4 documentation may be still available at <http://svnbook.red-bean.com/en/1.4/index.html>.

* Branching is essentially pulling off your own managed copy of the code to develop on. It is creating a "sandbox", if you will. You can commit changes back to the repository without affecting the main line of development (the "trunk"). The entire branch can be abandoned without affecting the trunk. The down side of branches is that it is a bit of a pain to merge them back into the trunk.

Consult the developers' mailing list on whether you should branch or work directly against the trunk.

** The Perl Critic subversion repository on Tigris contains a bunch of stuff other than Perl::Critic. You probably do not need it all. But if you execute the 'svn checkout' command given on Tigris you get it all. This is not recommended.

* Here is my "branch and checkout" cookbook:

    Name the branch after the ticket you are working on (e.g. rt25046).
    Issue the following commands (we assume '$ ' is your system prompt):
    $ svn copy
        http://perlcritic.tigris.org/svn/perlcritic/trunk/distributions/Perl-Critic
        http://perlcritic.tigris.org/svn/perlcritic/branches/rt25046
        -m "Put your comment here" --username your_username
    $ svn checkout http://perlcritic.tigris.org/svn/perlcritic/branches/rt25046
        --username your_username

The 'svn copy' command is the one that does the branch. Each 'svn' command is one line, though sometimes (e.g. the 'branch') it's a huge one. The "svn" commands above have been wrapped. A checkout from the trunk is also done with the "svn checkout" command, but specifying the trunk's URL. You can also specify, as a second argument to "svn checkout", the directory you want the code to go into.

** Development requires using Module::Build rather than ExtUtils::MakeMaker. In other words,

    $ perl Build.PL
    $ ./Build
    $ ./Build test

** You need to run the suite of author tests by running

    $ ./Build authortest

(but not 'make authortest', which is one of the reasons you should start with Build.PL rather than Makefile.PL) These should run cleanly before you declare your work done. My advice, though, is not to worry about them until your code is functionally correct.

    Devel::EnforceEncapsulation
    Perl::Critic::More
    Test::Kwalitee
    Test::Memory::Cycle
    Test::Perl::Critic
    Test::Pod
    Test::Pod::Coverage
    Test::Without::Module

ADDING A GLOBAL CONFIGURATION ITEM¶

Perlcritic handles global configuration items and command line options in very similar ways. These notes will cover adding both a global configuration item and a corresponding, same-named command option. These notes can not, of course, cover implementing the functionality of the new item, just the mechanics of getting the item into Perl::Critic.

    $NEW_ITEM_DEFAULT

    new_item

    $self->{_new_item} = dor(delete $args{'new-item'},
        $NEW_ITEM_DEFAULT);

    sub new_item {
        my ($self) = @_;
        return $self->{_new_item};
    }

    sub new_item {
        my ($self) = @_;
        return $self->{_new_item};
    }

    sub new_item {
        my ($self) = @_;
        return @{ $self->{_new_item} };
    }

    t/00_modules.t
    t/01_config.t
    t/01_config_bad_perlcritic.t
    t/04_options_processor.t
    t/07_command.t
    t/10_user_profile.t
    t/16_roundtrip_defaults.t

DEPRECATING AND REMOVING A PUBLIC SUBROUTINE OR METHOD¶

This is something to be done cautiously. The code in question may only exist to serve Perl::Critic, but if it is documented as public it may well be in use "in the wild", either in add-ons to Perl::Critic or by users of Perl::Critic.

Before deprecating public code, the potential deprecator must discuss the issues on the Perl::Critic developers' mailing list. There are instructions on how to subscribe to this list in "EXTENDING THE CRITIC" in Perl::Critic.

Once agreement is reached, the technical details of the deprecation are fairly simple.

You must insert something like the following in the code to be deprecated:

    warnings::warnif(
        'deprecated',
        'Perl::Critic::Utils::foo() deprecated, use blah::foo() instead.',
    );

You should have the deprecated subroutine delegate its functionality to the new subroutine, if that is practical (it may not be).

You must update the documentation to say that the old code is deprecated, and what the replacement is.

After the old code has been deprecated for a couple production releases, it can be removed.

AUTHOR¶

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT¶

Copyright (c) 2009-2011 Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.