Ok, thanks. There are many tasks waiting for a recipe… I will surely take some time to contribute. Note: the page says something about a « cookbook section of the CONTRIBUTION.md » which doesn’t exists yet.
I guess that the Database section should provides SQLite, Postgress, MySql, and multi-database option. (Caqti and Petrol are multi-database… no need to duplicate their recipes)
The plan seems to follow the Rust Cookbook (the Earth distance between two points is typical !) I guess it can be adapted (no mention of ZIP… but tar.gz is proposed. However camlzip handle the former not the last one. And ZIP has more usages - docx, jar, …)
There appears to already be an issue raised suggesting that a central list of who has volunteered for what would be helpful. In the absence of that I’ll mention here that if nobody else has yet, I’ll take a look at the “command-line parsing” items over the next few days.
I would greatly appreciate some recipes on concurrency. I clicked on the “create and await promises” link and it takes me to an empty page: OCaml Cookbook
The process of writing a cookbook entry seemed quite simple and I’ve had my first attempt reviewed already, so I will have a go at writing some recipes for “create and await promises”. It may take me a few days @zoj613 - it will need an example using Async which I’ve never looked at.
Are there docs on how to run or test the cookbooks against the CI/CD with the yaml meta at the top of the file? I have a PR up for reading csvs which I used dune to get running then reformatted to match the cookbook format. I’m hitting errors in the CI/CD which I’d like to resolve locally if possible for quicker iterations.
I just ended up getting my code-samples working separately from the cookbook and pasting the yaml in the top once I was done
That wasn’t ideal because I still wanted to tweak the comments to line up with my code.
I think longer-term the yaml needs to go in its own file (named to match the .ml file?) or be in a comment at the top of the file or some such. Possibly the cookbook code should be its own repo too with tests for expected output etc. That might have value of its own anyway - it could be useful to clone the cookbook repo and hack around on the examples.
It seems in my case the meta data had to be quoted for the build to pass (some other examples I looked at weren’t quoted so this might be a recent-ish change).
I found interesting to have this Cookbook in OCaml.org, but even more that idea that the community can participate in this part of OCaml.org which is fostering the collaborative values. Three comments:
I saw that the cookbook pull requests are frozen in OCaml.org since April 2024. There are 34 PR at this moment, and 20 are cookbooks. Personally, I don’t know is there is an specific reason. So I asked myself if we could still submit PR with our contributions? Could we have some feedback about what is the current situation? I asked in pull-requests but never answered.
Me (and maybe others) proceed by checking OCaml Cookbook looking what is required, and we contribute with a PR as indicated. However, when I realized that my contributions were frozen more than 2 months, I checked there are old cookbooks for months and we are somehow repeating work about specific cookbooks. Are we aware of that?
The cookbook section itself has issue of navigation. My point of view is that it is needed something similar to Exercises, where there is an index of categories on the left sidebar.
Thanks for the nice OCaml.org webpage and kind regards.
I do agree… I have submitted multiple PR some months ago and some of them are still frozen. My database contribution has been approved only recently, but I guess I should wait the approval of more waiting PR before adding even more.
When I see the OCaml Cookbook page, there are « This task has no recipes yet, maybe you want to contribute a recipe » where some on my « recipes » are waiting. This makes me encline to wait, have an accurate view of what is really missing.
I definitely saw a recipe get merged very recently. One strategy I always recommend is if you send a PR to the repo, take a few extra minutes and review someone else’s existing existing PR so that you reciprocate the review that someone else will have to do for yours. This helps to reduce the burden on the reviewers.
but even more that idea that the community can participate in this part of OCaml.org
Yes, cookbook recipes are intended to be contributed by the community. But the rest of ocaml.org, too.
Could we have some feedback about what is the current situation? I asked in pull-requests but never answered.
Reviewing cookbook recipes is surprisingly difficult, so progress is slow. Recently, some PRs have been merged. You can contribute new recipes, but reviewing feedback on existing proposals would greatly help. Sorry for not answering in GitHub; we missed your feedback.
The cookbook section itself has issue of navigation. My point of view is that it is needed something similar to Exercises, where there is an index of categories on the left sidebar.
That’s an exciting proposal. Can you file an issue describing what you would like to have?
Just an update: I am, as far as I know, the only person reviewing these.
Indeed it would be greatly helpful to review open PRs under the concerns:
is the task being proposed reasonable, or could it be made more realistic / useful without introducing unnecessary complexity?
is the code presented good enough to copy into a production codebase without creating any serious concerns? (This concerns naming of variables, but also not introducing security worst-practices, or providing code that triggers undocumented exceptions, and more things that could cause trouble.)
are the explanations minimal but useful? We are not looking for lengthy discussion, but instead want to give people code examples for common tasks. The more text there is, especially when it has a likelihood to become outdated, the more work for the reader and the more work to maintain it. People can always check out the documentation of the package (and we can link there, which can be useful when there’s multiple packages used but only one has the relevant docs). If some code needs explanation because of bad naming of things: Propose obvious names so the code doesn’t need explanation instead.
Would you consider a section for new users with some common examples to help people start to create standalone projects in a few simple scenarios with extra documentation?
Projects like reading file content, using OCaml libraries, talking to a C library with the correct dune files allowing people to clone the project and play with exploring the language and simple aspect of the ecosystem?
Would you consider a section for new users with some common examples to help people start to create standalone projects in a few simple scenarios with extra documentation?
I think this would fit in very well with the Guides section of the documentation (if advanced enough), or the Getting Started section (if aimed at absolute beginners).
Such contributions are very welcome! Best is to propose a title / brief outline to make sure it doesn’t overlap with other docs (or should rather extend other docs) before spending a lot of time writing.
I addressed all open cookbook PRs up until Dec 10.
PRs have either been edited and merged or closed, and in one case, a comment has been left to clarify.
Criteria:
Is the task useful when writing real world applications?
Is the code ready/safe to copy paste into a production codebase? (I.e. is the code structured such that it’s easy to adapt it, and are things named well, and are there any security implications or uncaught exceptions)
In case of Standard Library code: Is a LLM able to easily generate the code? (If yes, no use to include it in the cookbook) In the case of code that uses a package, it’s still worthwhile to include it in the cookbook because this constitutes an explicit recommendation to use this package in production.
Do the other recipes for the same task implement the exact same task? When there are multiple packages that can be used to do a thing, it’s helpful to see how the packages differ, so the task itself should be the same between different implementations with different packages.
Thank you to everyone who contributed. I am aiming to review new PRs much quicker.
