[rt-users] suggestions for improvement

[Alex Peters]

>
> The concern here is that the installation process is not clear, and is
> *nowhere* made clear, that the extension is more than the single file.
> Many, many projects have extensions which are single files. Modern
> sysadmins install JS modules, Java plugins, browser plugins, Python
> modules, Ruby modules, Puppet modules, Chef cookbooks, Perl modules, etc.
> Even some of these configuration management packages are single files. The
> ones which aren’t contain clear instructions on how to install them.
>

It's not about whether an extension has a single file or not.  To install
any extension (be it for RT, or just Perl), you need a Makefile or a
Makefile generator whether the installed result is a single file or many.
The Makefile/Makefile generator is included in distributions.  You don't
get those things by downloading a single file.  This isn't an RT-specific
thing—this is a Perl thing.  The only reason it has anything to do with RT
is because of RT's design decision to use standard Perl modules for RT
extensions.  That's why I've suggested that RT's documentation should at
least mention that fact.

No Perl module is ever installed by downloading the .pm file and placing it
somewhere.  You need at least a .pm file and a Makefile, then you use the
Makefile to install the Perl module.  Or if there isn't a Makefile, you
follow the specific instructions included in the README/INSTALL file of the
distribution.  That's why I said you only install distributions, not
modules.  Again, none of this is specific to RT—it's Perl.


> Even if one is an established Perl hacker, a large majority of CPAN
> modules are a single .pm file. The fact that one must download the entire
> package, not just the singular file, is not stated anywhere. This deserves
> clarity.
>

The fact that one must download the entire package is really emphasised by
the fact that the only, single Download link on any CPAN page is the entire
package, not just any singular file.  You won't encounter any Download
links for individual files for that very reason.

I can't argue that that's not explicitly documented somewhere, but neither
is it documented that you must download single files individually and
manually because there's no Download link for individual files.  No one
should be doing that, so CPAN's site doesn't support that action.


> Every system for which a plugin is multiple files focuses on, and makes
> obvious, how to install the plugin.


Perl's system is no exception.  This information exists for almost every,
if not every, RT extension/Perl module distribution in the form of included
README and/or INSTALL files, as I mentioned in a previous post.


> Obviously, if a confused person comes here Alex Peters’ will abuse them
> and talk down to them about how they’re stupid for not using CPAN to
> download an install the module, even though there’s no documentation for
> doing that either.


There's no documentation on RT's side because this is a Perl issue.  It's
standard convention for all Perl modules.  I don't think that RT's
documentation should be a manual on how to use Perl.

That said, I do believe (as I've already stated elsewhere in this thread)
that perhaps RT's documentation should be upfront about "knowledge of
installing Perl modules" being a prerequisite for administering RT
extensions, and link to Perl's documentation on how to install modules in
case that knowledge isn't already there.


> You would at least need to pass -I /opt/rt4/lib to your CPAN invocation
> for this to work.


Actually, that's not correct.  RT extensions have custom Module::Install
functionality to either detect the correct RT library directory, ask for
it, or retrieve it from the RTHOME environment variable (which I raised in
one of my earliest posts in this thread).  The custom functionality also
puts the plugin's files under RT's library directory instead of in the
standard Perl location for Perl modules.

In any case, as Alex Vandiver pointed out somewhere in this thread,
following the specific README/INSTALL instructions per RT extension is
necessary in case installation involves things that can't be fully
automated, such as database schema adjustments.  Because every RT extension
might have its own special installation instructions, RT's documentation
really can't say anything more than "read the installation instructions
included with the extension" or else important details might be missed.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bestpractical.com/pipermail/rt-users/attachments/20141212/ed1b11c2/attachment.htm>