merging release/2.0

.circleci/config.yml

@@ -36,7 +36,7 @@ common_settings:
 
   full_build: &full_build
     name: Full Build
-    command: 'cp packages/venia-concept/.env.dist packages/venia-concept/.env && npm run build && npm run clean:dist'
+    command: 'cp packages/venia-concept/example.env packages/venia-concept/.env && npm run build && npm run clean:dist'
 
   test_result_path: &test_result_path
     path: "test-results"

.editorconfig

@@ -8,6 +8,9 @@ indent_style = space
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[{package.json,*.yml}]
+[{package.json,*.yml,*.md}]
 indent_size = 2
 indent_style = space
+
+[*.md]
+trim_trailing_whitespace = false

.eslintignore

@@ -1,4 +1,3 @@
 __fixtures__
 dist
 pwa-devdocs
-packages/venia-concept/web

.gitattributes

@@ -0,0 +1 @@
+package-lock.json -diff

.github/ISSUE_TEMPLATE.md

@@ -7,6 +7,8 @@
 [ ] `peregrine`
 [ ] `pwa-module`
 [ ] `pwa-devdocs`
+[ ] `upward-js`
+[ ] `upward-spec`
 
 ## This issue is a:
 

.gitignore

@@ -5,11 +5,9 @@ npm-debug.log
 coverage
 test-results
 dist
-packages/venia-concept/web
 storybook-dist
 .idea
 test-report.xml
 test-results.json
 lerna-debug.log
 .env
-packages/venia-concept/web

.prettierignore

@@ -1,6 +1,4 @@
 coverage
 package-lock.json
 dist
-web/js
 pwa-devdocs
-packages/venia-concept/web

README.md

@@ -44,39 +44,70 @@ All packages are versioned in a single repo, but released to `npm` as independen
 
 This repository includes the following packages:
 
-* [venia-concept](packages/venia-concept) - Reference/Concept Theme
+* [venia-concept](packages/venia-concept) - Reference/Concept Storefront
 * [pwa-buildpack](packages/pwa-buildpack/README.md) - Build tooling
 * [peregrine](packages/peregrine/README.md) - eCommerce Component Library
 * [pwa-module](packages/pwa-module)
 * [pwa-devdocs](packages/pwa-devdocs) - Project source for the [documentation site]
+* [upward-js](packages/upward-js) - Reference implementation of the UPWARD specification
+* [upward-spec](packages/upward-spec) - UPWARD specification and test suite
 
-## Install project dependencies
+## Quick Setup
+
+PWA Studio 2.0 requires much less setup than PWA Studio 1.0. The UPWARD architecture means that the Magento instance does not need to be configured to use your project as a theme. Instead, you connect to your Magento instance by simply specifying its URL in your environment.
+
+### Obtain Magento 2.3
+
+1. Make sure the Magento instance you're using is set to development mode, and has the latest 2.3.
+
+   * You need development mode for GraphQL introspection queries to work.
+   * The latest codebase will have the most up-to-date GraphQL schema.
+
+2. Ensure that the Venia sample data is installed on the Magento instance. (**TODO: painless instructions for the Composer commands to do that**)
+
+### Install Dependencies
 
 _**Note**: You must have a version of `node.js` >= `8.0.0`, and a version of `npm` >= `5.0.0`. The latest LTS versions of both are recommended._
 
 Follow these steps to install the dependencies for all the packages in the project:
 
