The Future of the PureScript Book

Thanks for starting the discussion @dtwhitney!

I believe it would be nice to have a book along the lines of “The Rust Programming Language” book. A book that is the de facto book when picking up the language. Phil’s book is already this. It would be nice to have it under the PureScript organization such that it is easy to contribute to and hopefully keep up to date.

As I learn the language I’m willing to make some contributions here and there but I don’t think I’m able to lead the effort.

1 Like

Yeah probably better to start another topic/discussion, but it would be nice to have Phil update the book :slight_smile:

I thought I’d bring this up because it does somewhat relate. I think the larger question here is “What are the main learning resources the community will provide, so that new learners can get a solid foundation quickly?” Officially, it’s the PureScript book. However, I’ve also written my purescript reference learning repository.

Thus, how should these two resources relate, if any?

Currently, they are separate projects. Should things continue as that? Or should there be more integration between the two? The resources take two different approaches to try to achieve similar goals, so I’m not sure that they should. However, I thought I’d bring it up for discussion.

1 Like

To be fair, I’m not sure what 1.0 would give you if it doesn’t also apply to the ecosystem. A large part of updating the book was Effect, and I also think React changes.

2 Likes

I didn’t know about your repo. It’d definitely be nice to have it included as a learning resource. Where are these decisions typically made? Github issues?

IMHO 1.0 would be great even if it were merely symbolic. It’s a signal that PureScript is working and usable in production. I realize I’ve 0 contributions to the PS compiler, so I don’t really get a voice in that decision, but as someone who has taken the “risk” of using PureScript, it would be nice to see the pool of adopters grow.

1 Like

Oh, I’m actually surprised to hear that. It’s already mentioned in the documentation repo’s Learning Resource’s third bullet point. I’ve also made announcements regarding it at various times on this site, too.

As for decisions, I have no idea. I opened an issue for adding my repo in the documentation repo. I then opened a PR for it.

Actually, Harry left a comment that is worth quoting below:

Sorry for the delay in responding. The reason it’s taken a while is that before linking to things, I’d really want to make sure we’ve had a good look at them first, and your repo has a decent amount of stuff in it.

I’m happy to put links to unofficial documentation resources in here, but I’d prefer that we clearly separated them from any official documentation and added a note to clarify that they are unofficial.

Content from other people’s projects can be referenced by contributors to this project, when and if that happens. ~Alex

I’m not super keen on this, as it happens; we have enough trouble keeping links between official resources alive as it is, and any references to unofficial resources are even more likely to change under us.

On the topic of 1.0, I don’t think it’s essential, but having seen things from the “outside” for a while now, I do think having some sort of public roadmap is essential. It’s next to impossible to know what to expect in terms of changes without being deeply involved in the community and I expect that reduces motivation for people to work on tooling and other contributions to the ecosystem. Just like I’m far less motivated to work on the book because it will inevitably keep getting out of date.

4 Likes

Yeah I was previously reluctant about writing a roadmap because of the work required to maintain it and keep it accurate, but I do agree that it’s probably necessary if we want people to keep contributing. FWIW I do still like the idea of declaring a 1.0 and committing to not breaking anything for a certain period of time or something like that, but there are a few fairly large things I think we need to sort out first, like ES modules and the packaging situation.

2 Likes

Thanks for the reply. Just to illustrate the use for a roadmap though, I think having a place to debate and understand the need for ES module support or a compiler-supported packaging solution would be useful. For example, as a user, I know Spago exists but I have no idea what the 1.0 plans for a packaging solution would involve, or why.

I think having a place to debate and understand the need for ES module support or a compiler-supported packaging solution would be useful.

FWIW, there are long-standing issues for both of these on the compiler issue tracker with stated motivations and debate. I’m not sure that a separate roadmap would be a better place. I could see having more milestones though.

I’m with Phil on this - it’s not so much for the benefit of the organizers, but mostly to promote the language itself. I’d love to see more people using PureScript, as I’m sure all of you would too, so I think Phil’s suggestion is good.

I’m with Phil on this - it’s not so much for the benefit of the organizers, but mostly to promote the language itself

Promote it in what way?

My point is to have a list of the things which are prioritized so I’d know which ones to go look at. There’s no way to know what the “path to 1.0” looks like right now, if it exists at all, there is just the Approved milestone.

I think there is still a sense out there that since Phil isn’t working on it anymore, that not much is done. Having a visible roadmap would give outsiders some perspective that there is active development and a plan, rather than just maintenance.

1 Like

I’ve created this thread to discuss making milestones and important features more visible. New Compiler Milestones

I’d like to invite anyone who is interested to help with a code review on updating the original chapter 8 code to work with react-basic-hooks.

I have a working version, but am unsure if this is the best coding style, and would like to get this straightened-out before including code snippets in the chapter text.

Links:

3 Likes

AWESOME! I’ll provide some feedback this weekend

It appears that everyone is in agreement that the book should be moved to purescript-contrib. What are the next steps for that? This may be a good task to combine with the library deprecation effort.

Yea, I’m happy to move the book to -contrib!

As far as I’m aware that simply involves @dtwhitney making any last minute updates, ensuring we credit the work appropriately, and then on GitHub request transferring ownership to the -contrib organization (I can accept the request).

2 Likes