Suggestions from the OCaml Survey result

[patricoferris]

Thanks for the great suggestions so quickly! I’ll also set aside some time to summarise everything once some more ideas are posted and there is general consensus.

@lindig

I believe a common theme among the comments in the survey is a lack of structure found in documentation, libraries, and critical build tools

Completely agree – documentation is fundamental as it is felt by most I feel. The limitations of build-tools are perhaps more felt by more advanced or complicated workflows.

@lindig

curated Opam repos

This sound really interesting – from experience I think quite a few beginners are unfamiliar with the ability of having multiple repos. I certainly was until I started cross-compiling to RISC-V :)) I think a good example curated repo would help drive this home more, do you know if one exists beyond the cross-compiling ones which aren’t exactly what we’re looking for?

@kanishka

Use sourcegraph and other code search mechanisms to surface all the work in progress (WIP) libraries that people have put together on github/gitlab/etc

This sounds good. I do wonder if more documentation/tutorials/awareness of dune-release and opam-publish might also help. I, for one, am sitting on a few libraries I should really publish but the process can be a little intimidating, so I still agree a search would be great but ultimately it would be good for libraries to make it upstream.

@yawaramin

Thanks for this great analysis

Thanks for the kind words :))

@yawaramin

Is GSoC still a thing?

Not in a position to start making GSoC proposals but they are definitely still a thing! For example two projects I think are great, still do them. Even outside of GSoC perhaps a curated list of OCaml Community approved projects/internships that would benefit the whole community would be good that different businesses/organisations/foundations could use when making their own internships would be useful? At least everyone would be united on that front.

[kanishka]

@patricoferris

I do wonder if more documentation/tutorials/awareness of dune-release and opam-publish might also help.

It might help for the people who have libraries that have reached that level of maturity. I think most people and companies are too busy to get their libraries to that level of maturity and being willing to properly support a package put on opam. direct, point to point sharing of source code can lower the fear/hesitation about “I won’t have time to support, answer questions, or clean up this code for someone else’s use”

[Ulugbek]

I was doing absolutely the same thing (a jupyter notebook in google colab so users can play with the data) but you got there first I was also interested to see correlation between different “random variables” such as most wished feature and OCaml experience

[lindig]

That abundance of tools required to install, develop, compile, and release packages is a complaint in the survey. Adding more is not going to reduce complexity. I do think the publishing process is too complex, though.

[mseri]

Do you know if and how one can use ocaml on colab? In principle there is support for the jupyter protocol…

[Ulugbek]

I was using python

[CraigFe]

This is perhaps better in (yet another) split thread, but if you’re looking for an easy solution to spin up OCaml-kernel Jupyter notebooks – without hosting the infrastructure – then it’s very easy to do this with Binder and the right Dockerfile.

I recently used this workflow for OCaml teaching, and was very happy with it. /h.t. to @jonludlam for the suggestion.

[avsm]

Thanks Patrick for the fantastic distillation of results. It’s extremely useful to see our user responses segmented by their experience. (in particular, our self-identified expert userbase runs Coq a lot more than our self-identified newcomer codebase who tend to use JavaScript – we want to make sure we continue to help all of these segments!).

At a high level, this survey has already influenced the Platform tool developers. Documentation has been identified as a priority item for next year, and so a couple of next steps are happening this week already among the various groups:

• The regular odoc developer meeting this week will also feature the opam team as part of our community dev meetings, and we are getting together to put the final plan together to put a docs.ocaml.org site together. The results of this will be on the dev wiki as usual, so anyone interested can track progress and suggest ideas (the video meetings are not exactly closed, but fully open participation isn’t practical given the constraints of current technology – please ping the odoc maintainer @jonludlam directly if interested in attending)

• the second part of a docs site is to ensure we have really reliable and solid workflows for opam-repo contributions (including bulk builds, health checks and having a more automated contribution process, ideally without having to run a CLI tool). The next opam dev meeting later this week will feature us planning a switch to a cluster-based nextgen CI for opam-respository. We’ve also invited the maintainers of the Coq opam repository as well as Tezos and Jane Street (who contribute large package sets regularly) so we can ensure we work well with those ecosystems as well. Our intention here is to really reduce the burden on contributions to opam repository by mechanising as much of the grunt work as possible, thereby helping both beginners and expert users. Our new CI will also feature macOS and Windows testing as we bring those cluster workers online, and be much more easily extensible to custom workflows.

• Having all the fancy package cluster builds in the world don’t help if noone is actually writing any documentation in their libraries. We’re hoping that new tools (such as mdx from Real World OCaml) will reduce the friction of entry to writing ocamldoc tutorials and sites. The mdx tool usage is easy but the implementation is quite complex (due to the interlock with the internal compiler-libs), so there is a mdx team working away on it, including hopefully speeding it up with native code compilation and continuing to improve the integration with dune and other build tools. @yminsky and I use mdx to write the whole of Real World OCaml (v2 of which is coming out soon in print), and we are most eager for other people to fork our tools and write their own books (like the Owl scientific computing book).

