Featured Templates

Change Proposals
#1

Edit. Here are the available templates so far:

Original Post:

Adding official “featured” templates for web frameworks has been discussed in a few places so far (tooling-thread, spago repo). They seem like a good way to achieve the following goals:

  • Make the new-user experience as smooth as possible.
  • Minimize maintenance effort.

What are your thoughts on how to proceed?

Here are some questions to consider:

  • Should templates be featured on purescript.org? If so, what is the policy for adding and removing featured templates?
  • Should templates be versioned?
  • Where should template source code live?
  • What should templates contain?
  • Do any other policies need to be established?

Here’s one proposal:

  • Templates shall be featured on purescript.org.
  • Templates shall either live in the framework’s repo or an official org (purescript-contrib or purescript).
  • Only one template per framework.
  • Templates must be compatible with the latest compiler version. The latest commit before a compiler version bump must be tagged with it’s version.
  • Broken templates shall be demoted.
    • The “Featured” section shall contain a link to “Outdated Frameworks and Templates”.
    • If a user encouters a broken template, they are encouraged to do one or more of the following depending on their ability and generosity:
      • File an issue in the template repo.
      • File a PR in the template repo to fix the template.
      • File a PR in the homepage repo to demote the template.
        • A link to the filed template issue must appear next to the demoted template listing. This ensures that the template maintainers were notified of this change of status, and that other users can quickly see what’s wrong with the template and whether it’s an easy fix.
    • Homepage maintainers should approve these demotion requests as soon as possible to spare frustration for new users.
    • Template maintainers are responsible for filing the PR that reverts the demotion in order to restore their template back to “featured” status, but anyone else is also welcome to help reinstate working templates.

This proposal expands the scope of duties for homepage maintainers, but I hope that having a clear policy minimizes the time and effort required to approve these demote/promote PRs.

Guidelines for template contents is subjective and depends on use case. I think beginners just want to see a minimal example of something interactive appear on screen that updates upon file changes.

To get the ball rolling, here are two opinionated templates that I think would be appropriate for new users.

The guide in each readme is intended to be approachable for users who may not have a strong background in either FP or web development. I’m assuming everyone already knows about the purescript book for learning the core language, but it may be worth linking to that too.

I’m debating whether to just suggest the “global toolchain” approach and making the “local versioned toolchain” content a separate guide. The react template describes both toolchain options, while the halogen template just suggests global tools. What do you think would be best for new users?

Also, please share any other suggestions, such as directory structure and choice of bundler (parcel vs webpack vs other).

3 Likes
#2

Only one template per framework

I think there should be 1 “template repository” for a framework, but the repo may have multiple templates for that library. For example, if I haven’t updated to Halogen 5 yet, I would like to know how to use Halogen 4. So, there should still be a Halogen template for Halogen 4 even if it’s not the latest release. However, I don’t think we need to / should maintain older templates once a newer release has been made. Moreover, when a new release is made, we would copy the template for the previous release into a new folder, update it, and push the changes to the master branch. No releasing is even necessary.

With this concept in mind, we could say "Template repositories shall be featured on purescript.org"

Should templates be versioned?

Yes, but not in the typical way if we use a template repo. I think the version should indicate two things:

  • the last known major version of PS that the template works on (e.g. ps-0.13.x)
  • the version of the library in question that template works on (e.g. halogen-v5.0.0-rc.4)

As an example, here’s the directory structure of a hypothetical repo

ps-0.13.x--halogen-v4.0.0/
ps-0.13.x--halogen-v5.0.0-rc.1/
ps-0.13.x--halogen-v5.0.0-rc.2/
ps-0.13.x--halogen-v5.0.0-rc.3/
# ...
ps-0.13.x--halogen-v5.0.0-rc.6/
ps-0.13.x--halogen-v5.0.0-rc.7/
ps-0.13.x--halogen-v5.0.0/
ps-0.14.x--halogen-v6.0.0-rc.1/

Templates must be compatible with the latest compiler version. The latest commit before a compiler version bump must be tagged with it’s version.

With a template repo approach, we wouldn’t need to worry about this being true.

Where should template source code live?

Templates shall either live in the framework’s repo or an official org (purescript-contrib or purescript).