-1.  Clone the repository
-2.  Navigate to the root of the repository from the command line
-3.  Run `npm install`
-4.  Watch the bootstrapping take place.
-5.  To run the Venia theme development experience, run `npm run watch:venia` from package root.
-6.  To run the full PWA Studio deeloper experience, with Venia hot-reloading and concurrent Buildpack/Peregrine rebuilds, run `npm run watch:all` from package root.
+1. Clone the repository.
+2. Navigate to the root of the repository from the command line
+3. Run `npm install`
+4. Watch the bootstrapping take place.
+5. Create a `packages/venia-concept/.env` file (or set environment variables manually)
+6. Set the environment variable `MAGENTO_BACKEND_DOMAIN` to the URL of the backing Magento instance you are using
+7. On your first install, run `npm run build` from package root.
+8. To run the Venia storefront development experience, run `npm run watch:venia` from package root.
+9.  To run the full PWA Studio developer experience, with Venia hot-reloading and concurrent Buildpack/Peregrine rebuilds, run `npm run watch:all` from package root.
+10.  To run the staging environment, which uses more compressed assets and more closely reflects production, run `npm run stage:venia` from package root. (This requires that you first run `npm run build` to generate the artifacts being served.)
 
-## Things not to do
+## Troubleshooting
 
-When using a monorepo and lerna, it's important that you break some common habits that are common when developing front-end packages.
+### When I run the developer mode, I get validation errors
+
+Make sure you have created a `.env` file in `packages/venia-concept` which specifies variables for your local development environment. You can copy from the template `packages/venia-concept/example.env`.
+
+### Venia queries to GraphQL produce validation errors
+
+Venia and its GraphQL queries may be out of sync with the schema of your connected Magento instance. Make sure the Magento instance is up to date with the 2.3 development branch, and your copy of this repository (or your dependency on it) is up to date.
+
+**To test whether your queries are up to date, run `npm run validate:venia:gql` at project root.**
+
+## Things not to do
 
-* Do _not_ run `npm install` to get `node_modules` up to date within any folder under `packages/`.
-  Instead, run `npm install` in the root of the repo, which will ensure all package's dependencies are up-to-date.
-* When adding a new entry to `devDependencies` in a package's `package.json`, ask yourself whether that dependency will be used across multiple packages.
-  If the answer is "yes," the dependency should instead be installed in the root `package.json`. This will speed up runs of `lerna bootstrap`.
+* Our monorepo is set up so that `npm install` can cross-link dependencies (such as Venia's dependency on Buildpack) without any extra tools. Do not run `lerna bootstrap`.
+* All devDependencies are installed in the repository root. This means that **all scripts must be run from repository root**; otherwise, the locally installed CLI commands they use will not be available.
+* Production dependencies are sometimes installed in child packages, but for some projects, such as Venia, it makes no sense to have production dependencies, because of bundling.
+* Don't check in a big change to `package-lock.json`, and don't check in any `package-lock.json` files but the root one.
+* Make sure to run `npm run prettier` and `npm run lint` before any commit you intend to push. You may want to set up a [Git hook] for this.
 
 [documentation site]: https://magento-research.github.io/pwa-studio/
 [CircleCI]: https://circleci.com/gh/magento-research/pwa-studio.svg?style=svg
 [Coverage Status]: https://coveralls.io/repos/github/magento-research/pwa-studio/badge.svg?branch=master
 [Greenkeeper badge]: https://badges.greenkeeper.io/magento-research/pwa-studio.svg
 [Contribution guide]: .github/CONTRIBUTING.md
+[Git hook]: <https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks>
 
 [mage2pratik]: https://github.com/mage2pratik
 [mage2pratik-image]: https://avatars0.githubusercontent.com/u/33807558?s=120&v=4

jest.config.js

@@ -4,6 +4,7 @@ module.exports = {
     projects: [
         'packages/peregrine',
         'packages/pwa-buildpack',
+        'packages/upward-js',
         'packages/venia-concept',
         'scripts'
     ],

lerna.json

@@ -1,17 +1,19 @@
 {
-    "version": "2.0.0-rc.1",
+    "version": "2.0.0-rc2.0.5",
     "packages": [
         "packages/peregrine",
         "packages/pwa-buildpack",
         "packages/pwa-devdocs",
+        "packages/upward-js",
+        "packages/upward-spec",
         "packages/venia-concept"
     ],
     "npmClient": "npm",
     "command": {
         "publish": {
             "ignoreChanges": [
                 "__tests__/**",
-                "pwa-module"
+                "pwa-devdocs"
             ]
         }
     }