PS future - new features vs documentation & spec

[chexxor]

Continuing the discussion from The Principles of PureScript:

The Principles of PureScript

I think it is almost essential that we stop adding new features now, and let documentation catch up, including a language spec.

I’ve been thinking about that idea, and I’m wondering if it’s fair to enough PS users.

Consider how we’d communicate this policy to people who want to give the PS language new feature.

“Until PS gets X amount of documentation we can’t accept your PR. So, if you want to lower the time until we merge your PR, you can add lots of documentation. Otherwise, you can maintain a fork of the PureScript compiler.”

Forcing a fork is only slightly concerning right now. More importantly, I think there are several people who really want the PureScript language to be awesome, and it feels a little unfair to put a ceiling on their contributions.

Even more unfair to those people is that documentation and spec-writing is a huge project with no clear end date. What’s more, it feels like documentation and language development can be developed concurrently.

If we want to slow language development to improve docs, I’d guess that a more effective means of accomplishing the goal of great documentation and a solid spec is to put a small documentation tax on language development. That is, before a PR is merged into the purescript/purescript repo, the author must improve docs somewhere. It’s just an idea, and I’m sure it’d be more difficult to implement than it is to describe it.

[paf31]

I’ve been thinking about that idea, and I’m wondering if it’s fair to enough PS users.

I don’t see how fairness comes into this when the product is free and open source. Maintaining the compiler is a massive amount of work. What seems simple to one contributor actually represents a possible long term burden of maintenance on the project owners. Every breaking change has to be documented which involves more work. Then the book has to be updated, and Try PS, and Pursuit, and those things have to be hosted and maintained. So yes, I would much rather such efforts exist in forks.

More importantly, I think there are several people who really want the PureScript language to be awesome, and it feels a little unfair to put a ceiling on their contributions.

Asking a user to fork puts less of a ceiling on contributions because they are able to work on exactly the changes they want. I also think the language is already awesome, and I use it every day.

Even more unfair to those people is that documentation and spec-writing is a huge project with no clear end date.

Of course it has an end date, it ends when the stable language is fully specified.

The attitude which encourages adding every shiny feature and seeing what works is no longer appealing to me, and a big part of why I don’t enjoy the idea of being a maintainer of the compiler again.

As a user, the most unfair thing to me would be to never know when the project will reach stability. If we want to talk about fairness to users then we should try to make the project roadmap clearer and aim for stability.

[zyla]

Of course it has an end date, it ends when the stable language is fully specified.

What’s your definition of “fully specified”?

[paf31]

Obviously, writing documentation is an ongoing process. We would continue to improve it, but at least we’d be converging on something.

[zyla]

Forcing a fork is only slightly concerning right now

I like the idea of using a fork of the compiler. Would be nice if we had better tooling for this though. For example, stack makes it almost trivial to switch the compiler per-project like any other dependency - because everything is specified in stack.yaml. Does something like that exist for PureScript?

[paf31]

It is much, much easier to use a fork of PureScript than a fork of GHC, so additional tooling is not really needed. Simply put the replacement executable on your PATH.

[naglalakk]

Hi I want to share my experience as someone migrating to Purescript. I absolutely love the language but I think your tooling is lacking a lot. Which I think is a pity and I don’t think it needs to be that way.

My biggest issue is package management. Your default way is using bower. I understand it from the dependency management viewpoint. However even that does not work very well. You’ve probably all had to resolve massive bower conflicts and so you probably know that this is a process that is very painful and not intuitive at all. So then we move onto your own package manager psc-package.
The psc-package is not mentioned anywhere in the official docs. Do you want people to migrate to it or not? I understand why it’s not mentioned though because at the moment it’s a total pain to use. The default package set only contains the core libraries so anytime you want to use any other library, say Purescript-aff which is widely used, you need to create your own custom set. Custom sets are very time consuming to make since you need to constantly push and tag new versions to a git repository and then check in your project if your set is valid or not.
You’re right, Purescript itself does not need any new features for a year. However I would focus solely on this package manager for now.

This brings me to another point which is that when breaking changes are pushed it seems that neither bower or psc-package seem to be able to resolve it correctly and so they just install whatever is new which is why half of my libraries now tell me they cannot parse some if else clause. This is very discouraging for beginners.

I know I’m being fairly negative here but you have to understand that this is how it looks for a lot of people coming to the language and some of them, including myself want to be able to use Purescript for production. However until these things are fixed I don’t see how I can successfully do that. Half of my time with Purescript is spent figuring out ways around things that don’t work or are not explained well enough.

[hdgarrood]

Don’t worry, I and others are well aware of how many people are struggling with dependency management issues like the ones you’ve described. I think a large part of the reason these issues haven’t been addressed yet is that comprehensively addressing all this is a massive undertaking, and for now there are plenty of other things which appear to be lower hanging fruit in terms of effort required to address them versus payoff. I am intending to investigate what might be possible to mitigate these issues soon, but I am not going to make any promises.

I know I’m being fairly negative here but you have to understand that this is how it looks for a lot of people coming to the language and some of them, including myself want to be able to use Purescript for production. However until these things are fixed I don’t see how I can successfully do that.

Sure, this is entirely understandable. This is why I am careful not to describe PureScript as “production ready”, because that phrase means very different things to different people. I know of plenty of teams who are happily using PureScript in production, but (for now) you do sometimes have to be prepared to get your hands dirty and eg do a bit of digging to understand why you’re getting a particular error; if that is not something your team is willing to do, or if that doesn’t seem like a good trade off, then PureScript might not be a good fit at this particular stage in its development.

Just to be absolutely clear, there are plenty of people in the community who agree that this is worth addressing, and I do believe that we will find a way to stop this sort of thing from happening eventually; I think it is just a case of resources.

[naglalakk]

Thank you for your answer hdgarrood. It’s good to hear that this is not just me being a total beginner. I would like to add that I’ve notice some people in the Purescript community are contributing so much to multiple libraries. That is really good work and I do understand that this is hard work and the community is very active even if it’s not the biggest. I hope that one day I can contribute as well. I just wanted to explain my sort of first weeks and how they were going from a viewpoint of a beginner and what could go better from that experience. Overall I’m really positive towards this language. I’ve really enjoyed writing in it and I want to continue to do so.

[paulyoung]

My biggest issue is package management. Your default way is using bower. I understand it from the dependency management viewpoint. However even that does not work very well. You’ve probably all had to resolve massive bower conflicts and so you probably know that this is a process that is very painful and not intuitive at all

I have to say that the only issue I’ve ever had with bower is it being rate-limited by GitHub on CI.

I think the problems described here might be addressed by adding a couple of points to some documentation somewhere.

Namely:

1. Specify a version range in bower.json instead of using bower install --save (at least around new releases of the compiler)
2. Try removing the bower_components directory and running bower install again if you run into version conflicts.