There are two downside of this approach. First, if a maintainer of the library does not have much time to respond to such PRs, the templates may never be updated. Second, git clone has to download a lot more files that are unnecessary.

It would likely be easier if, assuming we’re using a template repo approach, this repo was maintained by users of the library where there are multiple maintainers, so that it lowers the maintenance burden for everyone. Maintainers of the framework aren’t incentivized to maintain such a template. Users are. However, this creates the issue of decentralization where it’s harder to find the template repo if it’s not stored in the framework’s repo. That can be fixed by linking to the template repo from the main framework’s repo.

#3

I made a typo in my original propsal with suggesting the framework’s repo as a template location. I meant to write framework’s org. For example: purescript-halogen/purescript-halogen-template. I’d also be happy with templates in another org for the decentrialization benefits you described.

I’m concerned that adjacent versioned directories won’t offer the best user experience. What are the instructions for retrieving the latest template? It’s tough to beat the basic clone command that’s available when the latest working template is tracked as master branch.

I think supporting multiple framework versions simultaneously is best tackled with branches. For example with Halogen, we could start with v4 on master and a separate branch for v5. Then let each branch march forward with compiler and framework updates. Once we feel like v5 should be officially featured, we break away a legacy v4 branch from master, and make v5 the new master.

#4

I made a typo in my original proposal with suggesting the framework’s repo as a template location. I meant to write framework’s org . For example: purescript-halogen/purescript-halogen-template.

Oh, ok. That makes sense. The only problem I can think of is that some projects may not want to be under a GitHub organization. Perhaps we could instead have a purescript-templates GitHub organization and libraries will have template repos under that organization? Thoughts?

I’m concerned that adjacent versioned directories won’t offer the best user experience. What are the instructions for retrieving the latest template? It’s tough to beat the basic clone command that’s available when the latest working template is tracked as master branch.

I think supporting multiple framework versions simultaneously is best tackled with branches. For example with Halogen, we could start with v4 on master and a separate branch for v5. Then let each branch march forward with compiler and framework updates. Once we feel like v5 should be officially featured, we break away a legacy v4 branch from master, and make v5 the new master.

True. git clone would be better and the multiple branch idea with the “latest release as master branch” approach is also a better idea.

#5

purescript-templates sounds good to me. Sent you an invite. Let me know if anyone else would like an invite too. Also happy to transfer ownership or go with any other template management strategy that the community prefers. This thread is still new and not everyone has gotten a chance to share their feedback yet.

#6

I’ve accepted the invite. The projects already look pretty great! Nice job!

#7

In my experience, “community-maintained” things tend to go out of date and accumulate questionable workarounds for issues more quickly, which makes them less suitable for a curated set of templates for beginners. I think these templates should remain how they are currently: maintained by the same people who are maintaining the library/framework in question. As one of the people who is responsible for the contents of the purescript.org homepage and the documentation repo (which actually would be my preferred place to have these templates), I’d be much happier linking to templates which are maintained by the library/framework maintainers. Also, I don’t think it’s true that library/framework maintainers aren’t incentivised to keep the templates up to date: they’ve gone to all of the effort of open-sourcing and documenting their library, presumably because they want other people to use it, haven’t they? In any case, I think we really ought to get input from the people who are maintaining the frameworks and libraries which would end up being featured first.

#8

Also, I don’t think it’s true that library/framework maintainers aren’t incentivised to keep the templates up to date: they’ve gone to all of the effort of open-sourcing and documenting their library, presumably because they want other people to use it, haven’t they?

True. Perhaps it would be more accurate to say that the code is the maintainer’s highest priority, which means other things (e.g. documentation, template files, etc.) sometimes take longer to get updated because of their lower priority…?

In my experience, “community-maintained” things tend to go out of date and accumulate questionable workarounds for issues more quickly, which makes them less suitable for a curated set of templates for beginners.

While that can be true, it can also be true that “community-maintained” things can work as a stop-gap situation until the library/framework maintainers can spend the time to provide or update such things. I think what @milesfrain created is pretty good right now and better than nothing. Could it become out-of-date quickly and/or start causing more problems by misleading people? Sure. But I don’t think we’re there yet either.

In any case, I think we really ought to get input from the people who are maintaining the frameworks and libraries which would end up being featured first.

Sounds good to me. Are such people aware of this effort?