• Finally, @ashish @gemmag and I have been putting our heads together to get funding sorted to reboot the ocaml.org site and make it easier to maintain, in recognition of the fact that the “old guard” (Christophe, Ashish, Phillippe, myself) just don’t have the day-to-day time anymore to keep things up. @patricoferris, @kanishka @sanette Bella and @JohnWhitington have all been contributing content to ocaml.org, and we are doing both incremental changes and also overhauling the internals of how it is built to use the latest and greatest innovations. I’m excited to see what all these new contributors will come up with.

This is of course not a closed list of action items – simply what I am tracking as the coordinator of the OCaml Platform efforts – so please keep suggestions and analysis flowing.

Thanks to everyone for the input and comments so far. If anyone has a burning desire to be in any of the dev meetings, please get in touch with me directly (anil@recoil.org) or the maintainers of the individual tool. I’ve never seen this much activity happening in all my time working on OCaml, so it warms my heart on this crisp winters day to see all the constructive positivity and effort going on. Keep it up and keep the suggestions coming

[BikalGurung]

Thanks for the update.

For mdx, I think this RFC if implemented would be very helpful as it would help with both documentation and testing. Sometimes an API example really helps sharpen the understanding.

[grayswandyr]

I was surprised to see that relatively few people seem to have talked about OCaml teaching. I would argue that these are a lot of newcomers, but they don’t answer polls As far as we are concerned, the modern OCaml experience is much better for us researchers but is more difficult when wearing our teaching hat. Our students are not complete beginners (they already know several languages and an interpreter/notebook-based approach would not fit the size of programs they have to write) but most of them are still not mature developers. So we’re a bit stuck between an interpreter-based approach that doesn’t scale much and that is not the current standard way, and OTOH an opam/dune-based approach that’s still a bit rough on the edges. Installing an all-in-one OCaml teaching platform still requires many steps students don’t understand and we can’t ensure stability from one year to the next. Also, the source-based approach is a problem for some students with old hardware because installation is looong. My 2 cents.

[kanishka]

@grayswandyr

we can’t ensure stability from one year to the next.

