Add docs for reproducible build

docs/introduction/reproducibility.md

@@ -0,0 +1,34 @@
+# Reproducibility
+
+A key point to service definition is the ability to reliably reproduce the exact same output over time. In cases like:
+
+1. A dependency or dependency of dependency was updated with an unintended breaking change
+2. Changes to a new version of a service shouldn't affect the older versions
+3. A change to the TypeSpec spec
+
+This can be mitigated with a few steps:
+
+## 1. Defend against dependency changes
+
+_Note: This section applies if using `cadl install` or `npm install` to install dependencies. However other package managers (`yarn`, `pnpm`, etc.) have their own similar lock mechanisms._
+
+When using `cadl install` or `npm install` a `package-lock.json` will be installed. This file SHOULD be committed to source control. It will ensure that later calls to `cadl install` or `npm install` will use the exact versions resolved in the lock files unless the `package.json` was updated or a command like `npm update` was run.
+
+The command `npm ci` can also be used in the CI to ensure that the `package.json` and `package-lock.json` are in sync.
+
+## 2. Work with multiple versions of a service
+
+TypeSpec provides a library `@typespec/versioning` that can be used to describe changes to a service or library over time. Using this will ensure that a service can evolve while keeping track of the changes and allowing emitters to see the service representation at different versions.
+
+[See versioning docs](../standard-library/versioning/overview.md)
+
+## 3. Change to the TypeSpec spec
+
+If you don't directly control the spec, you might still want to make sure you remember which exact definition was used.
+Using version control and pinning to a specific commit SHA will ensure that the spec will remain exactly as it was.
+
+## Summary
+
+1. Use `package-lock.json`
+2. Use [versioning library](../standard-library/versioning/overview.md)
+3. Keep track of commit IDs

packages/website/sidebars.js

@@ -36,6 +36,7 @@ const sidebars = {
         "introduction/usage",
         "introduction/style-guide",
         "introduction/formatter",
+        "introduction/reproducibility",
         {
           type: "category",
           label: "Configuration",