Re: [rt-users] Documentation for installing extensions
On 12/16/2014 05:15 PM, Jo Rhett wrote: 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
Re: [rt-users] Documentation for installing extensions
On Dec 15, 2014, at 5:07 PM, Alex Vandiver ale...@bestpractical.com wrote: 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 :) 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 :) 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.
Re: [rt-users] Documentation for installing extensions
On 12/12/2014 02:39 AM, Jo Rhett wrote: Linking to the documentation makes sense. Linking to the module docs without any clear installation instructions does not. On Dec 12, 2014, at 10:06 AM, Alex Vandiver ale...@bestpractical.com wrote: Picking a commonly-used module, RT::Extension::SLA, and looking at the documentation we link to: http://search.cpan.org/~alexmv/RT-Extension-SLA-1.03/lib/RT/Extension/SLA.pm#INSTALLATION 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 https://www.bestpractical.com/rt/extensions.html and it links to https://metacpan.org/pod/RT::Extension::SLA 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 (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. 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 (http://perldoc.perl.org/perlmodinstall.html ) 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. 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 https://metacpan.org/pod/RT::Extension::ActivityReports::Billing — error, not found https://metacpan.org/pod/RT::Extension::AddAdminCcsOnQueueChange — no installation instructions https://metacpan.org/pod/RT::Extension::AttributeWalker — no installation instructions https://metacpan.org/pod/RT::Authen::Bitcard — no installation instructions 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 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
Re: [rt-users] Documentation for installing extensions
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
Re: [rt-users] Documentation for installing extensions
On Dec 15, 2014, at 2:20 PM, Alex Vandiver ale...@bestpractical.com wrote: 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.
Re: [rt-users] Documentation for installing extensions
On 12/15/2014 06:20 PM, Jo Rhett wrote: 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
[rt-users] Documentation for installing extensions
On 12/12/2014 02:39 AM, Jo Rhett wrote: On Dec 11, 2014, at 11:26 AM, Alex Vandiver ale...@bestpractical.com wrote: 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: http://search.cpan.org/~alexmv/RT-Extension-SLA-1.03/lib/RT/Extension/SLA.pm#INSTALLATION 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 (http://perldoc.perl.org/perlmodinstall.html ) 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.