I freshened up the links for courses on ocaml.org into its own table here (https://gitlab.com/kanishka-azimi/ocaml-courses). It might help a little to be able to see what the larger classes are using each year for install instructions, while waiting for improvements upstream in the core tools.

[cloudyhug]

Talking about teaching.

I learnt OCaml at school 3 years ago. I remember two kinds of setup: practical sessions writing all the code in one file only and using the interpreter, or projects with a Makefile already given by the teacher, and mainly using pre-dune tools like ocamlbuild or OCaml Makefile in a black box way, which did not encourage students to try to understand how an OCaml project was supposed to be managed. I remember having to learn on my own about ocamlbuild, to be able to manage my own side projects. So in a way, I totally understand what you feel, I can only like your message.

But I also feel like dune makes project management a lot simpler. I mean, in OCaml courses we usually build small compilers or that sort of stuff, which needs handling ocamllex / menhir files, not much more. I guess we can still provide a rather simple dune file, but the difference is, now we can explain it quite clearly to the students, and not have that kind of obscure build files. We can even use things such as utop for live-testing.

Another issue (the main issue preventing students from easily adopting OCaml in my opinion) was that we had to learn emacs (with tuareg mode) along with OCaml. The difficulty was not only to learn a new language or even a new paradigm, but also learning a less beginner-friendly development environment, and not being able to use what we were used to. This problem has been solved too thanks to the development of environments such as VSCode. (edit: I’m not anti-emacs, I recently started learning vim, but learning a text editor during a course was not the right time)

So, while I understand your concerns and do not want to question anything about what you said, I think the situation has improved a lot (even in the last 3 years). I believe we are close to having something practical. I’m only a new PhD student so I have the newcomer’s point of view, but I just wanted to bring some optimism to the topic.

I’ve been working on some side projects in Haskell recently (well, today I’m that guy bringing Haskell into OCaml conversations). We already have merlin and great IDE extensions, but I think we just lack a stack-like tool so that we can just setup a project, compile the sources, and publish the executables quickly. An OCaml version of Hoogle (which I find great) could be nice too.

[lindig]

Would a Docker image set up for the course not take away most of these problems? And skeleton projects that can be cloned from a git repository?

[grayswandyr]

Opam and Dune are great for development, and I convinced my colleagues to use them for teaching, but I think they sometimes cursed me I appreciate greatly the work done on the OCaml platform and thank all those who contributed to it. But from a pure teaching point of view, I think the experience has sometimes been difficult in our school these past years, compared to Makefile-based lab sessions. Even for some colleagues of mine who are excellent teachers but don’t necessarily follow the OCaml pace; but they know how to debug a failing ocamlc compilation called from a Makefile. I don’t think this is the place to list difficulties, so -in the spirit of this poll- I’d rather make the wish that we can get a teaching-friendly variant of the OCaml platform: stable during 3 school years (for instance), easy to scaffold new projects, well isolated from the rest of the filesystem (dune workspace, I’m looking at you), promoting testing (we try to teach our students to write contracts and do heavy testing)… For a very long time, I think universities have played a good role in spreading the OCaml word and I fear that, as the focus shifts on developer-friendliness (which is good), we forget teaching-friendliness.

[grayswandyr]

Our students work on university machines as well as their own one (in particular in these times of lockdown), running any of Linux/Mac/Windows. A lot of them have low-grade machines. I think it’s still easier to tell them something like:

1. install opam in one command (found on the opam website)
2. issue only one opam special command to install a stable teaching environment (hopefully avoiding local compilation)
3. install the OCaml plugin for your favorite editor among VS Code/Emacs/Vim

For scaffolding, I think dune init is actually a first step, but we would once again need a special configuration as the dev and release dune modes need some tweaking (which we currently do in our skeletons) to fit our requirements (e.g. we want non-fatal warnings in dev mode, but also allow running inline tests: we spent a long time figuring out why our inline tests were not failing, until we realized we were in release mode to avoid fatal warnings but then inline tests were inhibited).

[avsm]

@grayswandyr

I’d rather make the wish that we can get a teaching-friendly variant of the OCaml platform: stable during 3 school years (for instance), easy to scaffold new projects, well isolated from the rest of the filesystem (dune workspace, I’m looking at you), promoting testing (we try to teach our students to write contracts and do heavy testing)… For a very long time, I think universities have played a good role in spreading the OCaml word and I fear that, as the focus shifts on developer-friendliness (which is good), we forget teaching-friendliness.

To be clear, I’m very much in favour of this (with my hat on as a busy professor type at Cambridge). I actually ended up deploying Jupyter notebooks for our course instead, and that eased a vast number of installation problems but at the expense of not having access to the full power of build tools.

All the attempts to build a Platform installer have stalled in the face of Windows support to date. The good news is that we’re targetting opam 2.2 (i.e. the next release after the current beta cycle is done) as the “Windows release”, where we will get proper upstream support (including opam and CI) for Windows. This in turn will fold in all the superb work @fdopen has done, and allow us to ship more official cross-platform installers suitable for use in (e.g.) a university environment.

I also have high hopes for the VS Code plugin we’ve been working on this year. Now that the basics are done, @rgrinberg and team have been looking into what more advanced UI integration might look like (for instance, an editor and lsp-integrated opam/dune ui is plausible to build). With this in mind, the workflow that @grayswandyr described can actually be compressed down to:

1. install the OCaml plugin for your favorite editor among VS Code (or tracking-free variant)
2. clone a teaching repo

There should be no need soon to install opam outside of the plugin (I’ve prototyped an opam tools plugin that I need to clean up for @rgrinberg that analyses a project and ensures that all the right tools are available in the local switch).

But… in order to deliver all this as a reliable binary installer, we really need Windows support. So that’s what the opam team is highly focussed on getting done as the sole purpose of opam 2.2. If we reject or delay other feature requests, it’s because we’re busy getting that done

[jaxon]

Can’t MS Windows new Linux support be of help there? Especially if students should install it themself.

We deliver a Ubuntu VirtualBox machine which have all set up. Then it work for our machines and students machines without bother about the set up.

Yes, I am curently looking into Emacs with lsp-support and opam/dune. It would be much easier if we got that working good, and would quickly be able to explain they set up. Yes, they can use MS VS Code if they want to.

[xavierleroy]

Apologies for posting this link twice. Here is a summary and analysis of the survey results I wrote on behalf of the OCaml Software Foundation: https://www.dropbox.com/s/omba1d8vhljnrcn/OCaml-user-survey-2020.pdf?dl=0 Enjoy!

[kanishka]

Maybe split up expert into expert ocaml users and expert compiler/language developers, in next year’s survey. Expert ocaml users may have used ocaml libraries for many users to build applications and other libraries, but may not be particularly interested in implementing programming languages themselves.

[kanishka]

Here is an example of using sourcegraph, in case anyone wants to dive deeper:

https://sourcegraph.com/search?q=repo:ocaml/ocaml%24+or+repo:janestreet/base+or+repo:gitlab.com/tezos/tezos%24+or+repo:c-cube/ocaml-containers+or+repo:ocaml-batteries-team/batteries-included+or+repo:mirage/mirage%24+or+repo:ocsigen/lwt+or+repo:janestreet/async%24&patternType=literal