The state of things

[paf31]

It’s been 7 months since I announced that I would be taking a long break from PureScript development, and I’d like to take some time to provide an update on what I’ve been up to, and make some comments on the state of things as I see them as a PureScript user.

What I’ve been up to

I had been spending less and less time on PureScript for several months before I decided to finally call it quits. I’m not entirely sure why, but I found myself losing interest in leading the development of the language. In retrospect, I think it’s fair to say that I was quite thoroughly burned out from trying to balance open source work and real life. Since December, I’ve been concentrating on doing far less open source work, and only on things which I find enjoyable. I still love to use PureScript, and I’ve been working to increase PureScript adoption at work, which I’m happy to say is going very well. I’ve also been using PureScript for a few low-priority personal projects like Purview, trying to write more blog posts and give more talks, building the LA PureScript group, and supervising Arthur’s fantastic thesis on comonadic UIs in PureScript. Overall, I’m still sorry that my transition out was so abrupt, but I’m glad that I decided to take the break.

Some observations

Let me say first - I am writing this in my capacity as a PureScript user, not a former PureScript contributor, and not as the creator of the language. I would like to share some thoughts I’ve had regarding the future development of the language, and some constructive suggestions for action. This is not meant to be a criticism.

1. The 0.12 release was a massive achievement, not to be underestimated. I’ve been using 0.12 for personal projects, and at work, and it has been wonderfully stable and fast. We’re making good use of lots of new features (I love the new Lacks constraints, and I have to admit, Effect is the right choice). Generally, I think some of the minor library updates like renaming certain things were a bit unnecessary and confusing, but overall, the upgrades went very well.
2. Unfortunately, unlike the release of the compiler itself was not synchronized with releases in the rest of the ecosystem. The website and Pulp were updated after the compiler release, Try PureScript and Pursuit are yet to be updated. Now, I suppose I am technically responsible for Try PureScript and Pursuit (at least, I need to be the one to deploy them right now), but in any case, I think there needs to be some synchronization around the release of a major compiler update.
3. We seem to have developed something of a documentation problem. Even now, the documentation repository is only partially updated for the 0.12 release, and generally it is quite unstructured and lacks a single vision for what good documentation should look like.
4. Also regarding documentation, I still need to update the book. It seems to take longer with each major compiler update, and honestly, I’m not motivated to update it again without some sort of guarantee that I won’t have to redo everything again in a few months. I will inevitably get around to it, because I feel like I should and it’s already eating at me that I haven’t yet, but this seems like a bigger problem. I would like to write a lot more documentation for PureScript, but I hate the idea that it will become out of date quickly, and that I will have yet more projects to update in future. So without some sort of plan for the future of the language, and some idea of what changes are coming (and just as importantly, which aren’t), I’m not likely to write anything, and I wouldn’t be surprised if others avoided writing for the same reason.
5. The community seems to be getting fragmented and there is no long-term record of discussions outside of GitHub issues. We now have IRC, Slack, Gitter and Discourse. I personally don’t tend to look at Slack very much any more, because I find it hard to track conversations, I don’t like that there’s no logging, and the tone there has been a little… unpleasant, from time to time. I hang out in IRC, but there are very few users there. I do like Discourse, and I hope that we can move more discussions here.

Some recommendations

I’ll use “we” here to refer to the community generally.

1. I think we need to come to the difficult realization that everyone is already stretched thin, and that we need to try to do less in order to do things well. If Try PureScript takes too much time to update, then we should not advertise it on the website. If the documentation cannot be updated in sync with the compiler, then it should also be unlinked from the website, and marked as stale. I have said before that I think we should avoid new features and concentrate on bug fixes and documentation. Now that 0.12 is out, I think it is a great time to prune any inessential feature requests from the issue tracker and make a plan to concentrate on these things instead.
2. There needs to be a plan for the future, and that plan needs to be documented. I would like to start working on a specification for the language, something which I consider essential for documentation purposes, but it doesn’t make sense to start documenting a language when there is no plan in place for the next milestone. For me, the ideal situation would be this: we agree that the compiler is not perfect as it exists now, but that its flaws are relatively minor and easily documented; we make a plan to release 1.0 (or 13.0?) by fixing any bugs we cannot document, and engineering things as best as possible in order to facilitate feature additions we anticipate; then we write a specification for this language, and commit to a stable release window, ideally as long as possible. When I’ve brought this idea up in the past, it’s met some opposition, but I think this would be massively beneficial and enable the creation of lots of stable documentation.

That’s about all I’ve got to say. Thanks for listening, and what do you think of these suggestions?

[paulyoung]

The community seems to be getting fragmented and there is no long-term record of discussions outside of GitHub issues. We now have IRC, Slack, Gitter and Discourse.

There’s also the Google group

I prefer Discourse for things that don’t warrant a GitHub issue. I find that Slack can sometimes be good for getting an immediate response and for transient things.

[cmdv]

Firstly, thanks for all the involvement in PureScript it’s been greatly appreciated and speaking personally it’s taken my development career into a entirely new interesting direction

