Plugins link to module file, not package file

RT Users
21

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.

22

Moving to the topic at hand: the links we provide are to the
documentation of the module, not to the distribution page. This
is intentional, soas to provide the user with a longer description
of the extension first, to let them make a more informed decision
as to whether the extension suits their needs.

Linking to the documentation makes sense. Linking to the module docs
without any clear installation instructions does not.

Picking a commonly-used module, RT::Extension::SLA, and looking at the
documentation we link to:

It contains an “INSTALLING” section which details the steps necessary to
install the module. I believe that all, or nearly all, of the modules
that Best Practical places on CPAN have a similar section.

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.

Can you point me at documentation which suggests downloading one file
from CPAN and putting it in place manually? Perl’s own core
documentation (perlmodinstall - Installing CPAN Modules - Perldoc Browser ) suggests:

  • downloading a .tar.gz file
  • unpacking it
  • running perl Makefile.PL
  • followed by running make install

Note the date in the footer: written 1998, and last updated 2003; these
are not new suggestions. A search for “install perl module”
additionally confirms that the steps are what are, by and large,
suggested everywhere. These are thus the steps which RT extensions
mirror in their installation.

This is not to say that we cannot make RT’s documentation on this
subject clearer. I’m happy to take patches atop the docs I just pushed:

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

I believe that anything which solves the basic confusion here will be
an improvement. Links as simple as the following would be a big
improvement. [Documentation] [Download]

nod Makes sense, and shouldn’t be hard. I’ll add a direct download
link to the Extensions page.

  • Alex

N.B. I have intentionally snipped all discussion of insulting behavior.
Bringing up that topic further is not productive, and, itself, does not
contribute to a welcoming atmosphere. Keep the discussion here
technical, not emotional.

23

Linking to the documentation makes sense. Linking to the module docs
without any clear installation instructions does not.

Picking a commonly-used module, RT::Extension::SLA, and looking at the
documentation we link to:

RT::Extension::SLA - Service Level Agreements for RT - metacpan.org

It contains an “INSTALLING” section which details the steps necessary to
install the module. I believe that all, or nearly all, of the modules
that Best Practical places on CPAN have a similar section.

I’m not sure where you are looking. I’m at Request Tracker... So much more than a help desk — Best Practical Solutions and it links to RT::Extension::SLA - Service Level Agreements for RT - metacpan.org without #INSTALLATION.

None of the modules I looked at or included in my original report linked to an INSTALLATION section. In a section below I go through the first six modules provided by BP, and not a single one of them links to installation instructions, and most of them don’t have that section at all.

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)

Can you point me at documentation which suggests downloading one file
from CPAN and putting it in place manually? Perl’s own core
documentation (perlmodinstall - Installing CPAN Modules - Perldoc Browser ) 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.

Puppet is written in Ruby. Puppet modules are written in Ruby and Puppet Ruby-DSL. If you want to write a really good Puppet module, you need to be a Ruby coder.

HOWEVER, tens if not hundreds of thousands of people use Puppet and install Puppet modules (e.g. extensions) without knowing how to code in Ruby, without having read the Ruby documentation, and without being able to write a single line of Ruby code. They are able to install and use Puppet extensions, without ever learning Ruby.

I would think that this would be a desirable situation for RT. Nearly nobody is hiring these days for Perl knowledge, and that every company I’ve worked at in the last 10 years has been replacing and removing Perl in favor of Python or Ruby. There are numerous places who have refused to consider RT simply because they don’t support Perl. Given this environment today, there is significant advantage for Best Practical to lower that barrier to entry, and make RT work without Perl competency.

Obviously there are numerous places that BP would need to change the installation process to make this work better, however this is clearly one of those places. It would be an improvement.

Can you point me at documentation which suggests downloading one file from CPAN and putting it in place manually?

You linked directly to the singular file. That is the appropriate approach for many, many systems where the plugin is a single file. Remember that there are no sysadmins who know nothing beyond RT and never use any systems beyond RT.

Perl’s own coredocumentation (perlmodinstall - Installing CPAN Modules - Perldoc Browser ) suggests:

…

These are thus the steps which RT extensions mirror in their installation.

I have used numerous self-contained Perl applications which would not work properly if you simply CPANed the module in. I’ve worked in two companies who exclusively used their own library paths to avoid the breakage associated with random CPAN upgrades. No, it is not “obvious” that simply using CPAN or any other “standard perl thing” to install the package would be appropriate.

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.

— 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

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

— no installation instructions

— no installation instructions

— no installation instructions

— 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

Do I really need to keep going?

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.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

24

I�m not sure where you are looking. I�m at
Request Tracker... So much more than a help desk — Best Practical Solutions and it links to
RT::Extension::SLA - Service Level Agreements for RT - metacpan.org 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 (perlmodinstall - Installing CPAN Modules - Perldoc Browser )
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.

RT::Extension::ActivityReports - Additional reports to show Activity in RT - metacpan.org
� 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.

RT::Extension::AddAdminCcsOnQueueChange - Keep AdminCcs in the loop - metacpan.org � no
installation instructions

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

RT::Extension::AttributeWalker - Examining Attributes of a user - metacpan.org � 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.

RT::Authen::ExternalAuth - RT Authentication using External Sources - metacpan.org � 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
25

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.

