Update comments

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+Other improvements:
+- Docs: updated package addition/overriding syntax to use `with` syntax (#661)
+
 ## [0.15.3] - 2020-06-15
 
 New features:

README.md

@@ -444,9 +444,9 @@ In this case we override the package with its local copy, which must have a `spa
 It might look like this:
 
 ```haskell
-let overrides =
-      { simple-json = ../purescript-simple-json/spago.dhall as Location
-      }
+let upstream = -- <package set URL here>
+in  upstream
+  with simple-json = ../purescript-simple-json/spago.dhall as Location
 ```
 
 Note that if we do `spago ls packages`, we'll see that it is now included as a local package:
@@ -477,13 +477,10 @@ In this case, we can just change the override to point to some commit of our for
 
 
 ```haskell
-let overrides =
-    { simple-json =
-          upstream.simple-json
-       // { repo = "https://github.com/my-user/purescript-simple-json.git"
-          , version = "701f3e44aafb1a6459281714858fadf2c4c2a977"
-          }
-    }
+let upstream = -- <package set URL here>
+in  upstream
+  with simple-json.repo = "https://github.com/my-user/purescript-simple-json.git"
+  with simple-json.verison = "701f3e44aafb1a6459281714858fadf2c4c2a977"
 ```
 
 **Note**: you can use a "branch", a "tag" or a "commit hash" as a `version`.
@@ -499,32 +496,33 @@ by changing the `additions` record in the `packages.dhall` file.
 E.g. if we want to add the `facebook` package:
 
 ```haskell
-let additions =
-  { facebook =
-      { dependencies =
-          [ "console"
-          , "aff"
-          , "prelude"
-          , "foreign"
-          , "foreign-generic"
-          , "errors"
-          , "effect"
-          ]
-      , repo =
-          "https://github.com/Unisay/purescript-facebook.git"
-      , version =
-          "v0.3.0"  -- branch, tag, or commit hash
-      }
-  }
+let upstream = -- <package set URL here>
+in  upstream
+  with facebook =
+    { dependencies =
+        [ "console"
+        , "aff"
+        , "prelude"
+        , "foreign"
+        , "foreign-generic"
+        , "errors"
+        , "effect"
+        ]
+    , repo =
+        "https://github.com/Unisay/purescript-facebook.git"
+    , version =
+        "v0.3.0"  -- branch, tag, or commit hash
+    }
 ```
 
 As you might expect, this works also in the case of adding local packages:
 
 Example:
 
 ```haskell
-let additions =
-  { foobar = ../foobar/spago.dhall as Location
+let upstream = -- <package set URL here>
+in  upstream
+  with foobar = ../foobar/spago.dhall as Location
   }
 ```
 
@@ -620,13 +618,9 @@ Then:
 
 ```dhall
 let upstream = https://github.com/purescript/package-sets/releases/download/psc-0.13.4-20191025/packages.dhall sha256:f9eb600e5c2a439c3ac9543b1f36590696342baedab2d54ae0aa03c9447ce7d4
-
-let overrides =
-  { lib1 = ./lib1/spago.dhall as Location
-  , lib2 = ./lib2/spago.dhall as Location
-  }
-
-in upstream // overrides
+in upstream
+  with lib1 = ./lib1/spago.dhall as Location
+  with lib2 = ./lib2/spago.dhall as Location
 ```
 
 - `lib1/spago.dhall` might look something like this:
@@ -1256,7 +1250,7 @@ type) of the files that `spago` expects. Let's define them in Dhall:
 let Package =
   { dependencies : List Text  -- the list of dependencies of the Package
   , repo = Text               -- the address of the git repo the Package is at
-  , version = Text            -- git tag
+  , version = Text            -- git tag, branch, or commit hash
   }
 
 -- The type of `packages.dhall` is a Record from a PackageName to a Package

templates/packages.dhall

@@ -31,28 +31,24 @@ Purpose:
     the package set's repo
 
 Syntax:
-Replace the overrides' "{=}" (an empty record) with the following idea
-The "//" or "⫽" means "merge these two records and
-  when they have the same value, use the one on the right:"
+where `entityName` is one of the following:
+- dependencies
+- repo
+- version
 -------------------------------
-let overrides =
-  { packageName =
-      upstream.packageName // { updateEntity1 = "new value", updateEntity2 = "new value" }
-  , packageName =
-      upstream.packageName // { version = "v4.0.0" }
-  , packageName =
-      upstream.packageName // { repo = "https://www.example.com/path/to/new/repo.git" }
-  }
+let upstream = --
+in  upstream
+  with packageName.entityName = "new value"
 -------------------------------
 
 Example:
 -------------------------------
-let overrides =
-  { halogen =
-      upstream.halogen // { version = "master" }
-  , halogen-vdom =
-      upstream.halogen-vdom // { version = "v4.0.0" }
-  }
+let upstream = --
+in  upstream
+  with halogen.version = "master"
+  with halogen.repo = "https://example.com/path/to/git/repo.git"
+
+  with halogen-vdom.version = "v4.0.0"
 -------------------------------
 
 ### Additions
@@ -61,37 +57,30 @@ Purpose:
 - Add packages that aren't already included in the default package set
 
 Syntax:
-Replace the additions' "{=}" (an empty record) with the following idea:
+where `<version>` is:
+- a tag (i.e. "v4.0.0")
+- a branch (i.e. "master")
+- commit hash (i.e. "701f3e44aafb1a6459281714858fadf2c4c2a977")
 -------------------------------
-let additions =
-  { package-name =
-       { dependencies =
-           [ "dependency1"
-           , "dependency2"
-           ]
-       , repo =
-           "https://example.com/path/to/git/repo.git"
-       , version =
-           "tag ('v4.0.0') or branch ('master')"
-       }
-  , package-name =
-       { dependencies =
-           [ "dependency1"
-           , "dependency2"
-           ]
-       , repo =
-           "https://example.com/path/to/git/repo.git"
-       , version =
-           "tag ('v4.0.0') or branch ('master')"
-       }
-  , etc.
-  }
+let upstream = --
+in  upstream
+  with new-package-name =
+    { dependencies =
+       [ "dependency1"
+       , "dependency2"
+       ]
+    , repo =
+       "https://example.com/path/to/git/repo.git"
+    , version =
+        "<version>"
+    }
 -------------------------------
 
 Example:
 -------------------------------
-let additions =
-  { benchotron =
+let upstream = --
+in  upstream
+  with benchotron =
       { dependencies =
           [ "arrays"
           , "exists"
@@ -113,16 +102,10 @@ let additions =
       , version =
           "v7.0.0"
       }
-  }
 -------------------------------
 -}
 
-
 let upstream =
       https://github.com/purescript/package-sets/releases/download/psc-0.13.8-20200615/packages.dhall sha256:5d0cfad9408c84db0a3fdcea2d708f9ed8f64297e164dc57a7cf6328706df93a
 
-let overrides = {=}
-
-let additions = {=}
-
-in  upstream // overrides // additions
+in  upstream

test/SpagoSpec.hs

@@ -80,7 +80,7 @@ spec = around_ setup $ do
       -- We don't want fixture for packages.dhall to avoid having to maintain upstream package-set URL in fixture
       dhallSource <- readTextFile "packages.dhall"
       dhallSource `shouldNotSatisfy` (Text.isInfixOf "{-") -- comments not present
-      dhallSource `shouldSatisfy` (Text.isInfixOf "let overrides = {=}") -- some dhall stuff is present
+      dhallSource `shouldSatisfy` (Text.isInfixOf "let upstream") -- some dhall stuff is present
 
   describe "spago install" $ do