Glad you took the decision to step down vs totally burning out to the point of no return, even to development!

Maybe a solution to getting better documentation would be to have some live on the main compiler repo as issues with the new contributor label and if others find they need more docs in popular libraries to open an issue with similar label on library repo and have a section on here with all of these accumulated. They wouldn’t strictly have to be just docs anything beginner friendly. But writing Docs is a good way to get into a language.

Hopefully more new/doc contributors could results in further investigation from those contributors into more complex issues and therefore spreading out the workload for what is still currently a small set of people. (Bless their cotton socks )

[kika]

Phil, first of all, thanks a lot for the language and your contributions.

As a pure user of the language I’m also quite frustrated with rapid backwards incompatible changes to the language and standard “library”. It hinders my ability to introduce it more widely into production because once the compiler changes it’s me who is solely responsible to “make it work again, forchristsakes!”. I think the time has come to have a definition of “version 1.0” and work towards it.

If you take volunteers I can maintain Pursuit. I’m infrastructure engineer/manager by day. It will take me some time to figure my way around “server side Haskell” but I’ve seen harder things in my life. Let me know if I can help.

As for the communication channels, the Slack is great for asking a stupid question if you got stuck in the middle of something simple. The lack of logging sucks big time and I remember myself reading IRC logs for hours with great results.

[garyb]

Unfortunately, unlike the release of the compiler itself was not synchronized with releases in the rest of the ecosystem. The website and Pulp were updated after the compiler release, Try PureScript and Pursuit are yet to be updated. Now, I suppose I am technically responsible for Try PureScript and Pursuit (at least, I need to be the one to deploy them right now), but in any case, I think there needs to be some synchronization around the release of a major compiler update.

Yeah definitely, there was another thread talking about some of that: How do we avoid ecosystem incoherence in the future? At least this time, for I think the first time, we actually got the core library releases synced with the compiler release.

I guess regarding Try Purescript / Pursuit there need to be more of us who are aware of how to update it / how they work, as I think it’s just you and Harry at the moment.

We seem to have developed something of a documentation problem.

I think that started with the initial release and has been true ever since. I can’t think of a time in PS’s history where we had docs resources that were good and up to date (book aside). I agree it’s a problem, I just don’t think characterising it as something new or that has gotten worse is true - perhaps it’s just become more apparent now you’re primarily a user?

Also regarding documentation, I still need to update the book. It seems to take longer with each major compiler update, and honestly, I’m not motivated to update it again without some sort of guarantee that I won’t have to redo everything again in a few months. I will inevitably get around to it, because I feel like I should and it’s already eating at me that I haven’t yet, but this seems like a bigger problem. I would like to write a lot more documentation for PureScript, but I hate the idea that it will become out of date quickly, and that I will have yet more projects to update in future. So without some sort of plan for the future of the language, and some idea of what changes are coming (and just as importantly, which aren’t), I’m not likely to write anything, and I wouldn’t be surprised if others avoided writing for the same reason.

Just out of curiosity, I looked back at the releases as to how long the gap between them was and how breaking they were, for as long as I’ve been involved with the project:

PureScript version history

So I’m not sure the perception that we’re breaking things constantly is entirely true, especially with the last release since it was by far the longest period of non-breaking. Also, the breaking changes that weren’t library related in 0.12 were relatively minor compared with changing => in 0.11, etc.

Not to discount your feelings on the matter! Just pointing out PS is definitely slowing down into a more stable state anyway. Especially after 0.12, the Effect changes and some of the other library changes that went out, there’s very little that I can think of that I’d like to do differently in the core libraries now. In fact there are only two changes I can think of, one would require polykinds and the other would require quantified constraints, so they’re probably not going to be any time soon.

The community seems to be getting fragmented and there is no long-term record of discussions outside of GitHub issues. We now have IRC, Slack, Gitter and Discourse. I personally don’t tend to look at Slack very much any more, because I find it hard to track conversations, I don’t like that there’s no logging, and the tone there has been a little… unpleasant, from time to time. I hang out in IRC, but there are very few users there. I do like Discourse, and I hope that we can move more discussions here.

Yeah, this is definitely unfortunate. I think having the Discourse is valuable for sure, as hopefully we can encourage non-transient discussions that aren’t issue specific to move here instead.

There’s also the Google Group, but I can’t remember the last time I looked at that.

I use Slack as even though there’s no persistent logging it has enough of a backlog that I can actually catch up with the last day or so, which is about all I ever did with IRCBrowse too. That and you can reply to people who are offline.

I don’t use Gitter at all or the IRC channel anymore.

Perhaps we should cull the list to just point people to Discourse and GH issues for “real” discussions, Slack (and maybe IRC) for quick questions / transient discussions, and leave it at that.

… When I’ve brought this idea up in the past, it’s met some opposition, but I think this would be massively beneficial and enable the creation of lots of stable documentation.

