Clarify Bower vs psc-package pros/cons for new learners

[JordanMartinez]

Continuing from #199's comment and down, explain the differences of Bower and psc-package in a format that is friendly to new learners.

My learning repo's Dependency Mangers.md file already explains this but...

That page looks good but on reflection I'm not sure it's appropriate to expose all that to someone who is just trying to get something working during their first experience with the language. I'm going to close this PR for now, but feel free to open issues if you want to revive this discussion. Original comment

This is a valid cricitism. Ever since my discussion with thomashoneyman in his RW Halogen App, I've updated the repo's Install Guide.md to present spacchetti and dhall-to-json as optional dependencies that people can later install if they desire. I haven't yet documented/covered Spago, so keep that in mind, too.

Still, the question remains: what needs to be stripped/added from these two files to make things easier for a new learner?

[hdgarrood]

Still, the question remains: what needs to be stripped/added from these two files to make things easier for a new learner?

Sorry, which two files are you referring to?

[JordanMartinez]

My learning repo's Dependency Managers file and its Install Guide file.

[JordanMartinez]

I'm assuming that an integration of both will help satisfy this issue.

[hdgarrood]

I was really only referring to the install guide in this repository; I don't know enough about the structure of your repository to comment on it.

[JordanMartinez]

Oh. I think I misunderstood the nature of the original issue then, likely because it's been so long since someone commented on that PR.

[hdgarrood]

So here's my view at the moment. I've actually changed my mind a little since that comment of mine you quoted.

Having mulled it over for a bit, I think the initial getting started guide should stick with bower + pulp and not mention anything else. The reason for this is that at that stage of learning purescript, I think it's safe to say that the majority of our audience is going to have close to zero interest in the different package management options and what the tradeoffs are. What's most important is that they get some code running with as little effort as possible.

Why bower + pulp as opposed to any other option though? I think @thomashoneyman is absolutely right in that other comment you linked:

On the other hand, with Bower my workflow was simply to install via NPM, init, and then run bower install --save ... everything I needed. I had one conflict -- argonaut-traversals' latest version is incompatible with Halogen v4, so I had to install argonaut-codecs and argonaut-core separately -- but was otherwise pretty seamless. Certainly much less effort than any of the 3 options I mentioned before.

I understand the value of package sets -- I would love for version conflicts to go away forever -- but I just don't think the right mix of curated package sets, extensibility and overrides when needed, and a single, easily-installed-and-used tool exists right now. I can't help but consider Bower + Pulp to be the correct introduction for a beginner even now.

Also, because we've struggled to keep this repo up to date, I think we need to be quite restrictive about what we decide is in scope. So I think I'd actually prefer to say that this repo is not the place for such a discussion (even though it would be useful). I've also just realised that the README does in fact list dependency management options as something which is in scope for this repo; I'd like to remove that.

[JordanMartinez]

What's most important is that they get some code running with as little effort as possible.

It seems that psc-package arose out of issues related to Bower, namely, that it was not always clear which versions of libraries for Bower were compatible with a specific PureScript language release.
What follows is not an argument; just my personal story. When I first started learning PureScript, Bower left me completely confused as to how to fix its problems. I later learned that running rm -rf bower_modules/ helped fix such problems, but as a new learner it was a frustrating experience. Its error messages did not help me know what I should do to fix the problem. After being fed up, I looked up psc-package and found that things worked immediately without any problems. Since there wasn't anything significant that I was doing that required me to define and edit my own package set, this solution worked for a few months until I started doing more advanced things. At that point, I found it worthwhile to use spacchetti and dhall-to-json.

Now actually raising arguments.

Having mulled it over for a bit, I think the initial getting started guide should stick with bower + pulp and not mention anything else.
... Also, because we've struggled to keep this repo up to date, I think we need to be quite restrictive about what we decide is in scope.

I think restricting any mention of dependency managers to only one dependency manager + pulp is wise. You only have so much manpower and time. Moreover, Spago is not as mature or battle-tested as pulp.

Still, I think I could only agree with you in choosing Bower over psc-package if these conditions were met:

• One explains that the biggest issue with Bower is referring to the correct versions of libraries that are compatible with the current PS language version. (Note: I'm not sure how relevant this issue is as it seems to only arise when a language release with breaking changes occurs.) One should include guidelines for how to find the correct version of a library. (If this is as easy as bower --save <package>, then I'm simply misinformed.)
• There should be a warning about the outdated/deprecated libraries used in the Purescript by Example book. This will prevent people from installing the wrong libraries that then lead to incompatibilities later on.
• There should be a "common problems and their easy solutions" that include tips like rm -rf bower_modules/ output/ That should address the remaining pain points for new learners when using Bower.

