Adds the workspace documentation

Author: Maël Nison

_data/guides.yml

@@ -204,6 +204,13 @@
   - id: docs_prune_offline_mirror
     path: /docs/prune-offline-mirror
 
+- id: docs_workspaces
+  title: docs_workspaces_title
+  description: docs_workspaces_description
+  pages:
+  - id: docs_workspaces
+    path: /docs/workspaces
+
 - id: yarn_organization
   title: yarn_organization_title
   description: yarn_organization_description

_data/i18n/en.yml

@@ -200,6 +200,11 @@ docs_offline_mirror_description: |
 
 docs_prune_offline_mirror: Pruning an Offline Mirror
 
+docs_workspaces: Workspaces
+docs_workspaces_title: Workspaces
+docs_workspaces_description: |
+  Link together your projects for easier maintenance.
+
 yarn_organization_title: Yarn Organization
 yarn_organization_description: |
   The Yarn organization is a collaboration of many companies and
@@ -349,7 +354,7 @@ script:
     display_all: Display all
     hide: Hide
 
-    not_found: 
+    not_found:
       whoa: Whoa, {package_name} does not exist yet
       yours: But that means it is now yours!
       make: Make your package

lang/en/docs/workspaces.md

@@ -0,0 +1,104 @@
+---
+id: docs_workspaces
+guide: docs_workspaces
+layout: guide
+---
+
+{% include vars.html %}
+
+Workspaces are a new way to setup your package architecture that's available by default starting from Yarn 1.0. It allows you to setup multiple packages in such a way that you only need to run `yarn install` once to install all of them in a single pass.
+
+### Why would you want to do this?
+
+- Your dependencies can be linked together, which means that your workspaces can depend on one another while always using the most up-to-date code available. This is also a better mechanism than `yarn link` since it only affects your workspace tree rather than your whole system.
+
+- All your project dependencies will be installed together, giving Yarn more latitude to better optimize them.
+
+- Yarn will use a single lockfile rather than a different one for each project, which means less conflicts and easier reviews.
+
+### How to use it?
+
+Add the following in a `package.json` file. Starting from now on, we'll call this directory the "workspace root":
+
+**package.json**
+
+```json
+{
+    "private": true,
+    "workspaces": [
+        "workspace-a",
+        "workspace-b"
+    ]
+}
+```
+
+Note that the `private: true` is required! Workspaces are not meant to be published, so we've added this safety measure to make sure that nothing can accidentaly expose them.
+
+After this file has been created, create two new subfolders named `workspace-a` and `workspace-b`. In each of them, create another `package.json` file with the following content:
+
+**workspace-a/package.json:**
+
+```json
+{
+    "name": "workspace-a",
+    "version": "1.0.0",
+
+    "dependencies": {
+        "cross-env": "5.0.5"
+    }
+}
+```
+
+**workspace-b/package.json:**
+
+```json
+{
+    "name": "workspace-b",
+    "version": "1.0.0",
+
+    "dependencies": {
+        "cross-env": "5.0.5",
+        "workspace-a": "1.0.0"
+    }
+}
+```
+
+Finally, run `yarn install` somewhere, ideally inside the workspace root. If everything works well, you should now have a similar file hierarchy:
+
+```
+/package.json
+/yarn.lock
+
+/node_modules
+/node_modules/cross-env
+/node_modules/workspace-a -> /workspace-a
+
+/workspace-a/package.json
+/workspace-b/package.json
+```
+
+And that's it! Requiring `workspace-a` from a file located in `workspace-b` will now use the exact code currently located inside your project rather than what is published on Github, and the `cross-env` package has been correctly deduped and put at the root of your project to be used by both `workspace-a` and `workspace-b`.
+
+### How does it compare to Lerna?
+
+Yarn's workspaces are the low-level primitives that tools like Lerna can (and [do](https://github.com/lerna/lerna/pull/899)!) use. They will never try to support the high-level feature that Lerna offers, but by implementing the core logic of the resolution and linking steps inside Yarn itself we hope to enable new usages and improve performance.
+
+### Tips & Tricks
+
+  - The `workspaces` field is an array containing the paths to each workspace. Since it might be tedious to keep track of each of them, this field also accepts glob patterns! For example, Babel reference all of their packages through a single `packages/*` directive.
+
+  - Workspaces are stable enough to be used in large-scale applications and shouldn't change anything to the way the regular installs work, but if you think they're breaking something, you can disable them by adding the following line into your Yarnrc file:
+
+    ```
+    workspaces-experimental false
+    ```
+
+### Limitations & Caveats
+
+  - The package layout will be different between your workspace and what your users will get (the workspace dependencies will be hoisted higher into the filesystem hierarchy). Making assumptions about this layout was already hazardous since the hoisting process is not standardized, so theoretically nothing new here.
+
+  - In the example above, if `workspace-b` depends on a different version than the one referenced in `workspace-a`'s package.json, the dependency will be installed from Github rather than linked from your local filesystem. This is because some packages actually need to use the previous versions in order to build the new ones (Babel is one of them).
+
+  - Workspaces must be children of the workspace root in term of folder hierarchy. You cannot and must not reference a workspace that is located outside of this filesystem hierarchy.
+
+  - Nested workspaces are not supported at this time.