Make it easier for devs to be onboarded on this project

[Rudd-O]

Here is my experience trying to test a one-line LESS change:

• develop-egg mockup clone from master into my project
• Follow README,
  • Install Node from distro repos: fine.
  • Install PhantomJS... whut? no package? of course there's no package, this is the JavaScript world, software engineering practices for release are alien in that world.
  • Launch disposable VM and repeat Plone install plus mockup develop-egg plus Node install.
  • Go to the Web site and download mystery meat binary on a disposable VM to see how it goes.
  • Unpack mystery meat binary to homedir of disposable VM.
• now run make bootstrap
• I get this:

[user@plonedev mockup]$ make bootstrap
mkdir -p ./mockup/build
npm link
npm ERR! Linux 4.4.14-11.pvops.qubes.x86_64
npm ERR! argv "/usr/bin/node" "/usr/bin/npm" "link"
npm ERR! node v4.5.0
npm ERR! npm  v2.15.9
npm ERR! path /home/user/optplone/deployments/master/src/mockup
npm ERR! code EACCES
npm ERR! errno -13
npm ERR! syscall symlink

npm ERR! Error: EACCES: permission denied, symlink '/home/user/optplone/deployments/master/src/mockup' -> '/usr/lib/node_modules/mockup'
npm ERR!     at Error (native)
npm ERR!  { [Error: EACCES: permission denied, symlink '/home/user/optplone/deployments/master/src/mockup' -> '/usr/lib/node_modules/mockup']
npm ERR!   errno: -13,
npm ERR!   code: 'EACCES',
npm ERR!   syscall: 'symlink',
npm ERR!   path: '/home/user/optplone/deployments/master/src/mockup',
npm ERR!   dest: '/usr/lib/node_modules/mockup' }
npm ERR! 
npm ERR! Please try running this command again as root/Administrator.

npm ERR! Please include the following file with any support request:
npm ERR!     /home/user/optplone/deployments/master/src/mockup/npm-debug.log

What?

"Please try running this command again as root/Administrator."

HAHAHA. This make target wants to touch my /usr/lib? To compile a single line of LESS?

No thanks, I'm closing the browser window and I'm forgetting about contributing to mockup.

I am glad it occurred to me to launch a disposable VM before I tried any of this, but no one is going to give me back the half an hour I had to waste on it.

:-(

[frapell]

Hello @Rudd-O. Thanks for your feedback. There is a training we created for the Bristol conference, it is 2 years old, but you might find it useful. https://mockup-training.readthedocs.io/en/latest/index.html
Check the "Installation and Bootstrapping" section, in particular https://mockup-training.readthedocs.io/en/latest/install.html#installing-mockup-with-vagrant

Does that look easier? maybe we should link it better from the product README

[Rudd-O]

Yes, it really should be included as part of the documentation. But the problem goes beyond lack of documentation.

Let me put it this way: if I have to spin up a VM just to hack on a single line of LESS, I will not do it. If I have to download and run mystery meat from the Internet (quite literally what the installing-mockup-with-vagrant instructions say they will do) I will not do it. The process that the documentation demands is ridiculously complex, it's insecure, and it takes forever. Under the circumstances, I fully understand why there are very few contributors — I can only wonder how many others simply gave up without telling anyone. Perhaps it's too late to turn around now, but the mockup releng process is an extraordinary imposition and I'm not going to execute it.

FWIW, there is no way that, no matter how well-documented something is, I will let it touch my system files.

[frapell]

@Rudd-O I understand your point, however for "hacking on a single line of LESS", you can simply clone the repo (as you would need to do on any software you want to contribute to), do your modification, and push it to a branch.

Understand that mockup is not a 3 line library. It is a huge framework, you just need other software installed to be able to properly work with it, like bower, npm, and so on...

Notice that the error you posted arises when running npm link, then, if you do a quick google search, you reach this page: https://docs.npmjs.com/getting-started/fixing-npm-permissions

After doing what is suggested in Option 2, make bootstrap works like a charm, and it will not try to access your system.

As you can see, the Vagrant option is provided for making it easier for people to get their hands dirty and hacking into mockup, without the need to be googling around, fixing npm permissions and whatnot...

[Rudd-O]

Change the owner of npm's directories to the name of the current user (your username!):
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

No way I'm doing that. If npm requires that, then npm is bad software built by people who have no clue how to do software.

[frapell]

@Rudd-O If you read carefully, they give you 3 options, you should pick the one you find best for you.

As per NPM, you will need to file a bug with them in order to help them solve their bad design destions.

[davisagli]

@frapell why do we need to do "npm link" though? My understanding is that this adds a link from the global npm packages to mockup, and that doesn't seem like a good thing for us to do by default, unless there's a reason it's necessary.

[frapell]

@davisagli I don't know for sure, maybe @vangheem or @thet know?

[vangheem]

If we can do it without link, that'd be better.

[jcbrand]

FWIW, I only ever use npm link when I have a source checkout somewhere else which I want to link into the current project. Haven't had cause yet to use it for anything else.

[Rudd-O]

Relevant to this report:

https://hackernoon.com/how-it-feels-to-learn-javascript-in-2016-d3a717dd577f?gi=d0ff8513b207

[jcbrand]

Not really relevant since Mockup doesn't require (last I checked) Babel, React, Redux, Flux, SystemJS, webpack or almost any of the other stuff mentioned there.

I do think things could probably be made simpler and the barrier to entry lowered for newbies, however taking your frustrations out on the devs is not going to help much.

[ebrehault]

Hi @Rudd-O ,

Regarding:

Change the owner of npm's directories to the name of the current user (your username!):
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
No way I'm doing that. If npm requires that, then npm is bad software built by people who have no clue how to do software.

That's actually exactly the same problem you have when you install a Python package using easy_install: it will require to be done as sudo.
To avoid that, in Python world, we use virtualenv.
In npm world, there is a similar solution called nvm (see https://github.com/creationix/nvm ).

[jcbrand]

@ebrehault: Or you can just not use the -g option when using npm, then everything is installed relative to your current directory, instead of globally.

[davisagli]

Yeah, you really only need nvm to manage different versions of node itself. Or if the software you're building runs 'npm link' ;-) Since no one seems to remember why we do that, I suggest we try removing it and see if anything breaks.

[ebrehault]

Well, using npm without -g works of course, you know you will not install new packages globally, but you never know if your project will use global packages or not. I think isolation is cleaner.

[Rudd-O]

Yes, this is beginning to sound quite a lot like the article I posted, except it isn't about JS library hell, it's about tooling hell ;-)

[zmijunkie]

I had some success using the following buildout-Snippet:

node.cfg:
[buildout]

parts+=
node

[node]
recipe = gp.recipe.node
npms = less node-sass grunt-cli
scripts = lessc node-sass grunt

then you can put something like the following into
buildout.cfg:

extends =
base.cfg
versions.cfg
node.cfg

and I also changed the Makefile to contain
NPM = /Applications/Plone5/zeocluster/bin/npm

This prevents installing software as a root-User ....

To build "make docs" I had to deactivate

pattern.thememapper.less

in docs.less also but this is another issue.

Regards,
Sascha