[elm-discuss] Best practices to create examples for an elm package?

[Matthieu Pizenberg]

Exploring a bit the packages repository, I've come accross the following
options:

1. no examples/ dir, all in readme and documentation.
(elm-array-exploration, ...)
2. examples/ dir with nothing more than `.elm` files (elm-decode-pipeline,
elm-monocle, ...)
3. examples/ dir with an `elm-package.json` file (elm-transducers, ...)
4. examples/ dir with a `package.json` node builder (elm-kinto, ...)

I personally have a mix of (2) and (3). However I feel like they all have
issues.

1. Sometimes, having a "ready to build" example is useful.
2. It relies on building from the root directory of the package (where the
`elm-package.json` file lives). It also means that the example file can
"cheat" by accessing non exposed modules.
3. If you add your `src/` dir in the json, then you can also "cheat" like
in 2. If you do not, and you use your package as if it was loaded from elm
packages, then you cannot verify that your latest modifications (not pushed
yet) are working with your examples.
4. Well, it's a bit too heavy of a machinery most of the times. Plus it
also requires an `elm-package.json` file anyway so the same issues as (2)
and (3) apply.

*Do you think there is a best practice? Are there alternatives to those
four?*

[Eric G]

Good question, I'd like to hear what other people do as well. Just to add
two other options to the mix:

