proposal: Prohibit external packages

[HajagosNorbert]

Writing the simulation chapter, I'm currently using an external pseudo-random package. Obviously I don't want to implement it while teaching simulations, so a package is needed in this case. That begs the question: How should we handle packages? I have 2 related proposals:

1. We should restrict the use of packages to those that are created in one of the chapters. (I know there will be a chapter on PRNG, so simulation would be covered) I suspect the reader would find great satisfaction in using his/her own implementation of a package. That way, every used line of Roc code would be explained in the book. If an external package is needed to implement a chapter's code, that package needs explaining as well in one of the chapters. That being said, we can't expect the reader to first write the package code and then use it. Some may do it, others won't, so the packages need to be hosted somewhere.

2. This github repo should host the package releases which would be used by other chapters. External packages imported from an url are fragile, especially if those urls are out of our control. Those urls will be physically printed out, so they should strive to be as stable as the page they are written onto. Hosting them under roc-lang's github would yield us more control and also make things be in a single place.

Related question to the 2. point of the proposal:

I know little about Roc packages, but I think they need to have a pre-defined structure. Adhering to that structure while teaching a concept inside a chapter could be distracting to the learner (but I don't know by how much). Should the hosted packages be the same as the content of the chapters, or should the chapters focus on teaching the concept in expense of not being a proper package that the user could import locally, thus later in a different chapter needing to import it from a url regardless if he/she has written it already?

Note: By packages, I mean Roc packages, not platform packages.

[jwoudenberg]

I was thinking of using roc-json in the CI chapter. I probably can use another serialization/deserialization format instead if a chapter gets written for one (given some constraints). I'm not entirely clear on the value though, and do see some downsides in terms of dependencies between chapters we'd introduce both for ourselves as we're writing and readers.

I do think we should avoid relying on libraries for solving the interesting parts of the problem each chapter is about. I think using a package for commodity functionality like JSON parsing or random number generation is fine though!

[jwoudenberg]

I want to add, in referring to JSON parsing or random number generation as commodity functionality I was thinking as a user of a library providing that functionality. I know a lot of work and thinking goes into building one!

[nathanielknight]

I would agree that we don't necessarily want the book to be hermetic, and we want to think about providing:

• a link to most up-to-date version of the library (for someone reading in a few years who needs a JSON decoder)
• a link to the version of the library used for the chapter (for a reader who wants the source code/documentation)
• a stable link to the files needed to run the code (so that code examples continue to work)

GitHub releases or signed tarballs on the book's website might work okay for the last point?

[Anton-4]

Github releases work well, we also have a github action that can take care of the whole release process.

[Anton-4]

I'm not entirely clear on the value though, and do see some downsides in terms of dependencies between chapters we'd introduce both for ourselves as we're writing and readers. I do think we should avoid relying on libraries for solving the interesting parts of the problem each chapter is about. I think using a package for commodity functionality like JSON parsing or random number generation is fine though!

I agree with this.

[Anton-4]

External packages imported from an url are fragile, especially if those urls are out of our control.

I think all external packages we currently use were authored by people who collaborate on the book, so that seems acceptable to me.

[HajagosNorbert]

Alright, I can get behind these arguments. If a package built within a chapter is suitable for other chapters (like I assume the random package will be), I would use that instead of a community package that may be more mature and feature complete. In that case that package would need a Github release.

What is your opinion, would it be better to do it that way, or stick to a more realistic scenario, in which a more accepted package is used? (Thus eliminating the need of releasing the chapter packages)

[Anton-4]

I would use that instead of a community package that may be more mature and feature complete.

Yeah sounds good, the user will already be familiar with that API :+1:

[gvwilson]

Thank you all for the discussion - I'll flag this to be voted on for the 2024-04-10 meeting.