Again, back to “you must be a perl hacker to use RT”. My entire point is that installation instructions can and should be self-sufficient, without requiring a person to utilize “common knowledge” of something they might not be experts in.

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.

Take a look at the published usage charts for the Perl language and decide if you want RT to have the same (plummeting) trajectory.

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.

Puppet modules are not one-click installations. In fact, I can’t think of any extensions outside of web browser extensions which are even a few clicks. This is not what I have said.

I have suggested that the installation instructions should be self-standing and complete. This is a significantly easier task.

Where did you find you needed to add -I /opt/rt4/lib

Perhaps phrased more straightforward — what about your installation places /opt/rt4/lib in @INC ? Without that, it cannot find the RT-specific paths and makefile creation fails.

I suspect you’ve got this in your path because RT is your job. That’s not true of a normal person. You shouldn’t test in your RT dev setup.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

26

Again, back to �you must be a perl hacker to use RT�. My entire
point is that installation instructions can and should be
self-sufficient, without requiring a person to utilize �common
knowledge� of something they might not be experts in.

I’ve just verified that all of BPS’ packages that we list on the
Extensions page contain an INSTALLATION section which is up-to-date,
which I believe removes any necessity for common knowledge.

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.

Puppet modules are not one-click installations. In fact, I can�t
think of any extensions outside of web browser extensions which are
even a few clicks. This is not what I have said.

Nor did I claim that was what you said; it was what I would ideally
want. Apologies if that was unclear.

I have suggested that the installation instructions should be
self-standing and complete. This is a significantly easier task.

As noted above, I believe I’ve verified that all of our extensions now
contain up-to-date INSTALLATION sections, which I believe suffices to
mark that task as accomplished.

Do you think that that, combined with
https://github.com/bestpractical/rt/blob/4.2/installing-extensions/docs/extensions.pod
will sufficiently help new users?

If not, what would improve on the situation?

Where did you find you needed to add -I /opt/rt4/lib

Perhaps phrased more straightforward � what about your installation
places /opt/rt4/lib in @INC ? Without that, it cannot find the
RT-specific paths and makefile creation fails.

The Module::Install::RTx machinery, loaded from inc/ by the Makefile.PL,
takes care of checking the the standard install locations for RT, and
setting the installation prefix accordingly. It is part of the package
itself, and not part of my environment. In fact, if it fails to find
your RT.pm, it should be prompting you:

$ perl Makefile.PL
Cannot find the location of RT.pm that defines $RT::LocalPath in:
[snip contents of @INC]
Path to directory containing your RT.pm:

…whereupon providing the path will cause it to carry on, and install
appropriately in your non-standard RT prefix. Hence, if running ‘perl
Makefile.PL’ is failing for you, I’d be quite curious to see how, so we
can fix it.

I suspect you�ve got this in your path because RT is your job. That�s
not true of a normal person. You shouldn�t test in your RT dev
setup.

We test things like this in clean VMs explicitly to prevent that. If it
fails for you, then that is a bug – and one that we certainly should
address.

  • Alex
27

I’ve just verified that all of BPS’ packages that we list on the
Extensions page contain an INSTALLATION section which is up-to-date,
which I believe removes any necessity for common knowledge.
…
Do you think that that, combined with
https://github.com/bestpractical/rt/blob/4.2/installing-extensions/docs/extensions.pod
will sufficiently help new users?

I like that page a lot :slight_smile: I would recommend stating the 4.2 practice first, unless you recommend 4.0… always prefer and mention first the version you recommend.

I think that a link to that new extensions pod added to every module (e.g. in your template) for the Extensions will help significantly, especially in situations where the author didn’t making an INSTALLATION section.

Furthermore, lazy or busy authors might make an INSTALLATION section and link to this document now that it exists :slight_smile:

The Module::Install::RTx machinery, loaded from inc/ by the Makefile.PL,
takes care of checking the the standard install locations for RT, and
setting the installation prefix accordingly. It is part of the package
itself, and not part of my environment. In fact, if it fails to find
your RT.pm, it should be prompting you:

$ perl Makefile.PL
Cannot find the location of RT.pm that defines $RT::LocalPath in:
[snip contents of @INC]
Path to directory containing your RT.pm:

…whereupon providing the path will cause it to carry on, and install
appropriately in your non-standard RT prefix. Hence, if running ‘perl
Makefile.PL’ is failing for you, I’d be quite curious to see how, so we
can fix it.

It failed exactly that way for me, even though we did use the stock directory. On a fresh installation on a fresh node with nothing on it but CentOS 6 with the provided Perl and having followed your instructions for installing all dependencies from CPAN.

We test things like this in clean VMs explicitly to prevent that.

Awesome. My apologies for the assumption. Working in Operations I deal with a lot of developers who forget to do that, and I assumed it in my reply. Sorry.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

28

It failed exactly that way for me, even though we did use the stock
directory. On a fresh installation on a fresh node with nothing on it
but CentOS 6 with the provided Perl and having followed your
instructions for installing all dependencies from CPAN.

Hm – I can’t replicate on a clean CentOS install. And you say that:

perl -I/opt/rt4/lib Makefile.PL

…makes it work? Which module were you trying to install? Can you
show the output of it not working?

  • Alex