From 734857d3bfd8a469f8e323d46ef130fb7a07fc2d Mon Sep 17 00:00:00 2001
From: Nolan Lawson <nolan@nolanlawson.com>
Date: Sun, 10 Feb 2019 11:30:00 -0800
Subject: [PATCH] docs: add documentation about 1.0.0 yarn changes (#959)

[skip ci]
---
 BREAKING_CHANGES.md | 17 +++++++++++++++++
 Dockerfile          |  2 +-
 README.md           |  8 +++++---
 3 files changed, 23 insertions(+), 4 deletions(-)
 create mode 100644 BREAKING_CHANGES.md

diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md
new file mode 100644
index 00000000..48369595
--- /dev/null
+++ b/BREAKING_CHANGES.md
@@ -0,0 +1,17 @@
+# Breaking changes
+
+This document contains a list of _breaking changes_ for Pinafore. For a full changelog, see [the GitHub release page](https://github.com/nolanlawson/pinafore/releases).
+
+## 1.0.0
+
+**Breaking change:** This version [switches Pinafore from npm to yarn](https://github.com/nolanlawson/pinafore/pull/927). Those who self-host Pinafore will need to make the following changes:
+
+1. [Install yarn](https://yarnpkg.com/en/docs/install) if you haven't already.
+2. Instead of `npm install`, run `yarn --pure-lockfile`.
+
+This change fixes [a functional bug in Webpack](https://github.com/nolanlawson/pinafore/pull/926). If you use npm instead of yarn, Pinafore may not build correctly.
+
+### Notes:
+
+- Using `yarn start` instead of `npm start` should not make a difference.
+- Those using Docker shouldn't need to change anything.
diff --git a/Dockerfile b/Dockerfile
index 84f7c1a0..564abf7b 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -14,7 +14,7 @@ RUN npm i yarn -g
 
 # Install Pinafore
 RUN yarn --pure-lockfile
-RUN yarn run build
+RUN yarn build
 
 # Expose port 4002
 EXPOSE 4002
diff --git a/README.md b/README.md
index caa0b73f..b83d2a0e 100644
--- a/README.md
+++ b/README.md
@@ -56,9 +56,9 @@ Pinafore requires [Node.js](https://nodejs.org/en/) v8+ and [Yarn](https://yarnp
 
 To build Pinafore for production:
 
-    yarn
-    yarn run build
-    PORT=4002 npm start
+    yarn --pure-lockfile
+    yarn build
+    PORT=4002 yarn start
 
 ### Docker
 
@@ -96,6 +96,8 @@ how to run Pinafore in dev mode and run tests.
 
 For a changelog, see the [GitHub releases](http://github.com/nolanlawson/pinafore/releases/).
 
+For a list of breaking changes, see [https://github.com/nolanlawson/pinafore/blob/master/BREAKING_CHANGES.md](BREAKING_CHANGES.md).
+
 ## What's with the name?
 
 Pinafore is named after the [Gilbert and Sullivan play](https://en.wikipedia.org/wiki/Hms_pinafore). The [soundtrack](https://www.allmusic.com/album/gilbert-sullivan-hms-pinafore-1949-mw0001830483) is very good.