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

[Christophe de Vienne]

Le 23/05/2017 à 17:44, 'Rupert Smith' via Elm Discuss a écrit :
> On Monday, May 8, 2017 at 3:38:55 PM UTC+1, Eirik Sletteberg wrote:
> 
> 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? 

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/.

-- 
Christophe de Vienne

-- 
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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

['Rupert Smith' via Elm Discuss]

On Monday, May 8, 2017 at 3:38:55 PM UTC+1, Eirik Sletteberg wrote:
>
> 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? 

-- 
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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

[Eric G]

On Thursday, May 11, 2017 at 10:49:17 AM UTC-4, Jakub Hampl wrote:
>
> 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!

-- 
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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

[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

On Monday, 8 May 2017 04:58:26 UTC+1, Matthieu Pizenberg wrote:
>
> 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?*
>

-- 
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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

[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).



On Monday, May 8, 2017 at 1:58:26 PM UTC+10, Matthieu Pizenberg wrote:
>
> 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?*
>

-- 
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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

[Francesco Orsenigo]

> 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.
 

-- 
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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

[Matthieu Pizenberg]

>
> - 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.

-- 
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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

[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.
   

-- 
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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

[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
 wrote:
> 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 
> email to elm-discuss+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

-- 
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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

[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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

[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. 

On Sunday, May 7, 2017 at 11:58:26 PM UTC-4, Matthieu Pizenberg wrote:
>
> 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?*
>

-- 
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 email 
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.