I’m less hostile to this idea than I once was, but mainly because I think the “missing” features that I feel are the greatest causes of friction for me can be added without breaking old code. I guess it depends by what we mean by committing to a long term stable release, if we’re talking about not grossly breaking things, I’d say we’re at a point where that’d be no impediment at all, but if we’re talking about an entire feature freeze then I’m still reluctant.

[paf31]

I think that started with the initial release and has been true ever since. I can’t think of a time in PS’s history where we had docs resources that were good and up to date (book aside). I agree it’s a problem, I just don’t think characterising it as something new or that has gotten worse is true - perhaps it’s just become more apparent now you’re primarily a user?

Yes, sorry, I meant to say this in my original post. This isn’t necessarily a new thing, but it’s something I’m more aware of now, and I think the language is at a good point where we could focus a lot more on documentation if we decided to commit to a stable language specification.

[JordanMartinez]

@paf31 said:

• We seem to have developed something of a documentation problem. Even now, the documentation repository is only partially updated for the 0.12 release, and generally it is quite unstructured and lacks a single vision for what good documentation should look like.

This issue has been somewhat resolved in my learning repo, which I announced here:

Purescript - Jordans Reference

The Purescript by Example book is somewhat outdated due to using to 0.11.x and the breaking changes introduced in 0.12.0. Moreover, while the Slack chatroom provides immediate help, many likely want a better, comprehensive, learner-friendly, ‘go-to’ reference for learning Purescript. Since I’m still learning Purescript, I decided to use the Feynman technique to learn it by teaching it to others. Here is the following link to my repo: It covers: Getting Started Installing Purescript for …

To summarize its benefits over the current documentation repo:

• My repo uses compileable code written in meta-language to document syntax; if it compiles, the syntax is correct. A new Purescript release will result in fixable compiler errors, making it easier to maintain the docs.
• I synthesized a number of the docs’ guides into my repo and strived to explain things better (not all are done yet, but those that have were updated to 0.12.0).
• Some things in the docs repo are still accurate (e.g. ecosystem) and those that aren’t (e.g. tool support) have been documented in my repo (see Build Tools)
• Errors: a number of these are undocumented in the docs repo. Unfortunately, I can’t figure these out unless I get really lucky and write code that fails to compile . If one of the core contributors worked on the errors part, the documentation would be largely up-to-date.

• Also regarding documentation, I still need to update the book. It seems to take longer with each major compiler update, and honestly, I’m not motivated to update it again without some sort of guarantee that I won’t have to redo everything again in a few months. I will inevitably get around to it, because I feel like I should and it’s already eating at me that I haven’t yet, but this seems like a bigger problem. I would like to write a lot more documentation for PureScript, but I hate the idea that it will become out of date quickly, and that I will have yet more projects to update in future. So without some sort of plan for the future of the language, and some idea of what changes are coming (and just as importantly, which aren’t), I’m not likely to write anything, and I wouldn’t be surprised if others avoided writing for the same reason.

I’m currently learning Purescript, and the best way to learn something new is to teach it to others (the Feynmann Technique). So, I have the necessary motivation to write a resource that may become outdated quickly.

Moreover, my repo has the following benefits:

• The goal of my repo’s Hello World folder is to equip a new learner with everything they need to know to design, write, test, and benchmark a simple application without introducing/using any unneeded FP concepts or libraries to reduce “noise” (still a WIP). This is largely what Purescript by Example does, just in a different approach. In my opinion, the advantage of mine is that it is more newbie-friendly. I’ve only recently learned FP concepts, so I still remember what did not make sense the first time I learned something.
• The “Design Patterns” folder (WIP) documents the various problems one will encounter in FP programming and the solutions one can employ to deal with them. It’ll help new learners write better code as well as recognize when these patterns are being used in libraries. In short, it is not specifically bound to a compiler version. Many of these ideas will continue to exist whether the compiler changes or not.
• PS-by-Example teaches using a book approach, which separates the code from the explanation. My repo combines both into a project that is designed to be git cloned via GitHub and is licensed under CC BY-NC-SA 4.0. Any issues can be tracked in the project’s issue tracker.

My other two cents:

• If maintaining TryPurescript is too costly to do, either train others to maintain it or take it down. People who try it out and then install Purescript 0.12.0 will encounter difficulties due to Eff -> Effect and leave thinking the language is too difficult. Thus, the website may hurt the language’s reputation more than help it. Furthermore, if the goal is to continue developing the language, this steals precious time away from core contributors.
• Please include my learning repo on the language’s website in addition to Purescript by Example. Even if it’s not yet finished, it provides a much smoother “Getting Started” experience and is updated for 0.12.0.

Lastly, thank you for designing and writing this language!

[cmdv]

I had the miss fortune of making a free PS course that uses TryPureScript a couple of months before 0.12 was due and some of it’s changes think broke a couple of my lessons due to the way I taught them. Need to check it out properly just not had the motivation! I like it as a tool but can totally understand the hassle of keeping it and attached material up to date.

[JordanMartinez]

Wow! That is unfortunate!

[cmdv]

It’s all good, it’s just a timing thing