Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use more up-to-date learn/documentation links that are more beginner-friendly #13

Closed
JordanMartinez opened this issue Dec 24, 2018 · 13 comments

Comments

@JordanMartinez
Copy link

commented Dec 24, 2018

I think this project may convince some people on the fence about PureScript. However, your guide links to the outdated Book and also to a version of the Halogen guide that's not very beginner-friendly. As such, newcomers who are enthusiastic about this language will likely be demoralized soon thereafter due to having a poor first-experience with the Getting Started part of the language.

In the Prerequisites section, why not update that section with a few additional links:

  • My 'Getting Started' file, which
    • already links to the FP Slack community and Discourse forum (using the correct URL and not the outdated .ml domain name) as a way to get more help
    • shows how to install the language correctly for the 0.12.1 release and not the outdated 0.11.7 release
    • pushes people to use psc-package which "just works" rather than Bower, which often comes with a number of issues where a first-time user does not know how to fix such problems immediately. (When they get more familiar with the language, they can choose whether to use Bower from there.)
  • My 'Dependency Managers' file, which explains why we used Bower in the first place, what its problems were that led to the creation of psc-package, and how spacchetti + dhall makes that easier (I've yet to include the update for spago)
  • My 'Halogen Guide' file, which
    • explains that one needs to checkout the v4.0.0 tag in order to get the Halogen examples to work (not sure whether this is still relevant, but it'll stop the confusion that would otherwise occur by seeing your v4 Halogen code and their v5 Halogen examples
    • links to my beginner-friendly "bottom-up" guide to Halogen where each of the polymorphic types are introduced one at a time
    • links to their original "top-down" guide to Halogen
    • most importantly, links to my Halogen Flowchart which shows how the overall concept works in a visual manner.

And yes, to save you time, I'd be willing to submit a PR if you agree with this idea.

@thomashoneyman

This comment has been minimized.

Copy link
Owner

commented Dec 27, 2018

Hi Jordan! I'm traveling for the holidays and won't be able to get to this until I'm back in town on the 2nd, but I'm in favor of the idea. The guide is hosted on my site so I'll make those updates myself, but it makes sense to point beginners to some good introductory resources from the README here as well.

I'm not sure I want to push new users towards psc-package. I don't use it myself (though I've tried it out in the past) and throwing psc-package, Dhall, Spago, Spacchetti, Nix, etc. all at a new user seems a bit much. I'll have to think about whether or not I would point a new user to those solutions vs. the still official Bower.

So I would at least like to add your Getting Started and Halogen links, and I'll update the book link to Dustin Whitney's fork.

@JordanMartinez

This comment has been minimized.

Copy link
Author

commented Dec 29, 2018

Hi Jordan! I'm traveling for the holidays and won't be able to get to this until I'm back in town on the 2nd, but I'm in favor of the idea. The guide is hosted on my site so I'll make those updates myself, but it makes sense to point beginners to some good introductory resources from the README here as well.

Sounds good! I hope you enjoy your travels!

I'm not sure I want to push new users towards psc-package. I don't use it myself (though I've tried it out in the past) and throwing psc-package, Dhall, Spago, Spacchetti, Nix, etc. all at a new user seems a bit much. I'll have to think about whether or not I would point a new user to those solutions vs. the still official Bower.

That makes sense. On one hand, I think that people already familiar with Javascript may know how to deal with Bower, so getting around its annoying issues might be less troublesome for them and feel overall more familiar than something like psc-package. On the other hand, Bower still produces error messages that are not obvious in how to fix for a new learner. So, I wonder whether psc-package might be better in that regard.

Even if one does not use Dhall, Spago, or Spacchetti (I didn't when I first started learning PureScript), pulp + psc-package still makes the learning process easier. Once one understands the language and experiences its advantages, they can then decide whether they prefer using Bower or Spago or whatever workflow they use.

@JordanMartinez

This comment has been minimized.

Copy link
Author

commented Dec 29, 2018

Just FYI. Here are a few other things I've been working on with this project in mind:

@thomashoneyman

This comment has been minimized.

Copy link
Owner

commented Jan 3, 2019

I have elected to link to your repository, the getting started section, and the Halogen section. Your getting started section already provides advice on psc-package, so I didn't include the dependency managers link. I've also included a warning about Halogen's v4 / v5 differences.

screen shot 2019-01-02 at 8 32 17 pm

@JordanMartinez

This comment has been minimized.

Copy link
Author

commented Jan 4, 2019

Nice!

@thomashoneyman

This comment has been minimized.

Copy link
Owner

commented Jan 4, 2019

@JordanMartinez I spent a little time exploring Spago for this project and I'm still leaning against psc-package for a few reasons:

  1. psc-package alone introduces the concept of 'package sets', requires a binary download, and almost inevitably will require a newcomer to learn how to create their own package set to include a library (like slug, halogen-formless, routing-duplex, formatters, and precise-datetime, among others, in this project) that isn't in it, which seems to sort of defeat the purpose of moving away from Bower if you have to build your whole package set and choose compatible versions yourself anyway.
  2. spacchetti solves having to build your own package set from scratch, but introduces way more complexity at the same time. It requires learning about a new configuration language, Dhall, and the docs make heavy reference to Nix, a big topic in its own right. Plus you need to install even more tooling, including dhall-json, dhall-haskell, and jq, and it seems to involve using Make and shell scripts on top of everything else!
  3. spago, fortunately, reduces these problems significantly. All a beginner would need to learn about is Dhall, package sets, and how to extend the base package set in Dhall, all of which is explainable pretty quickly. But I ran into issues bundling the app with Spago (spago bundle --to dist/app.js doesn't seem to work the same as pulp build --to dist/app.js, but perhaps I missed something), and psc-ide required a bower.json or psc-package file in the project folder to work properly, so I had to install the psc-package executable after all and use it with Spago, which all got confusing for me and would certainly be confusing as a newcomer.

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.

That said, I have high hopes for how PureScript's dependency management / build tooling will work out and I admire the effort that's gone into it so far. I'm excited for the day I switch everything off of Bower.

@JordanMartinez

This comment has been minimized.

Copy link
Author

commented Jan 4, 2019

Well, I appreciate your analysis as you raise some good points! There is definitely truth to this and I think spago and other tools related to psc-package are simply less mature right now mainly because of how little time they have been in development in comparison to Bower.


Still, I'd like to respond to some of your comments:

It requires learning about a new configuration language, Dhall

I've written quite detailed instructions and examples in spacchetti/spago#18 that should remove that requirement. However, that project was still named spacchetti when I submitted that PR. (When did it change?) So, perhaps I'm out of the loop when it comes to this issue / the remaining concerns you made.

the docs make heavy reference to Nix, a big topic in its own right.

This comment doesn't address the heavy doc references to Nix, but I thought it might be worth saying that I'm not currently using Nix. I probably will in the future, but I just haven't read up on it yet. I guess my point here is that one does not have to use the entire 'ecosystem' of psc-package to benefit from it.

Plus you need to install even more tooling, including dhall-json, dhall-haskell, and jq,

I think I installed dhall-to-json by downloading and using their binary. I don't think I needed to install the other dependencies. Granted, not everyone will want to take this approach.

it seems to involve using Make and shell scripts on top of everything else!

I don't believe I have encountered these issues yet. However, my projects are rather simple, so a production build or a company environment might reveal that more. Or, this might be another situation where I'm simply out of the loop.

I ran into issues bundling the app with Spago (spago bundle --to dist/app.js doesn't seem to work the same as pulp build --to dist/app.js, but perhaps I missed something), and psc-ide required a bower.json or psc-package file in the project folder to work properly, so I had to install the psc-package executable after all and use it with Spago, which all got confusing for me and would certainly be confusing as a newcomer.

I think this is a clear case where Spago is just still immature.

There's one other issue I can add to your list of concerns: spacchetti and spago don't currently work for Windows users.


Having said all that, if you link to my repo, it will likely encourage people to use psc-package. My project solely uses pulp + psc-package and only in certain later parts does it use spacchetti. Each folder has a "copy-and-paste"-able command that runs things for Mac/Linux. I don't have the same such commands for Bower. Moreover, once one installs Purescript, pulp, psc-package, and spacchetti, my project has for-each-folder--install-and-build-deps.sh, which sets up the rest of the project for them.

I'd like to cover Bower more in my project and this raises the idea of including such commands for Bower so that people can learn regardless of which dependency manager they use. For example, it would help to document the common solutions to various Bower problems (rm -rf bower_modules/ output/ && bower install && pulp build to get rid of cache problems). I'll need to open an issue for that.

Regardless of our discussion, I'm updating my "Getting Started" file to show spacchetti and dhall-to-json as optional but recommended things to install. For those who don't want to install them immediately, they can continue to learn without bottlenecks or slowdowns.

@thomashoneyman

This comment has been minimized.

Copy link
Owner

commented Jan 4, 2019

By Spacchetti I specifically mean https://github.com/spacchetti/spacchetti, as opposed to Spago (https://github.com/spacchetti/spago). Your notes about not running into these issues I believe are because you are referring to Spago, which now uses Spacchetti under the hood.

I'm not sure I'd suggest psc-package or spacchetti on their own, but Spago does make a pretty compelling alternative to Pulp + Bower and doesn't require installing anything except for Spago via NPM -- perfectly acceptable.

Unfortunately the editor support is still missing, but when that's resolved, you won't need to install and use psc-package (and maintain a separate psc-package file) and can stick with just Spago.

Once editor support + library support is in place, I'd prefer to switch to Spago.

@JordanMartinez

This comment has been minimized.

Copy link
Author

commented Jan 8, 2019

Sorry for the late response.

Mm... ok.

On another note, I wonder whether my project installation instructions are still correct then. Looks like it's time to implement CI for my project to account for these issues.

@f-f

This comment has been minimized.

Copy link

commented Apr 29, 2019

I just stumbled on this and it was a great read, thanks @JordanMartinez and @thomashoneyman for the good discussion 🙂

You raise great points and I'll checkout what's up with spago bundle (I believe spacchetti/spago#175 will solve it), but please feel free to tag me whenever you think you have an issue with Spago (either a bug or a usability issue), as I might be totally unaware of it like in this case 😄

@SebastianCallh

This comment has been minimized.

Copy link

commented Aug 18, 2019

Hi,

I tried to run psc-ide through Emacs after cloning this project but I get Searching for program: No such file or directory, spago when trying to start the server. Does

and psc-ide required a bower.json or psc-package file in the project folder to work properly, so I had to install the psc-package executable after all and use it with Spago, which all got confusing for me and would certainly be confusing as a newcomer.

refer to the same issue? If so, would be super happy if someone could explain how this was resolved!

@thomashoneyman

This comment has been minimized.

Copy link
Owner

commented Aug 18, 2019

I don’t use Emacs, but Spago should work there with psc-ide; perhaps these issues will help?

This PR added Spago support to purescript-emacs:
purescript-emacs/psc-ide-emacs#164

This issue tracked missing support for emacs on the Spago project:
spacchetti/spago#64

Both are resolved, so I presume it works and that there’s some setting I’m not aware of — you might want to look through Spago issues for that.

But the limitation you quoted is no longer the case, and I wholeheartedly support Spago at this point.

@SebastianCallh

This comment has been minimized.

Copy link

commented Aug 19, 2019

Thank you for the links! I'll have a look

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.