Merge pull request #263 from JordanMartinez/development

Make next minor release: ps-0.12.x-v0.11.1

.travis.yml

@@ -74,6 +74,6 @@ cache:
     - 21-Hello-World/07-Type-Level-Programming/output
     - 21-Hello-World/08-Application-Structure/.psc-package
     - 21-Hello-World/08-Application-Structure/output
-    - 21-Hello-World/09-Projects/.psc-package
-    - 21-Hello-World/09-Projects/output
-    - 21-Hello-World/09-Projects/node_modules
+    - 22-Projects/.psc-package
+    - 22-Projects/output
+    - 22-Projects/node_modules

00-Getting-Started/ReadMe.md

@@ -14,13 +14,10 @@ This question can be answered by explaining three things:
 
 ### Why one should use Javascript to build programs...
 
-TODO, but the general idea:
 - The web browser is the new ["dumb terminal"](https://www.youtube.com/embed/YI34UIMgkxs?start=1762&end=1828) / platform-independent OS:
     - [What can web do today?](https://whatwebcando.today/)
-- Progressive web applications are better than native web apps in a few important ways
-- WebAssembly
-- The points mentioned in this article: [Learn Javascript in 2018](https://hackernoon.com/learn-to-code-in-2018-get-hired-and-have-fun-along-the-way-b338247eed6a)
 - [Why Founders Should Start With a Website, Not a Mobile App](https://www.atrium.co/blog/founders-should-build-website-not-mobile-app/)
+- The points mentioned in this article: [Learn Javascript in 2018](https://hackernoon.com/learn-to-code-in-2018-get-hired-and-have-fun-along-the-way-b338247eed6a)
 
 ### ...but not write Javascript to build it...
 
@@ -43,6 +40,7 @@ TODO, but the general idea is:
 
 TODO, but the general idea is:
 - Paradigm shifts, such as the one demonstrated by this video using C++, are what enable programs with less problems: [Logging a function's name each time it is called: migrating an OO solution to an FP solution](https://www.youtube.com/embed/i9CU4CuHADQ?start=540)
+- [JavaScript, TypeScript, and PureScript](https://www.youtube.com/watch?v=JTEfpNtEoSA) or "Why TypeScript only 'pretends' to have types."
 - [Purescript: Tomrrow's Javascript Today](https://www.youtube.com/watch?time_continue=22&v=5AtyWgQ3vv0)
 - [Phil Freeman's post: 'Why You Should Use PureScript'](https://gist.github.com/paf31/adfd15fbb1ac8b99fc68be2c9aca8427)
 - type-level programming
@@ -90,12 +88,7 @@ PureScript supports a number of features (e.g. powerful type system) that simply
 
 To fully support this claim, it would help to compare various ecosystem's "features." Unfortunately, since I'm not familiar with every other language mentioned, it's very difficult for me to do that.
 
-In addition, PureScript can compile to other languages besides Javascript. That means you can write the same code to solve your business problem and run it on multiple platforms besides `Node.js` or the Browser, depending on which one is the best fit for your purposes:
-- [Pure-C (C)](https://github.com/pure-c/purec)
-- [Purescript Native (C++)](https://github.com/andyarvanitis/purescript-native)
-    - See [How to create 3D Games with PureScript Native and C++](https://twitter.com/lettier/status/1074863932328853505)
-- [Erlang](https://github.com/purerl/purescript)
-- [Swift](https://github.com/paulyoung/pureswift)
+In addition, PureScript can compile to other languages besides Javascript. That means you can write the same code to solve your business problem and run it on multiple platforms besides `Node.js` or the Browser, depending on which one is the best fit for your purposes. For a complete listing, as well as how ready they are for production, see [Alternate Backends](https://github.com/purescript/documentation/blob/master/ecosystem/Alternate-backends.md).
 
 #### If I learn PureScript, can I get a good developer job?
 

01-Build-Tools/01-Tool-Comparisons/01-Dependency-Managers.md

@@ -2,15 +2,15 @@
 
 ## Why doesn't Purescript use `npm`?
 
-The following provides a much shorter explanation of [this article](https://harry.garrood.me/blog/purescript-why-bower/)
+The following provides a much shorter explanation of [Why the PureScript Community Uses Bower](https://harry.garrood.me/blog/purescript-why-bower/)
 
 Short answer:
-- Because NPM doesn't produce a compiler error when multiple versions of the same transitive dependency are used.
+- Because NPM doesn't produce an error when multiple versions of the same transitive dependency are used.
 
 Long answer:
-- When package `foo` requires `bar v1.0.0` and package `baz` requires `bar v2.0.0`, NPM, will "nest" the packages, so that they will compile
-- Should one or both packages export something that exposes `bar` and our code uses it, this will produce a runtime error, either because some API doesn't exist (e.g. one version changed/removed some API) or because a pattern match didn't work (e.g. an `instanceOf` check failed due to seeing different `data Bar` types)
-- Bower (the 'official' version) uses "flat" dependencies, so we get the compile error when this situation arises. How? It'll ask you what you want to do to resolve the issues. Rather than decide one over the other, you pull out and rethink through your dependencies.
+- When package `child1` requires `parent v1.0.0` and package `child2` requires `parent v2.0.0`, NPM, will "nest" the packages, so that the code will compile.
+- Should one or both packages export something that exposes `parent` and our code uses it, this will produce a runtime error, either because some API doesn't exist (e.g. one version changed/removed some API) or because a pattern match didn't work (e.g. an `instanceOf` check failed due to seeing different types defined in the `parent` package)
+- Bower uses "flat" dependencies, so it will notify you that such an issue exists by asking you to choose the library version you want to use to resolve the issue.
 
 However, `bower` isn't the only package manager one can use. `psc-package` is also used throughout the community.
 
@@ -32,15 +32,41 @@ Those names, plus these flowcharts, will help one get an overview of how they wo
 
 Now for a side-by-side comparison (an "apples to oranges" comparison)
 
-| | Bower | Psc-Package |
+| | Bower | Psc-Package/Spago |
 | - | - | - |
-| Design Goals | ? | [See this summary](https://github.com/purescript/psc-package#design-goals)
-| Official/Unofficial | Official<br>(parts of `purs` depend on it) | Unofficial
+| Ideal User | <ul><li>Library Developers</li><li>People exploring the language/ecosystem</li></ol> | <ul><li>Application Developers</li><li>People learning the language via a CI-proven learning material</li></ul> |
+| Official/Unofficial | Official<br>(parts of the PureScript compiler depend on it) | Unofficial
 | Trajectory | Moving away? | Moving towards?
-| Pros | <ul><li>**Bower is required for one to publish docs to [Pursuit](https://pursuit.purescript.org/)**</li><li>Bower caches its dependencies, so you can download a version of a package only once and use it everywhere on your system</li><li>It's the "official" dependency manager for Purescript</li></ul> | <ul><li>**Defines a set of versions of specific packages that are proven via CI to work together**</li><li>Uses Git to work, which is usually already installed on all systems</li><li>Reliably produces reproducible Purescript dependencies</li><li>Reduces verbosity somewhat by omitting the `purescript-` prefix on PureScript packages</li></ul>
-| Cons | <ul><li>**Figuring out which version of a package works with another version of a package is needlessly time-consuming**</li><li>Uses node to work, which may not be installed on all systems</li><li>Doesn't always produce reproducible dependencies due to its caching feature.</li></ul> | <ul><li>If developing a library, one cannot publish docs to Pursuit without Bower. (If developing an end-user app, this doesn't matter.)</li><li>Uses more storage space due to duplicating code when one has multiple projects across their system.</li><li>Not the "official" package manager (but who really determines what is 'official' anyway?)</li><li>If the standard package set does not have some package in it, one must maintain their own copy.^^ (However, [Spachetti](https://github.com/justinwoo/spacchetti) makes it easier to deal with this. [Read its guide](https://spacchetti.readthedocs.io/en/latest/))</li></ul>
+| Design Goals | ? | [See this summary](https://github.com/purescript/psc-package#design-goals)
+| Pros | <ul><li>**Bower is required for one to publish a library's docs to [Pursuit](https://pursuit.purescript.org/)**</li><li>Bower caches its dependencies, so you can download a version of a package only once and use it everywhere on your system</li><li>It's the "official" dependency manager for Purescript</li></ul> | <ul><li>**One never experiences the aforementioned "transitive dependency conflicts"**</li><li>Uses Git to work, which is usually already installed on all systems</li><li>Reliably produces reproducible Purescript dependencies</li><li>Reduces verbosity somewhat by omitting the `purescript-` prefix on PureScript packages</li></ul>
+| Cons | <ul><li>**When a recent compiler release has been made, one will encounter the 'transitive dependency' issue above quite frequently until all the libraries in the ecosystem are updated to the new release. Figuring out which version of a package works with another wastes a lot of time.**</li><li>Uses node to work, which may not be installed on all systems</li><li>Doesn't always produce reproducible dependencies due to its caching feature.</li></ul> | <ul><li>**One cannot publish a library's docs to Pursuit.**</li><li>Uses more storage space due to duplicating code when one has multiple projects across their system.</li><li>If the standard package set does not have some package in it, one must maintain their own copy or learn how to use [Spacchetti](https://github.com/spacchetti/spacchetti)/[Spago](https://github.com/spacchetti/spago).</li></ul>
+
+## Bower: Addressing Common Problems
+
+### The Solution to Most Bower Problems
+
+At various times, you might encounter a problem with Bower due to its cache mechanism. When in doubt, run the following command and see if that fixes your issue:
+```bash
+# Deletes the 'bower_components' and 'output' directories,
+# ensuring that the cache mechanism is not corrupting your build
+# and that the next build will be completely fresh.
+rm -rf bower_components/ output/
+```
+
+### A Note on Breaking Compiler Changes
+
+The following issue is happening less and less frequently due to the PureScript language stabilizing, but it still needs to be stated.
+
+#### Annoyance Defined
+
+If a compiler release that includes breaking changes was released recently, it will take some time for libraries in the ecosystem to become compatible with that release. If you are using Bower as your dependency manager, it may try to install libraries that are and are not compatible with the new release, creating problems.
+
+#### Recommended Guidelines
 
-^^ This is explained later in this folder ("Create Local Custom Package Set.md")
+In such circumstances, follow these guidelines to help find the correct version of a library:
+- Go to Pursuit and look at the library's package page. Choose one of the library's versions and compare that version's publish date with the date of the compiler release. Those that occur after the compiler release are likely compatible with the new release.
+- Since `purescript-prelude` is a dependency for most libraries, see which version of `purescript-prelude` the library uses. That should indicate whether it's compatible with a new compiler release or not.
+- If all else fails, check the library's last few commit messages in its repository for any messages about updating to the new compiler release.
 
 ### Why Spacchetti?
 
@@ -58,7 +84,7 @@ A **package set** consists of a set of packages. It's a JSON file that maps a pa
 
 #### The Cause of the Pain Point
 
-When using Bower, you have no idea whether a package (code that was released at some tag) will compile with some other package. AFAIK, Phil Freeman (creator of PureScript) and others created `psc-package` to fix this problem. Currently, Justin Woo maintains it.
+When using Bower, you have no idea whether a package (code that was released at some tag) will compile with some other package. This pain point arises most often when a breaking changes compiler release is made. AFAIK, Phil Freeman (creator of PureScript) and others created `psc-package` to help fix this problem / start migrating to a non-Bower solution. Currently, Justin Woo maintains it.
 
 Justin has defined [an "official" / "standard" package set](https://github.com/purescript/package-sets/blob/master/packages.json) that `psc-package` uses to download and compile one's dependencies. Why? So that he can prove via CI that all the packages in the set work/compile together without issue. This addresses the pain point from Bower. Moreover, it also stops each developer who uses `psc-package` from wasting time verifying the same package set locally as it can be done only once in Justin's repo.
 

01-Build-Tools/05-Continuous-Integration.md

@@ -1,5 +1,9 @@
 # Continuous Integration
 
-See Justin's RTD project for the following CI setups. However, **look at the linked examples he used to create the below pages' examples, since they are likely more up-to-date than the page's examples**:
-- Works with hacks - [Travis CI](https://purescript-resources.readthedocs.io/en/latest/travis.html)
-- Works with less/no hacks - [Azure CI](https://purescript-resources.readthedocs.io/en/latest/azure-pipelines.html)
+| To use... | ... with this dependency manager... | ... see this file/article |
+| - | - | - |
+| Travis CI | `psc-pacakge`/`spacchetti` | This repo's [.travis.yml](../.travis.yml) and its [.travis/](../.travis/) folder. See also Justin's RTD article: [Travis CI](https://purescript-resources.readthedocs.io/en/latest/travis.html)^^
+| Travis CI | `bower` | ???
+| Azure CI | `psc-package` | See also Justin's RTD article: [Azure CI](https://purescript-resources.readthedocs.io/en/latest/azure-pipelines.html)^^
+
+^^ Look at the linked examples Justin uses as they are more up-to-date than the page's examples.

11-Syntax/03-Type-Level-Programming-Syntax/src/02-Basic-Syntax/03-Defining-Functions/ReadMe.md

@@ -152,7 +152,7 @@ The issue lies in step 2: the instance head is checked before the instance conte
 "Backtracking" could be implemented in the compiler by using instance guards, but this has not yet been done. For the current progress on this issue, see [the related Purescript issue](https://github.com/purescript/purescript/issues/3120).
 
 To understand unification at a deeper level, see these links:
-- [Type Checking](https://www.youtube.com/watch?v=r030JkmMLMI). This video **quickly** explains some of the notation used in the paper below, but not all of it.
+- [Type Inference from Scratch](https://www.youtube.com/watch?v=ytPAlhnAKro). This video explains the ideas behind the notation used in the paper below.
 - [Introduction to Type Inference](https://www.youtube.com/watch?v=il3gD7XMdmA). This video will explain a few more pieces of the notation used in the paper below as well as the problems that arise in type inference. Unfortunately, the teacher goes through concepts quickly and runs out of time, so not everything is immediately understandable through the first viewing.
 - [Phil's overview of the Purescript Type's System](https://www.youtube.com/embed/SPpIbiZFPRY?start=2258), where he shows how the compiler unifies types using the same notation above.
 - [The original paper describing instance chains](http://web.cecs.pdx.edu/~mpj/pubs/instancechains.pdf).

21-Hello-World/01-FP-Philosophical-Foundations/03-Data-Types.md

@@ -1,5 +1,9 @@
 ## Data Types
 
+### Algebraic Data Types
+
+Although this video's sound quality is horrible, it is still a very clear explanation behind the idea: [The Algebra of Algebraic Data Types](https://www.youtube.com/watch?v=YScIPA8RbVE)
+
 ### Principles
 
 In order to abide by the principle of pure functions, FP Data Types tend to adhere to two principles:

21-Hello-World/08-Application-Structure/src/02-MTL/15-The-ReaderT-Capability-Design-Pattern.md

@@ -96,3 +96,5 @@ main = do
   let globalEnvironmentInfo = -- mutable state, read-only values, etc.
   assert (runTest program globalEnvironmentInfo) == correctValue
 ```
+
+For another example, see [the Monad Reader Example](https://gist.github.com/rlucha/696ca604c9744ad11aff7d46b1706de7)

21-Hello-World/08-Application-Structure/src/03-Free/03-From-Free-to-Run/ReadMe.md

@@ -6,3 +6,5 @@ This folder will
 - explain what problem arises by using `Either`/`Coproduct`, the "closed" sum types
 - show how to make these effects more extensible by using `Variant`/`VariantF`, the "open" sum types
 - show how to combine `VariantF` and `Free` into a more-readable type via `Run`.
+
+As stated in [Free Programs, More Better Programs](reasonablypolymorphic.com/blog/freer-monads/index.html), PureScript's `Run` is the same idea behind Haskell's `Eff` monad. Moreover, The pre-`0.12.0` PureScript release's `Eff` monad that was later changed to `Effect` is not the same as Haskell's `Eff` monad, which is covered in that article.

21-Hello-World/08-Application-Structure/src/21-Modern-FP-Architecture.md

@@ -9,6 +9,7 @@ Now might be a good time to re-read these articles:
 - [the Capability Design Pattern](https://www.tweag.io/posts/2018-10-04-capability.html)
 - [A Modern Architecture for FP: Part 1](http://degoes.net/articles/modern-fp)
 - [A Modern Architecture for FP: Part 2](http://degoes.net/articles/modern-fp-part-2)
+- [Freer Monads, More Better Programs](reasonablypolymorphic.com/blog/freer-monads/index.html)
 
 ## Evaluating MTL and Free
 

21-Hello-World/Readme.md

@@ -60,12 +60,14 @@ Since Purescript is heavily inspired by and very similar to Haskell, one can lea
 | Action | Pros | Cons |
 | --- | --- | --- |
 | Read the documentation and source code for a type class and a few data types' implementations of said type classes | Free | Takes a lot of time; requires intuition to understand type class' usefulness / relation to others.
-| Read the relevant chapters from [Learn You a Haskell for Great Good](http://learnyouahaskell.com/chapters) | Free | I read elsewhere that it's "outdated". See [this Reddit comment's warning about learning from LYAHH](https://www.reddit.com/r/programming/comments/50m99l/new_edition_of_programming_in_haskell_now/d75pyxf/)
+| Read through the articles on or pay for training from [FP Complete's opinionated Haskell website](https://haskell.fpcomplete.com/) | Free / Paid | (Haven't done it so I don't know)
+| Read through the intermediate-level Haskell articles in the [`Applied Haskell 2018` GitHub Repo](https://github.com/fpco/applied-haskell#readme) | Free | (Haven't done it so I don't know)
 | Read through some of the free course materials taught by someone well informed about Haskell [here (you'll need to scroll towards the bottom)](https://github.com/bitemyapp/learnhaskell) | Free; more principled explanations | Looking at just slides without hearing someone teach using them is not usually as clear as when someone does teach using them or reading through a textbook on the same matter.
 | Read through the extremely lengthy ["What I wish I knew when learning Haskell"](http://dev.stephendiehl.com/hask/) site | Free; provides a better overview of basic to advanced topics | Very long; not necessarily deep and clear in its explanations
 | Read and do the exercises from [The Haskell Book](http://haskellbook.com/) | The "standard" for teaching Haskell and FP concepts in general: good explanations; good exercises; teaches "programming in the small" | Costs money; costs time; the exercises will stretch you
 | Read and do the exercises from [Haskell Cookbook](https://leanpub.com/haskellcookbook), and then its follow up book [Haskell Cookbook 2](https://leanpub.com/haskellcookbook2) | Free/Cheap; simpler than the Haskell book; gets to ideas faster; teaches "programming in the large" | May be harder for a new beginner (I haven't read it yet)
 | Watch the Intro to FP course on edX.org [here](https://www.edx.org/course/introduction-functional-programming-delftx-fp101x-0) | Free (or paid) | (Haven't done it so I don't know)
+| Read the relevant chapters from [Learn You a Haskell for Great Good](http://learnyouahaskell.com/chapters) | Free | I read elsewhere that it's "outdated". See [this Reddit comment's warning about learning from LYAHH](https://www.reddit.com/r/programming/comments/50m99l/new_edition_of_programming_in_haskell_now/d75pyxf/)
 
 ### Miscellaneous Links