From 838e627461f58181bb69fd3828a161bc88b97e6d Mon Sep 17 00:00:00 2001
From: Fabrizio Ferrai <fabrizio.ferrai@gmail.com>
Date: Fri, 18 Jan 2019 15:33:15 +0200
Subject: [PATCH] =?UTF-8?q?0.6.2=20=E2=86=92=200.6.3=20(#78)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md    | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 package.yaml |  2 +-
 2 files changed, 86 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 127c1db89..10fedd535 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,8 @@ PureScript package manager and build tool powered by [Dhall][dhall] and
   - [Configuration file format](#configuration-file-format)
 - [Commands](#commands)
   - [Package management](#package-management)
+    - [Listing available packages](#listing-available-packages)
+    - [Adding and overriding dependencies](#adding-and-overriding-dependencies)
   - [Building, bundling and testing a project](#building-bundling-and-testing-a-project)
 - [Can I use this with `psc-package`?](#can-i-use-this-with-psc-package)
   - [`psc-package-local-setup`](#psc-package-local-setup)
@@ -78,7 +80,9 @@ This last command will create a bunch of files:
 ```
 
 Convention note: `spago` expects your source files to be in `src/` and your
-test files in `test/`.
+test files in `test/`.  
+It is possible to include additional source paths when running some commands,
+like `build`, `test` or `repl`.
 
 Let's take a look at the two [Dhall][dhall] configuration files that `spago` requires:
 - `packages.dhall`: this file is meant to contain the *totality* of the packages
@@ -152,6 +156,70 @@ $ spago install
 ..then `spago` will download all the `dependencies` listed in `spago.dhall` (and
 store them in the `.spago` folder).
 
+#### Listing available packages
+
+It is sometimes useful to know which packages are contained in our package set 
+(e.g. to see which version we're using, or to search for packages).
+
+You can get a complete list of the packages your `packages.dhall` imports (together
+with their versions and URLs) by running:
+
+```bash
+$ spago list-packages
+```
+
+#### Adding and overriding dependencies
+
+Let's say I'm a user of the `react-basic` package. Now, let's say I stumble upon a bug
+in there, but thankfully I figure how to fix it. So I fork it, add my fix, and push
+to my fork.  
+Now if I want to use this fork in the current project, how can I tell `spago` to do it?
+
+We have a `overrides` record in `packages.dhall` just for that! And in this case it
+might look like this:
+
+```haskell
+let overrides =
+      { react-basic =
+            upstream.react-basic
+          ⫽ { repo =
+                "https://github.com/my-user/purescript-react-basic.git"
+            , version =
+                "my-branch-with-the-fix"
+            }
+      }
+```
+
+Note: currently support only branches and tags work as a `version`, and tags are
+recommended over branches (as for example if you push new commits to a branch,
+`spago` won't pick them up unless you delete the `.spago` folder).  
+Commit hashes are not supported yet, but hopefully will be at some point.
+
+If a package is not in the upstream package-set, you can add it in a similar way,
+by changing the `additions` record in the `packages.dhall` file.  
+E.g. if we want to add the `facebook` package:
+
+```haskell
+let additions =
+  { facebook =
+      mkPackage
+        [ "console"
+		, "aff"
+		, "prelude"
+		, "foreign"
+		, "foreign-generic"
+		, "errors"
+		, "effect"
+        ]
+		"https://github.com/Unisay/purescript-facebook.git"
+        "v0.3.0"
+  }
+```
+
+Once you verify that your application builds with the added packages, we would of
+course very much love if you could pull request it to the Upstream package-set,
+[spacchetti][spacchetti] ❤️🍝
+
 ### Building, bundling and testing a project
 
 We can then build the project and its dependencies by running:
@@ -203,7 +271,7 @@ Bundling first...
 Bundle succeeded and output file to index.js
 Make module succeeded and output file to index.js
 
-> node -e "console.log(require('./index).main)"
+$ node -e "console.log(require('./index).main)"
 [Function]
 ```
 
@@ -217,6 +285,16 @@ You should add some tests.
 Tests succeeded.
 ```
 
+And last but not least, you can spawn a PureScript repl!  
+As with the `build` and `test` commands, you can add custom source paths
+to load, and pass options to the underlying `purs repl` by just putting
+them after `--`.  
+E.g. the following opens a repl on `localhost:3200`:
+
+```bash
+$ spago repl -- --port 3200
+```
+
 ## Can I use this with `psc-package`?
 
 Yes! Though the scope of the integration is limited to helping your
@@ -270,6 +348,11 @@ leave the `require`s still in.
 To fill them in you should use the proper js tool of the day, at the time of
 writing [ParcelJS][parcel] looks like a good option.
 
+> So I added a new package to the `packages.dhall`, why is `spago` not installing it?
+
+Adding a package to the package-set just includes it in the set of possible packages you
+can depend on. However if you wish `spago` to install it you should then add it to
+the `dependencies` list in your `spago.dhall`.  
 
 [spacchetti]: https://github.com/spacchetti/spacchetti
 [dhall]: https://github.com/dhall-lang/dhall-lang
diff --git a/package.yaml b/package.yaml
index a55431226..77f1bce4c 100644
--- a/package.yaml
+++ b/package.yaml
@@ -1,5 +1,5 @@
 name:                spago
-version:             0.6.2.1
+version:             0.6.3.0
 github:              "spacchetti/spago"
 license:             BSD3
 author:              "Justin Woo, Fabrizio Ferrai"