Add a second example, more beginner friendly

[benjamin-thomas]

Hello Paul,

Following our discussion on the discuss forum, I'd like to show you what I'd like to contribute, as a more beginner friendly second example.

The basic idea is to provide a simple project, showing a many-to-many relationship to generate mild complexity and suggest structure.

As in the referenced blog post by Bobby Priambodo, it would be possible to do CRUD operations via the REPL. And also provide a test suite so that a beginner could play around, break stuff and observe test failures.

The basic idea can be found here

Please also have a look at the lib and test folders.

Does this look like an interesting addition to you? If yes, I would then provide a heavily commented README, to help the OCaml curious beginner run the project and play with the library (I would have liked to have that a few months ago, which is what motivates me to contribute a second example here)

[paurkedal]

I think this is a good example, though I need to think of whether/how it should be integrated or if we should start a separate tutorial repo. Keeping it in the main repo helps keeping the code up to date, though. As far as it contributes to the testsuite, it should be generalized to work with MariaDB and PostgreSQL. I presume that is not problem, except for the extra code to read in the uris.conf file. For the latter in could link the internal testlib, though that's not ideal from a pedagogical point of view.

[benjamin-thomas]

I had a bit of trouble with the internal dependencies of the bikereg example. I remember not being able to play with it a while ago.

For a beginner or an OCaml-curious developer, I think it's better to have the project isolated, so that one could copy it into another folder and start tweaking right away.

To make sure the example stays up to date and always compiles, I could make the example docker based and provide a single command that would run a test suite, then run the equivalent dune exec ./main.exe to demonstrate CRUD functionality.

Would checking the exit status of such a process be okay? The example could be updated after a release?

If you feel this doesn't belong in the repo, please don't feel bad to say so though :)

I just thought I could provide a modest contribution by making Caqti more accessible to beginners since I'm still in this mindset and I would have like to have a bit more hand holding a few months ago.

[paurkedal]

I think too this is very useful for beginners, I'm merely pondering on the practical consequences for both core and tutorial code. The main points, I think, which speaks towards a separate repository, is that the examples should target the latest release, rather than using features which are in development, and that I would be rather strict about external dependencies (e.g. it would be nice to keep ppx_rapper for the example, but it would create a dependency cycle). Due to the policy of keeping the build warning-free, examples would have to be updated as soon as something is deprecated. So, maybe a separate repo would be preferable?

[benjamin-thomas]

Got you. I kept playing after the commit I pointed to, I didn't have the intention to display ppx_rapper usage for info.

Are you thinking another repo under my name or the caqti umbrella?

[paurkedal]

I presume you don't want to take on maintenance, so I suggest i create a almost empty repo which you can clone and extend. I think having examples using ppx_rapper is good too. If there are too many dependencies, though, it may be more work for people to set up their environment. I'm thinking here of having a dune-project (or dune-workspace) file at the root, rather than in subdirectories of individual examples, so by default everything is built. It's possible to do conditional builds in dune, so maybe it examples can be conditioned on what libraries are installed. Or do you think having complete projects in each subdirectory would be preferable?

People have asked about documentation, but at the moment I'd like to focus on the upcoming release. So, if you can arrange something which works, I may make a few rearrangements later.

[paurkedal]

One difference between tests and examples is that the latter should not try to abstract over lwt, async, mirage, eio, but rather show how to use Caqti with a single (or mulitple) concurrency implementations. This is maybe a candidate for a main division for separate builds, since many dependencies follow from that choice.

[paurkedal]

I've tentatively created https://github.com/paurkedal/caqti-study, but I can re-create it if you have suggestions. Is the MIT license okay for your contribution? I'm using LGPL for the main repo, but I'd like to let people to cut-and-paste more freely from the examples.

[benjamin-thomas]

I presume you don't want to take on maintenance

Not at all. I do think it makes more sens for this to live under your name though, since it'll make finding the repo easier for someone searching.

I think having examples using ppx_rapper is good too.

Noted. In that case, since we are going with a separate repo approach, I think I will try to mimic Dream's approach to providing many independent examples. It introduces a bit of duplication, but at the benefit of making studying a specific subject easier since there is less context. I will look into dune-workspace which I haven't used yet, and make sure we build everything by default to keep things simple.

People have asked about documentation, but at the moment I'd like to focus on the upcoming release. So, if you can arrange something which works, I may make a few rearrangements later.

I will do my best. I have some vague ideas at the moment, so I think I'll just try things out and see where it goes. If you feel something is not going in the right direction, I'm happy to rip things apart and redo work to get something better in the end.

I've tentatively created https://github.com/paurkedal/caqti-study, but I can re-create it if you have suggestions. Is the MIT license okay for your contribution?

LGTM :)

I'll send you a PR soon and we can continue our conversation there

[paurkedal]

I almost mentioned dream, as I recall enjoying the format of that tutorial. The numbering of their first section "Tutorial" is nice, though since we don't have a grant plan up-front, I think it's better to follow the unnumbered approach of the later sections, and only organize it by links in the README. So, maybe use an l- prefix for examples using lwt, etc., and no numbering?

I'm not sure about dune-project vs dune-workspace; I think either will do for marking the root, so let's use dune-project until there should occur a reason to do otherwise.

[benjamin-thomas]

This issue can be closed now, see : https://github.com/paurkedal/caqti-study for more examples.