[rt-users] Documentation for installing extensions

[Alex Vandiver]

On 12/14/2014 07:23 PM, Jo Rhett wrote:
> I’m not sure where you are looking. I’m at
> https://www.bestpractical.com/rt/extensions.html and it links to
> https://metacpan.org/pod/RT::Extension::SLA without #INSTALLATION.

Sorry -- I did not mean to imply that our link contained the
#INSTALLATION anchor, merely pointing out that the SLA extension does
contain what I believe to be clear installation instructions.  I choose
to believe that users are capable of scrolling down to the third heading
on the page.

> It seems you’ve updated this to link to MetaCPAN now. That does look
> better, but I’m not sure that the “Source Code” link is truly an
> improvement, for a reason I’ll describe in my next reply below (read
> down)

I agree that most users won't need the github link; it is mostly
superfluous, as metacpan provides it in most cases.  I've removed it for
all of the extensions which are on CPAN, which is most of them.

>> Can you point me at documentation which suggests downloading one
>> file from CPAN and putting it in place manually?  Perl's own core 
>> documentation (http://perldoc.perl.org/perlmodinstall.html )
>> suggests:
> 
> And this is the core issue that both you and Alex Peters seem to be
> hung up on, which I keep addressing over and over again but it’s not
> getting through. Let me try another way.

I was not trying to argue that we cannot make this simpler for new users
-- I agree that we can, and should.  I was primarily addressing what
seemed to be your belief that most CPAN modules could be installed via
copying a single file, or that this was a widely documented custom for
CPAN modules.

I hear you that modules in other languages are often more
straightforward to install than Perl's -- and that while our bar for
installation is currently set at the same as Perl's, that is not to say
that we cannot do better.

> So let’s start at the top of extensions try to follow the clear
> process for each one. For this I’m going to exclusively use modules
> provided by Best Practical.

That list has absolutely needed better curation for a while; for
instance, it didn't list 4.2 compatibility for the majority of the
extensions.  Thank for calling out some of the entries that need
updating, and providing impetus for fixing them.

> https://metacpan.org/pod/RT::Extension::ActivityReports#INSTALLATION 
> — does not link to installation as you suggested above — forgets to
> mention that you need "-I /opt/rt4/lib” so fails on my fresh 4.2.9
> installation

Where did you find you needed to add -I /opt/rt4/lib ?  With a fresh
4.2.9 in /opt/rt4, the installation instructions work fine for me:
https://chmrr.net/nopaste/2014-12-15l4EVqmFw

> https://metacpan.org/pod/RT::Extension::ActivityReports::Billing —
> error, not found

This extension was last updated in 3.8, which is why it never got to
CPAN.  I've removed it from the list.

> https://metacpan.org/pod/RT::Extension::AddAdminCcsOnQueueChange — no
> installation instructions

Pushed an updated version with our canonical installation instructions,
and version compatibility notes.

> https://metacpan.org/pod/RT::Extension::AttributeWalker — no
> installation instructions

Adds a command-line tool, which is probably not useful for most users;
I've removed it from the list.

> https://metacpan.org/pod/RT::Authen::Bitcard — no installation
> instructions

Written for rt.perl.org and rt.cpan.org, but unlikely to be useful to
anyone else; I've removed it from the list.

> https://metacpan.org/pod/RT::Authen::ExternalAuth#INSTALLATION — does
> not link to installation as you suggested above — forgets to mention
> that you need "-I /opt/rt4/lib” so fails on my fresh 4.2.9
> installation

As above.

> Do I really need to keep going?

Did you have feedback on the generalized installation instructions that
I posted earlier in this thread?


https://github.com/bestpractical/rt/blob/4.2/installing-extensions/docs/extensions.pod

> In short, yes a Perl hacker can figure this out. Is your target
> audience ONLY perl hackers? This is the key point I’m trying to get
> through.  If you only want to sell RT and its services to Perl
> hackers, then feel free to ignore my advice.

I don't disagree that plugin installation could be made better, and it's
an area we'd like to improve on.  Where you've made actionable
suggestions, I believe we've responded to the best of our ability.  The
larger-scale changes necessary to make plugins be one-click installs
cannot, obviously, appear overnight.

RT is open-source; if you support a number of RT installations and have
a vested interest in making plugin installation easier for your clients,
patches in this area would certainly be accepted.
 - Alex