If the main goal is to make it easy for new learners to just get up and running, then I think one could just as easily explain psc-package without actually explaining what a package set is or all the other things related to it.

I imagine it could be done using these ideas:

• run psc-package init <0.12.1 package set> - Yes, that package set is outdated, but a new learner likely won't care and, most importantly, it will seem correct to them. This is quite similar to bower init
• tell them, 'whenever you need a package, run the psc-package add <package> where the "purescript-" prefix has been removed, followed by psc-package install'. This is similar to bower --save <packages> && bower build
• tell them, 'whenever you want to build a package, use pulp --psc-package build'. This is similar to pulp build
• tell them, 'whenever you want to run a program, use pulp --psc-package run -m Module.Name. AFAIK, Bower has to do the same thing with pulp or an NPM script must define it this way, too.''

Ok. I've made my arguments. Now how can I help you get this fixed, regardless of which dependency manager is used?

[hdgarrood]

One explains that the biggest issue with Bower is referring to the correct versions of libraries that are compatible with the current PS language version. (Note: I'm not sure how relevant this issue is as it seems to only arise when a language release with breaking changes occurs.) One should include guidelines for how to find the correct version of a library. (If this is as easy as bower --save , then I'm simply misinformed.)

I think the rate at which we're doing breaking changes which split the entire ecosystem in the way that 0.11.0 and 0.12.0 did is starting to level off (which is great). I think the severe UX problems caused by Bower are indeed only relevant when these kinds of changes occur, too. As for guidelines about how to find the correct version of a library: comparing recent commit dates and messages to the dates in the compiler release notes gives you a good clue. If that doesn't give you enough information, I would usually take a look at what version of purescript-prelude the library depends on.

There should be a warning about the outdated/deprecated libraries used in the Purescript by Example book. This will prevent people from installing the wrong libraries that then lead to incompatibilities later on.

This is a good point. The issue is where to put it; we do have a notice alongside the link to the book now though, don't we?

There should be a "common problems and their easy solutions" that include tips like rm -rf bower_modules/ output/ That should address the remaining pain points for new learners when using Bower.

Also a good point, but I'm not sure where it would go; I don't think the getting started guide is the right place, really.

Now how can I help you get this fixed, regardless of which dependency manager is used?

Sorry, what is "this" here?

[JordanMartinez]

I think the severe UX problems caused by Bower are indeed only relevant when these kinds of changes occur, too. As for guidelines about how to find the correct version of a library: comparing recent commit dates and messages to the dates in the compiler release notes gives you a good clue. If that doesn't give you enough information, I would usually take a look at what version of purescript-prelude the library depends on.

Good to know!

This is a good point. The issue is where to put it; we do have a notice alongside the link to the book now though, don't we?

I don't think it would need to be clarified anywhere else once purescript/purescript.github.io#134 gets merged.

Also a good point, but I'm not sure where it would go; I don't think the getting started guide is the right place, really.

Hmm... So, it should be included in this repo. You just don't know where, correct?

Sorry, what is "this" here?

Basically, what can I do to update/fix the current documentation related to the things mentioned here?

Looks like we have a few things that can be done:

• Remove dependency managers from the scope of this repo
• Write a small explanation on Bower and "common problems and their solutions" page and put it somewhere in this repo
• Fix the Getting Started guide to use only Bower and Pulp and remove mentions of anything else.

[rlucha]

I think it's worth mentioning that Bower is not that well received in the JS community anymore, it's considered deprecated and (at least it did to me initially) could raise some eyebrows while evaluating the Purescript ecosystem.

I would try to provide other option as the recommended one, at least in the docs. But I'm aware this has been discussed elsewhere, and I don't really want to start bikeshedding.

Just adding that for the getting started docs, it might not provide the best first impression.

[JordanMartinez]

@rlucha Good to know. Still, if hdgarrood and others still think Bower should be used over psc-package, then one way to address JS-background newcomers' concerns is to link to Why the PureScript Community uses Bower

[stiofand]

I dont understand why there must be a discsussion ,as it stands the getting started guide does not work, its not any configuration its because bower has changed.