Document our versioning strategy (google#1155)

packages/model-viewer/CONTRIBUTING.md → CONTRIBUTING.md

@@ -40,7 +40,42 @@ approach.
 
 Please include tests in your pull request.
 
-We recommend making your pull request from a fork. See [Creating a pull
+We recommend making your pull request from a fork. See [creating a pull
 request from a
 fork](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)
 for more information.
+
+## Stability
+
+It’s important that our users can depend on our product, and not to worry
+about changes in model-viewer causing regressions in their use of the
+component. However, it’s also important that we continue to improve
+model-viewer, making changes to improve ergonomics and rendering quality.
+
+In general, <model-viewer> follows semver. Major versions (`X.y.z`) are used for
+the largest features and backwards-incompatible changes (more below on that),
+minor versions (`x.Y.z`) are used for new features, and patch versions (`x.y.Z`)
+are used for bug fixes.
+
+When possible please keep your changes backwards-compatible - including
+keeping both existing APIs and rendering consistent. When that’s not possible,
+we’ll follow a three-step process across several [semver](semver.org) major
+versions (in the `0.y.z` versions leading up to 1.0, we’ll use the minor
+version - `y` - for the same purpose): 
+
+1) Add a new optional API to enable the new behavior; in the release notes,
+document the new behavior, as well that it will become the default in the
+next version (in for instance the `2.0.0` release)
+1) Make the new API default enabled (allow it to be explicitly disabled for
+the old behavior); in the release notes, document this change, and that the
+API will be removed in the next version (the `3.0.0` release)
+1) Remove the API (the `4.0.0` release)
+
+Breaking changes mostly center around anything that the developer would have
+to take action on. This includes changes in APIs, or changes to the model
+staging/lighting that they might want to undo in order to achieve the effect
+that they currently enjoy.
+
+Additive changes (a new API) aren’t breaking, nor are smaller changes (a fix
+to the correctness of reflections, or a 1% change in padding).
+

README.md

@@ -1,8 +1,9 @@
 # The `<model-viewer>` project
 
 This is the main Github repository for the `<model-viewer>` web component and
-all of its related projects. Getting started? Check out the
-[`<model-viewer>`](packages/model-viewer) project!
+all of its related projects.
+
+**Getting started?** Check out the [`<model-viewer>`](packages/model-viewer) project!
 
 The repository is organized into sub-directories containing the various projects.
 Check out the README.md files for specific projects to get more details:
@@ -17,24 +18,6 @@ Check out the README.md files for specific projects to get more details:
 
 📦 **[3DOM](packages/3dom)** • A generic scene graph API that enables potentially untrusted scripts to operate on 3D models 
 
-## Installing `<model-viewer>`
-
-The `<model-viewer>` web component can be installed from [NPM](https://npmjs.org):
-
-```sh
-npm install @google/model-viewer
-```
-
-It can also be used from various free CDNs such as [unpkg.com](https://unpkg.com):
-
-```html
-<script type="module" src="https://unpkg.com/@google/model-viewer/dist/model-viewer.js"></script>
-<script nomodule src="https://unpkg.com/@google/model-viewer/dist/model-viewer-legacy.js"></script>
-```
-
-For more detailed usage documentation and live examples, please visit our docs
-at [modelviewer.dev](https://modelviewer.dev)!
-
 ## Development
 
 When developing across all the projects in this repository, first install git,

packages/model-viewer/README.md

@@ -42,6 +42,32 @@ It can also be used directly from various free CDNs such as [unpkg.com](https://
 For more detailed usage documentation and live examples, please visit our docs
 at [modelviewer.dev](https://modelviewer.dev)!
 
+### Important note about versions
+Our goal for `<model-viewer>` is to be a consistent, stable part of your web
+platform while continuing to deliver cutting-edge features. We’ll always try
+to minimize breaking changes, and to keep the component backwards compatible.
+See our [guide to contributing](../../CONTRIBUTING.md#Stability) for more
+information on backwards compatibility.
+
+For your production site you may want the extra stability that comes by
+pinning to a specific version, and upgrading on your own schedule (after
+testing).
+
+If you’ve installed via [NPM](https://npmjs.org), you’re all set - you’ll only
+upgrade when you run [`npm update`](https://docs.npmjs.com/cli/update.html).
+
+If you’re using [unpkg.com](https://unpkg.com), you can pin to a specific
+version by specifying it in the URL. Replace the `<version>` tag in the sample
+below with the full version number (like `0.10.0`) to be pinned to.
+
+```html
+<!-- Loads <model-viewer> for modern browsers: -->
+<script type="module"
+    src="https://unpkg.com/@google/model-viewer@<version>/dist/model-viewer.js">
+</script>
+```
+
+
 ## Browser Support
 
 `<model-viewer>` is supported on the last 2 major versions of all evergreen
@@ -56,7 +82,7 @@ desktop and mobile browsers. `<model-viewer>` is also supported on IE11.
 capabilities and compatibility of the library get better as the web evolves.
 
 However, not all browsers support all of these features today. **Check out
-[POLYFILLS.md](https://github.com/PolymerLabs/model-viewer/blob/master/POLYFILLS.md) to
+[POLYFILLS.md](https://github.com/google/model-viewer/blob/master/packages/model-viewer/POLYFILLS.md) to
 learn how to polyfill for maximum browser compatibility!**
 
 ## Development