5. Link to an example that uses the package in Ellie
(https://ellie-app.com/)
6. Deploy an example to the Github project page
(https://username.github.io/package/ )

5. Is quick and painless assuming you want to use a published version of
the package.
6. Is a bit of a pain to set up, but it can be scripted. I guess this is
"on top of" the options you list below, since you'll still have to decide
how you want to build the example.

I tend towards (3), and "cheat" and access src/ , and just take care not to
access internal modules, I have never found that a problem.

On a somewhat related note, it would be nice to have something like
bl.ocks.org for displaying examples together with code from Github gists.

Post by Matthieu Pizenberg
Exploring a bit the packages repository, I've come accross the following
1. no examples/ dir, all in readme and documentation.
(elm-array-exploration, ...)
2. examples/ dir with nothing more than `.elm` files (elm-decode-pipeline,
elm-monocle, ...)
3. examples/ dir with an `elm-package.json` file (elm-transducers, ...)
4. examples/ dir with a `package.json` node builder (elm-kinto, ...)
I personally have a mix of (2) and (3). However I feel like they all have
issues.
1. Sometimes, having a "ready to build" example is useful.
2. It relies on building from the root directory of the package (where the
`elm-package.json` file lives). It also means that the example file can
"cheat" by accessing non exposed modules.
3. If you add your `src/` dir in the json, then you can also "cheat" like
in 2. If you do not, and you use your package as if it was loaded from elm
packages, then you cannot verify that your latest modifications (not pushed
yet) are working with your examples.
4. Well, it's a bit too heavy of a machinery most of the times. Plus it
also requires an `elm-package.json` file anyway so the same issues as (2)
and (3) apply.
*Do you think there is a best practice? Are there alternatives to those
four?*

[Eirik Sletteberg]

Maybe write an example in the form of an integration test - then you know your example will be up to date with the actual code, and it may even discover bugs!

[Noah Hall]

Best practice:

- Use elm-doc-test for examples whereever possible, don't just write
documentation examples. They easily fall out of sync. If your
doc-tests start to look too crazy, it's possible your API could be
simplified.
- Have a test suite. Depending on your problem, your test suite may
need to be large and complex, in order to ensure all edge cases are
matched. If your package is mostly just glue code, there's not so much
need for that.
- If you have views, use elm-html-test. You can now also test events with this.
- If you are exposing something which is browser-dependant, e.g mouse,
touch, event decoders. You should have an integration test set up that
runs your code in a real browser

On Mon, May 8, 2017 at 4:38 PM, Eirik Sletteberg

Post by Eirik Sletteberg
Maybe write an example in the form of an integration test - then you know your example will be up to date with the actual code, and it may even discover bugs!
--
You received this message because you are subscribed to the Google Groups "Elm Discuss" group.
For more options, visit https://groups.google.com/d/optout.

[Aaron VonderHaar]

I have my examples/elm-package.json include ../src, and have my CI script
build all the examples so that I remember to update the examples of the API
changes.

Also, imo it's good to have a separate examples/elm-package.json because
you often want other dependencies to make a realistic example.

Post by Eirik Sletteberg
Maybe write an example in the form of an integration test - then you know
your example will be up to date with the actual code, and it may even
discover bugs!
--
You received this message because you are subscribed to the Google Groups
"Elm Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/d/optout.

[Francesco Orsenigo]

Post by Aaron VonderHaar
I have my examples/elm-package.json include ../src, and have my CI script
build all the examples so that I remember to update the examples of the API
changes.
Also, imo it's good to have a separate examples/elm-package.json because
you often want other dependencies to make a realistic example.

Agreed 100% with Aaron.

['Rupert Smith' via Elm Discuss]

Post by Eirik Sletteberg
Maybe write an example in the form of an integration test - then you know
your example will be up to date with the actual code, and it may even
discover bugs!

I think there is an issue here that did not come up for discussion yet:

Suppose I have some examples or some tests, and those need packages that
the actual library does not use. Those packages get sucked in as
dependencies even though the library itself does not use them?

Is there a way to have tests or examples and for those to use extra
packages, but for those packages not to be included as transitive
dependencies of the library itself?

[Christophe de Vienne]

Post by Eirik Sletteberg
Maybe write an example in the form of an integration test - then you
know your example will be up to date with the actual code, and it
may even discover bugs!
Suppose I have some examples or some tests, and those need packages that
the actual library does not use. Those packages get sucked in as
dependencies even though the library itself does not use them?
Is there a way to have tests or examples and for those to use extra
packages, but for those packages not to be included as transitive
dependencies of the library itself?

For the example I have a separate 'elm-package.json' in the 'example'
directory, and it has '../src', '.' as source-directory.

About test, with elm-tests you also have a separate elm-package.json in
tests/.

[Marek Fajkus]

My thoughts:


- Most packages don't depend on `elm-lang/html`
- Most examples do depent on `elm-lang/html`
- It's good to enforce examples compatibility <-> library compatibility
in CI (compiling examples in some step)

Solution?


- have `elm-package.json` without `elm-lang/html` in root
- have another `elm-package.json` with `elm-lang/html` in examples
- Ci should compile examples
- If you have more examples in folders of them it's maybe good idea
to have `Main.elm` where you import all of them and compile that Main in CI
- If you have single example jusut ensure it really compiles (not
just pull packages) in CI.

Downsides:

- From my experience some future contributors will ask how they can
compile (or run elm-reactor to work with) examples.

[Matthieu Pizenberg]

Post by Noah Hall
- Use elm-doc-test for examples whereever possible
- If you have views, use elm-html-test.

Thanks Noah, I didn't know about those for lack of using tests. Thank you
everyone for your feedback. So if I sum up, the main ideas are:

1. Keep in sync doc examples by using doc tests.
2. For more advanced examples, use a dedicated `elm-package.json` to avoid
unnecessary package dependencies and integrate them in a test suite.

[Francesco Orsenigo]

A personal pain point of mine is when the examples just import TheModule
exposing (..) rather than just using fully qualified references
TheModule.aFunction .

First of all, because that's not how the library will be used.

Second, and more important, unless you know already what the library
exports, for every symbol you encounter you need to go through the whole
example code to check whether it was declared in the example or it comes
from the library: if you CANNOT find it in the example, then it means it
comes from the library.
The situation is even worse if the library exports more than a module and
all are imported with (..).

I think this unnecessarily increases the time and cognitive load required
to understand a library (which is often times already a demanding task).

Post by Matthieu Pizenberg
Exploring a bit the packages repository, I've come accross the following
1. no examples/ dir, all in readme and documentation.
(elm-array-exploration, ...)
2. examples/ dir with nothing more than `.elm` files (elm-decode-pipeline,
elm-monocle, ...)
3. examples/ dir with an `elm-package.json` file (elm-transducers, ...)
4. examples/ dir with a `package.json` node builder (elm-kinto, ...)
I personally have a mix of (2) and (3). However I feel like they all have
issues.
1. Sometimes, having a "ready to build" example is useful.
2. It relies on building from the root directory of the package (where the
`elm-package.json` file lives). It also means that the example file can
"cheat" by accessing non exposed modules.
3. If you add your `src/` dir in the json, then you can also "cheat" like
in 2. If you do not, and you use your package as if it was loaded from elm
packages, then you cannot verify that your latest modifications (not pushed
yet) are working with your examples.
4. Well, it's a bit too heavy of a machinery most of the times. Plus it
also requires an `elm-package.json` file anyway so the same issues as (2)
and (3) apply.
*Do you think there is a best practice? Are there alternatives to those
four?*

[Jakub Hampl]

In elm-visualisation I use option #3 but build things into a /docs
directory that github serves. This is done
via https://github.com/gampleman/elm-example-publisher, which has a UI
somewhat resembling bl.ocks.org

Post by Matthieu Pizenberg
Exploring a bit the packages repository, I've come accross the following
1. no examples/ dir, all in readme and documentation.
(elm-array-exploration, ...)
2. examples/ dir with nothing more than `.elm` files (elm-decode-pipeline,
elm-monocle, ...)
3. examples/ dir with an `elm-package.json` file (elm-transducers, ...)
4. examples/ dir with a `package.json` node builder (elm-kinto, ...)
I personally have a mix of (2) and (3). However I feel like they all have
issues.
1. Sometimes, having a "ready to build" example is useful.
2. It relies on building from the root directory of the package (where the
`elm-package.json` file lives). It also means that the example file can
"cheat" by accessing non exposed modules.
3. If you add your `src/` dir in the json, then you can also "cheat" like
in 2. If you do not, and you use your package as if it was loaded from elm
packages, then you cannot verify that your latest modifications (not pushed
yet) are working with your examples.
4. Well, it's a bit too heavy of a machinery most of the times. Plus it
also requires an `elm-package.json` file anyway so the same issues as (2)
and (3) apply.
*Do you think there is a best practice? Are there alternatives to those
four?*

[Eric G]

Post by Jakub Hampl
In elm-visualisation I use option #3 but build things into a /docs
directory that github serves. This is done via
https://github.com/gampleman/elm-example-publisher, which has a UI
somewhat resembling bl.ocks.org

Super, glad to know about this!