SAFE v2 - Roadmap and request for feedback #348
Comments
|
Hello, I think the global idea for the v2 goes in the right direction. Here is my thought I wrote when reading the Roadmap. Simplify the templateIn the template section, I think you should include the most common polyfills by default like But people keep reporting a bug about Speaking about Fetch I don't see a section about Fetch support in the template only about Fable.Remoting. I think it can make sense to support Fetch via Thoth.Fetch but I am not sure. About the features removed from the template I think, the most important thing is to make sure people have the required resources to extends them to their needs. For example, I want to add Fable.Remothing or Heroku to my project I should be able to have a tutorial that I can follow step by step from the minimal template. With this kind of resource, people should be able to the knowledge to their growing application I think. More LibrariesI don't think we can suppose which library people will want to use and it can result in a lot of work for few benefits. I would make it a low priority tasks to be worked on when the rest has been done. |
|
Regarding Fetch - good point. I suspect it's not necessary if we're using Fable.Remoting for the "full" template, but possibly we should keep it for the "minimal" one. If nothing else, we definitely need to have it documented on the site because it's a very popular option. |
|
I'm curious if SAFE consumers would be interested in a scale-out story. |
|
I often find myself removing Fake and simplifying the webpack config so the plan sounds good. I btw don't see Feliz here. Is that deliberate and out of the question for v2? Personally I think Feliz is a turning point, i.e if you don't support it you might get obsolete quickly. |
|
I think it would be nice to have a dedicated That may just be adding more maintenance effort, so I understand if this is not seen as feasible. However, I thought it worth throwing out there. This could also be done through templates made available directly through the The issue I have with just modifying the template is that SAFE is supporting an ecosystem of multiple, independent projects. It should either be strongly opinionated (as proposed above) or provide an infrastructure to support those projects in many different ways. The notes above about SignalR backplanes and Feliz are great examples of how a supporting infrastructure may well help facilitate future evolution while retaining the notion of SAFE as an ecosystem and style for solving problems. |
|
@dbrattli Zaid has effectively joined the team and Maxime and him and going through the process of evaluating both options. At the moment we're sticking with Fable.React but if that needs to change, there's no problem in doing that. Side note: I'm personally very aware of the possible costs of bifurcating the dev experience and whilst for a simpler story I would prefer to simply have one choice, having the diversity is also a good thing and brings different options to the table. |
|
@et1975 Could you raise a separate issue for this? We've done some work on SignalR and, yes, if you're doing push notifications the backplane provides a possibility for scale out (if you're doing conventional SPA / server side apps, no websockets, scale out is inherently available). |
|
@panesofglass this is where we started last year. @theimowski spent a lot of effort into creating a prototype for some kind of modular system. But, as you say, there's the cost of not only building but also maintaining it. And, looking at the other side - building a specific tool is another layer of abstraction / magic on top of what is ultimately a dotnet core app and a webpack JS app. My view is short term (v2 launch) will be about simplifying the template and replacing the current template options with excellent, simple to read documentation and samples - whether that's support for docker or a different communication mechanism etc. In the medium-longer term, I would like to, yes, build a dotnet tool that could automate that process, by having a collection of "extensions" or "modules" for a SAFE app that the tool would download, involving file copy / rename etc. operations. |
|
@pimbrouwers this is not about Saturn. This is SAFE stack (the whole thing) where Saturn is only one component. If you only want to use saturn then you can do that. I think it's described on Saturn's docs. |
|
You argued about removing Fable and Elmish. Which are the F and the E of SAFE. |
|
@pimbrouwers the points you make on onboarding people to F# probably addresses larger concerns than SAFE. SAFE is about full-stack, cloud enabled web development in F# - so Fable and Elmish will continue to be a core part of that. Standalone Saturn is definitely "a thing" (indeed, I've just done a few YouTube videos on that), but that's not what SAFE is about. |
|
Apologies. Ignore my rant. |
|
I may personally miss the current way of doing things where we can choose-and-pick components but I do understand the issues arising from this and don't think the v2 should be a deal breaker for anyone. Especially if the Minimal and F# templates (which I think are quite well thought out) provide a baseline on top of which people can add components themselves but do not have to remove them. In this spirit I would suggest removing Saturn from these two templates since I think many people use SAFE stack without it. You could argue that Saturn should be included since it is one of the components in the acronym but then again, Azure is not part of these two templates either so it should be ok. Thank you for your great work! I may be able to help with some tasks. |
|
Regarding maintainability of the template. I'd suggest looking into what I did over here at MiniScaffold's template tests. I create a set of scenarios/situations I want to test for, generate the template, and execute/assert certain conditions about what was generated. I think this might give you a good starting point to help write tests for this template. |
|
I too would like to toss my coin for Feliz support. Also another thing that has gotten me into trouble with SAFE stack is when I need to update the npm packages. It would be cool to have some tool or documentation for a process how to update them in a way that does not wreak havoc with Fable. Might also be just me but this has been the black magic part for me. |
Have you heard of Femto? Not all libraries have it supported, but it's quite nice. I think pushing to have more projects embed this metadata would be really beneficial. Even if you don't use the tool, knowing the expected range in the fsproj of the source code is really nice. |
I have heard of it but haven't yet got my hands dirty with it, although I have been in the understanding that it is not integrated with the SAFE stack templates. |
|
Something we can / should be looking into in the future as well. |
|
I think having a test project for the template would be a good idea, using either Fable.Jester or Fable.Mocha. Over the past few weeks I've written bindings for react-testing-library, user-event, and fast-check. Those three are platform agnostic (I know @Zaid-Ajaj has gotten the first two to work with his library, the latter was just finished yesterday/today). In particular being able to do model-based testing on your elmish update function. @Zaid-Ajaj has also been working on an extension for RTL to make testing elmish code easier. |
|
I think I have a slightly odd perspective which may or may not be useful to share... Up until about two/three months ago I had never built a client-server application, never even written any Html or Javascript. I had mainly done programming of tools and utilities - some machine learning stuff, some regressions, some optimisation - plus some jazzed up VBA via VB.Net/Excel-DNA and some database work with POCOs in F#. But I had cause to learn how to build an application for something that I want to do this year, and overall I've found the SAFE Stack a pretty good way of doing it. I've followed my nose a bit and made use of some great packages like Feliz, Feliz.Bulma, Fable.FontAwesome, etc. However, in that time, I've done an awful lot of scratching my head and puzzling over terms because I have effectively zero .NET Core, ASP.NET, C# experience. It seems to me that virtually all documentation is written with a view to converting existing C# devs to the cause. That's fair enough - I can see that that's where most of the new adopters will come from. But what I would love (and I'd be happy to help write some docs provided someone can idiot-check them) is a guide that assumes nothing. How do we get a template and documentation that you could give to a curious 12-year old and have them building an app in an afternoon? Why even explain that Fable compiles to Javascript? Can't we abstract that in the same way that we don't dwell on Javascript compiling to machine code? I still would find it hard to explain what "type-safe CSS Classes" are, because I've never worked with CSS. How do we just communicate how to lay-out and format a web-page without disappearing among the weeds? Similarly, I'm a fan of Domain-Driven Design, and how it fits with the F# ecosystem. But again we often start assuming that people are coming from a different paradigm and so we focus on relative advantages and disadvantages compared to those. But we too seldom approach it from the perspective of a complete newbie, and I think we could and should. In terms of better documentation (for newbies as well as more experienced users), I think we need more pages on common pitfalls and errors. For example, I'm currently stuck with an error in the Browser Console that says: [ELMISH DEBUGGER] Cannot generate auto encoder for Microsoft.FSharp.Core.FSharpFunc`2[Shared.MessageTypes.Msg,Microsoft.FSharp.Core.Unit]. Please pass an extra encoder. Now, I've sort of worked out that it doesn't like the Msg->Unit signature in one of the types. But I'm not really sure what it means and how to fix it. (It will be coming to a Stack Overflow page near you before long...) But documentation that explains "this is what it is, this is what an encoder is, this is how to pass an extra one" would be invaluable. This sort of thing might involve more integration with, e.g., Zaid's brilliant Elmish Book, but a more structured Help page on the SAFE website would be really helpful. In terms of other stuff, a template that functions much as a simple Jupyter Notebook does would be cool - somewhere between Jupyter and LinqPad, where you could load data and analyse it as a stepping stone to making it an online application (Not too dissimilar to Isaac's recent Covid series of videos). Finally, if anyone has a smart way of being able to vary the localhost addresses for the client and server, that would be a nice touch. |
I imagine it is unable to serialize any function. If you need such a thing, you need to create an encoder yourself. Perhaps Thoth could provide a better error message if you specifically try to serialize a function? Not sure how useful it would be.
I think this is true for the general F# ecosystem, not just Fable. It's assumed (not wrongly I'd think) that the majority of newcomers already know the basics of .NET and C#. It would take a lot of work for the few contributors to document every little thing that might be obvious to a non-newbie (because where do you stop, how deep you want to go?), given how small the F# community is (and thus the potential contributor pool).
Vary how? |
|
@kerams It would be nice if the two addresses could be set within the code - just two lines in a configuration file to set the server and client localhost. I'm sure there are good reasons why this hasn't been done but, as an ambition, I think it's a valid one. (I could be wrong, of course!) |
|
My 2 cents. First of all a huge thanks for this project - it was incredibly helpful taking the plunge for doing mostly pipeline / backend data processing to building a fairly large SPA full stack F# app. We ended up basically taking the bookstore app and hacking it till it wasn't recognizable after a while. It definitely helped us getting started At some point, I wished the example apps were a little more fully featured. I can see some of the tension in the discussion here. For example, authentication is only briefly touched on but in reality almost any serious application unless it's come see my demo is going to need to hook into a commercial grade auth system and that took a lot of time. Databases are also a staple of a huge number of real word applications. The azure storage was cute for the bookstore but didn't really help us getting to where we needed to be and might even have been a mild detour. Which brings me to my main point - and I think this is the source of a lot of the tension in the project / thread - who is the audience and what are you trying to do? (to be clear, not trying to be critical here, it has been helpful and whatever it becomes will be useful, I have no doubt). On one end of the spectrum, it can be a tool for helping to recruit people to F# / web development. In that scenario, magic is mostly useful. You don't want 10 pages of instructions to get hello world on the page. The opinionated approach works, though you have to be very careful not to push someone down a path that will become frustrating if their hobby project becomes a monster and they need it to really work. Other solutions to this problem are tutorials or working apps that can be cloned and hacked (these are almost easier to maintain since you can do CI / make them a useful app. Other end of the spectrum is the app-builder / getting started quickly problem. E.g. friend asked yesterday if I could build a quick app for X - how quickly can I bang it out. Here you need a ton of bells and whistles. App to build an app (Ruby on rails kind of world) has a huge market for more experienced developers. I don't know how many times a year this happens, but know I would write more quick and dirty apps for people if the startup costs were lower. This needs to be more complex though to generate more simplicity. Given the rapidly mutating / evolving F# ecosystem (good thing IMHO) it would also need to be somewhat dynamic - way beyond template world, and polymorphic (ideally allow lots of people to contribute styles of app / features so you could mix and match transport layers / storage layers / auth layers). Again a competitor is just a gallery of demo apps but it's tedious renaming every damn module from HelloWorld to StartupIdea. I think you run the risk of missing both audiences if not careful - remove too many options and you lose the second audience, don't focus enough or be too opinionated in feature selection and you miss the first one. Orthogonal concern - one side effect of the rapid evolution is lots and lots of broken docs (not just SAFE but across the community). I have become increasingly zealous about destruction of documentation in my worlds. Better to have a few good pages than lots of out of date stuff. Focus on ease of maintenance, make it easy for people to ping you when it's wrong. In that sense, a gallery of well maintained code that is under CI and always works is sometimes the best documentation. The number of times I would have killed (ha ha not really) for %^&ing working example of something I've lost count of. I had a multi month battle with integrating google auth into giraffe and all the examples were too simple or wrong (not really a safe thing but something I hit really quickly taking simple safe stack into need to deploy this in an enterprise environment). This got longer than intended too quickly - hope it's useful, really support this effort - let me know how I can help. I do end up on-boarding a lot of F# curious folks, so can guinea-pig a lot of people when you are ready to test against a semi naiive audience. |
|
Adding my 2 cents as someone who learned programming in F#: First of all i also want to thank you for the work so far, it was overall a very pleasant experience to expand into web development using the SAFE stack. I fully agree with @ajwillshire regarding a need for a guide that assumes nothing. The current state of the SAFE stack feels very 'top-down', meaning that F# is set on top of a skillset that the user is expected to know already. This is not necessarily a bad thing, it just means its harder to get into completely naive.
This has always been frustrating with 90% of F# resources. I think the SAFE ecosystem has the additional "problem" of additionally targeting webdevs, resulting in a lot of standard tooling used from that world that is not explained. Take I am hosting two websites created with SAFE and never touched the Like @daz10000 said, it definitely depends on your target audience, but i would suggest explaining the core tooling from the webdev world (webpack,npm,Hot Module Reloading) thoroughly in 'bottom up' guide. One of the strengths of F# is the community, and i think we could gather members of both "teams", bottom-up and top-down to maybe work on two types of guides for SAFE. As others in this thread i also would offer to help on that front |
|
@kMutagene @daz10000 @ajwillshire these are excellent points, and I'm personally happy to read them because these are exactly the sorts of issues we've been discussing anyway. The idea of the new template is to have two simple choices:
There's obviously a huge gap in between these two options. In the short term, we'll plug that gap with clear, simple and reliable documentation / guides that show how to go from zero to the "opinionated" template as needed. Documentation is relatively cheap to author compared to baking into the template, and also provides benefits in terms of education. In the longer term, we might automate this with some kind of modular plug-in system. The challenge with documentation is that each library has it's own documentation as well - Fable, Thoth, Saturn, Giraffe etc. - and we don't want to rewrite those. What we can do though is provide good guidance on the SAFE site towards those docs sites, and contribute to them as well. In terms of users, I normally categorise SAFE users into a few separate personas:
Does that feel about right? |
|
@isaacabraham Sounds great to me. Are there insights on the distribution of the 4 types of user categories? Would be interesting to know.
To add a little to this point: Imho think the guidance on the central SAFE docs site is key here. I think all core components (in this case i mean everything you listed as core feature for v2) and maybe to a lesser extend all components of the template should have at least an explanation on what it is and why the component is included (just like the sections on Saturn, Azure, Fable and Elmish which are very good already imo). Also it could be a good idea to give two types of entry points for docs depending on the template type, meaning specific docs for the "batteries included" and the lightweight template |
|
@kMutagene we have no official stats or data - templates can't send telemetry or anything. This is based on evidence from e.g. chatting with users, customer engagements etc.. So, we don't know the split of these personas - but those are the types I've seen cropping up. |
|
I agree with @Shmew that having template that generates some simple tests like an integration test for the routing on the backend and some ui tests on the frontend would be very beneficial. For the integration test something like this would work well: https://github.com/giraffe-fsharp/Giraffe/blob/master/samples/SampleApp/SampleApp.Tests/Tests.fs |
|
I really like this direction. I have never used the SAFE template before because it's easier to start from scratch and put in only the things I need rather than remove so many bells and whistles. With this direction, the minimal template is something I could potentially use. Some further suggestions on the minimal template. Rather than using Fable.Remoting, I think it would be more minimal to use regular HTTP calls. Personally, I use Fable.SimpleHttp. Then for wire format use Fable.SimpleJson on the client, and Fable.Remoting.Json + Newtonsoft.Json on the server. Those specific libs are my personal preference, but in general this tactic of making an HTTP call to an endpoint seems more minimal and easier to change than coupling to an RPC framework. The most minimal starting point for the back-end would be to just use This is all under the assumption that the minimal template would be something that works out of the box, but brings in as little dependencies as possible so that it can be more easily customized to suit the dev. |
|
Personally, my first programming language was F# and my first introduction to web programming was the SAFE stack application. So while i had already worked with FAKE and Paket i was completly new to anything webrelated. Therefore i can not fully support to base the "F# Developer" template on the minimal template.
For me it was definitely a huge help to get some starting points.
This is really important to me, as i still need all the guideline and documentation i can find. I am really looking forward to v2 of the SAFE stack as it had become a huge part of my interest in programming, thank you for your awesome work! |
|
@isaacabraham - love the taxonomy. That captures a lot of the learning paths. The coming from the back end and fable/elmish as first web dev experience particularly resonates for me. I know a lot of people who wouldn't consider themselves front end developers (or particularly like it), but are happy to do fable/elmish as long as they don't have to get hands too dirty with webpack config :)
|
|
@kspeakman for the minimal template, we won't use Fable Remoting - it'll just be raw HTTP, probably using some serializer that we settle on e.g. Thoth or Simple JSON. |
|
Thanks everyone for their comments - that's a very good insight. I think that the "F# Minimal" might not be that crucial to have, as it's easy to start with Minimal and extend it to "F# Minimal" by yourself - and that process would have been well documented. That said, I'd like to find out If, and how many users would miss the "F# Minimal" option |
|
I started with F# & SAFE stack and have no previous dev experience. My opinion doesn't fit the above minimal/full categories cleanly, so may not be too valuable. This is a bit of a ramble - the summary is "I love the stack and support the idea of simplifying".
I do appreciate this is meant to be "a good stack" not "a good stack for complete beginners" so many of the above comments are somewhat redundant ;) I really like the stack and the community around it - I would've been pretty lost without something opinionated to follow along with, and have huge respect for all the effort that's gone in. |
@drk-mtr Please take a look at Feliz.ElmishComponents which attempts to solve this boilerplate problem by writing standalone React components in Elmish style without requiring the parent components to explicitly manage the child state. Even without ElmishComponents, you could still benefit from stateful React components using just plain Felix and use these within the Elmish application |
|
Oh yes, I forgot to address |
|
@Zaid-Ajaj - I've been using |
|
Hi, Just sharing my usage: The first time I do after initializing a SAFE app is removing FAKE and Paket. The next ones to go are Fulma and FontAwesome. While removing FAKE I also remove release notes. In my current project, I use Suave because I failed to get Giraffe working on Azure App Center due to some weird issues with the ASP.NET platform handler, but that's it. If this bug is resolved on the App Center side I see no issues with not having Suave support. I actually use and appreciate both Fable.Remoting and Fable.Bridge, but I guess with a guide on how to set them up from the minimal project it should be good. So I guess I found myself in the "minimal" camp and the proposed changes should be fine. Keep up the good work! |
|
I believe for DB migrations , giving also the simpler DbUp (using sql scripts) as option would be really nice, instead of migration DSL packages like fluent-migrator. But this is indeed more for Saturn repo, will post it there. https://dbup.readthedocs.io/en/latest/philosophy-behind-dbup/ also combining Fsharp.Data.SqlClient might make migration sql scripts compile-time checked :) Also regarding paket might be worth excluding it from the options, and maybe enable a --withpaket flag , since it's quite common for F# developers, but unknown to most of other folks (plus not being supported in VS2019) so definetly i would esclude it unless it becomes supported by default in VS2019. I would take care of making most of "default" work out of the box also in vs2019. And also agree with swagger/swashbuckle that is kind of a big feature missing from the default setup, that should be the default, provide openapi specs together with backend webapi, else it's not really "industry proof". Even in the context of making use of one of the most awesome F# type providers : http://fsprojects.github.io/SwaggerProvider/#/ Saturn should have openapi specs as default in my view extra hint, i personally love this, if possible use FSharp.Data JsonProvider for appsettings.env.json files for aspnetcore, that gives a big advantage of not having to type new stuff every time a setting is added, also useful in industry and quite common scenario (which already show advantages over e.g. C#) --> also will post in saturn repo, sorry for out of topic. |
Paket works just fine with VS2019 as it's integrated with MsBuild and run during the standard |
|
As SAFE 2 is now live I'm closing this issue. Thank you to everyone for feedback and ideas! |
and others
The purpose of this issue is to review where SAFE is and to discuss the team's thoughts and plans going forward - where SAFE is, where v2 might take us, and the potential future. We're interested, of course, in everyone's thoughts and feedback.
1. SAFE today
SAFE has achieved many of the goals it originally set out to do e.g. help F# developers adopt web development by treating F# as a first-class citizen across the stack, improve the understanding of what F# can be used for, and to become a more attractive platform for people looking at .NET, F# and Azure for the first time.
We're now in a position where the platform has, to an extent, slowed down in terms of development and evolution with some relatively minor changes e.g. keeping pace with changes to .NET Core etc. and need to decide how to best move forward.
2. Current Challenges
Some of the challenges we've identified and see today in SAFE are outlined here:
Maintaining the template
The SAFE template started out as a relatively simple dotnet template, but it's grown to such an extent now that it's becoming more and more difficult to make even what appear to be trivial changes. This impacts everyone through either bugs creeping into the template, or simply a lack of time available to address issues or accept PRs that people submit.
Fable Bindings
We know that there are not enough high quality, ready-to-go Fable bindings for popular React or Javascript libraries.
Website and Documentation
Whilst the SAFE site has a decent set of documentation, it hasn't been kept up-to-date, and nor does it provide enough guidance for common tasks. Also, the website itself needs to be spruced up a bit - the landing page and docs section appear to be two separate sites rather than a coherent whole, whilst the landing page does not explain the benefits of SAFE well enough.
Samples and Demonstrators
Whilst we have some samples and demonstrators, they are either not especially easy to find and / or there are not enough of them.
Consistency in and understanding of the Ecosystem
We've seen a number of different tools and technologies grow in the SAFE ecosystem. This is great - it shows a healthy diversity - but we also need to ensure that there's good documentation in outlining the options and showing how to choose what to use and when, as well as providing a simple, opinionated choice for beginners for want to quickly get started.
Too much magic
The default SAFE template options - even in their most simplified form - still provides challenges for some users. On the one hand, it provides a lot of bells and whistles, but on the other hand, this can be intimidating for those people that are not familiar with either the JS or F# ecosystem and tools. It's often not clear what each of the many files do and provide, which can lead people to see the template as bloated.
3. SAFE v2 Plans
For SAFE v2, we want to address a number of goals that we've observed over the last year or so. It won't be possible to achieve all of them for a "launch" of v2 but rather to put in place the foundation from which we can iterate, build and evolve the SAFE ecosystem step-by-step.
Simplify the template
We had originally looked at building out either a more powerful template, or creating a dedicated safe tool that would provide a modular plug-in system that would present people with the ability to opt in to various features and tools in a more extensible and pluggable way. However, this presents two issues:
Instead, we plan on going in a different direction and dramatically simplify the template which will target two or at most three different personas:
In addition, we also intend to simplify many of the elements that we keep - whether it's the FAKE script, the webpack file or how we bundle external JS dependencies and libraries.
This matrix highlights how the template may look - we're still iterating on it and would welcome feedback.
Core Features
This are features that we will include in all variants of the template.
Sometimes used
These are features that will not be bundled in all template variants.
Opinionated only
These are features that will only be included in the "opinionated" template option.
Dropped Completely
These are features that exist in the V1 template but will be dropped from V2.
The benefits of this approach are:
I love xxx feature in the template! What should I do now?
We know that this simplification won't please everyone and that there are features above we love. We will, of course, also amend the template over time based on feedback from real-world usage. In the short term what we intend to do as a replacement is to provide an excellent set of documentation, recipies and samples that will enable people creating new SAFE applications to rapidly incorporate those features into their SAFE applications. In time, we may automate this process using something similar to the way that Symfony Flex operates.
More Libraries
Whilst we know that bindings are not especially difficult to create, having more of them will undoubtedly help. As such, we plan on reviewing the most popular and commonly-used libraries that do not have equivalent stories in the SAFE world and committing to create high-quality bindings for them. This could include data grids, CSS frameworks, control sets etc.
Update the website
We plan to redesign and re-launch the website to include more information, more guidance, and better access to resources. This includes:
Samples and documentation
We need to provide more samples - both simple "how to" applications as well as full blown demonstrator applications that are hosted and made available for people to try out. This will vary for simple "how do I use websockets" style recipies to full-blown end-to-end apps that demonstrate using various Azure services with F#.
Provide more guidance
More critical analysis and recommendations will be provided on the documentation site to enable people to understand when to use which technologies that have an overlap with one another, as well as provide an overall, up-to-date registry of all SAFE-compatible libraries. More of us will also invest time in being available on Slack and the F# forums to support the community.
4. Next Steps
The key areas being worked on currently are to enact the changes in the template, and put in place a new website with documentation to replace the automation that the template provides. Over time, the remaining elements above will naturally fall into place.
Feedback!
We're definitely interested in both constructive feedback and suggestions from you. What are your thoughts? Do you have ideas or comments on things that we might have missed out here? etc.
In addition - if you have support and time to help make this happen, please let us know. Some of us e.g. Compositional IT are committing to dedicate several days every month towards investing in the stack to make sure that we keep it up to date and as compelling an option as possible, but every 1% that we can all contribute will help.
The text was updated successfully, but these errors were encountered: