Re: [elm-discuss] Re: Best practices to create examples for an elm package?
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?
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?
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?
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?
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?
> 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?
> > - 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?
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?
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. On May 8, 2017 7:38 AM, "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.
Re: [elm-discuss] Re: Best practices to create examples for an elm package?
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?
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?
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.