Document the way this package handles dependencies

Author: nex3

CONTRIBUTING.md

@@ -35,3 +35,86 @@ such, manual commits should never:
 
 * Update the `package.json`'s `"compiler-version"` field to a non-`-dev` number.
   Changing it from non-`-dev` to dev when using a new feature is fine.
+
+# Keeping in Sync With Other Packages
+
+The embedded host depends on several different components which come from
+different repositories:
+
+* The [Dart Sass embedded compiler].
+* [Dart Sass] (transitively through the embedded compiler).
+* The [Sass embedded protocol].
+* The [Sass JS API definition].
+
+[Dart Sass embedded compiler]: https://github.com/sass/dart-sass-embedded
+[Dart Sass]: https://github.com/sass/dart-sass
+[Sass embedded protocol]: https://github.com/sass/embedded-protocol
+[JS API definition]: https://github.com/sass/sass/tree/main/spec/js-api
+
+These dependencies are made available in different ways depending on context.
+
+## Local Development
+
+When developing locally, you can download all of these dependencies by running
+`npm run init`. This provides the following options for `compiler` (for the
+embedded compiler), `protocol` (for the embedded protocol), and `api` (for the
+JS API):
+
+* `--<type>-path`: The local filesystem path of the package to use. This is
+  useful when doing local development on both the host and its dependencies at
+  the same time.
+
+* `--<type>-ref`: A Git reference for the GitHub repository of the package to
+  clone.
+
+* `--<type>-version`: The released version of the package to use. This isn't
+  available for `api`, because the JS API definition doesn't have its own tagged
+  versions.
+
+By default:
+
+* This uses the version of the embedded protocol and compiler specified by
+  `protocol-version` and `compiler-version` in `package.json`, *unless* these
+  versions end in `-dev` in which case it checks out the latest revision on
+  GitHub.
+
+* This uses the JS API definition from the latest revision on GitHub.
+
+`npm run init` chooses the Dart Sass version as follows:
+
+* If a released version of the embedded compiler was specified, it uses the
+  version of Dart Sass compiled into that release.
+
+* If `--compiler-path` was specified, it uses the version of Dart Sass linked to
+  that compiler.
+
+* If the embedded compiler was cloned from GitHub, it uses the version of Dart
+  Sass specified in its pubspec *unless* that version ends in `-dev`, in which
+  case it checks out the latest revision on GitHub.
+
+## Continuous Integration
+
+CI tests also use `npm run init`, so they use the same defaults as local
+development. However, if the pull request description includes a link to a pull
+request for the embedded compiler, Dart Sass, the embedded protocol, or the JS
+API, this will check out that version and run tests against it instead.
+
+## Release
+
+When this package is released to npm, it downloads the embedded protocol version
+that matches `protocol-version` in `package.json`. It downloads the latest JS
+API revision on GitHub.
+
+The release version of the `sass-embedded` package does *not* include the
+embedded compiler or Dart Sass. Instead, we release optional packages of the
+form `sass-embedded-<os>-<arch>`. Each of these contains the published version
+of the embedded compiler that matches `compiler-version` in `package.json` for
+the given operating system/architecture combination.
+
+If either `protocol-version` or `compiler-version` ends with `-dev`, the release
+will fail.
+
+**Note:** As part of the holistic release process for Dart Sass, the embedded
+compiler's CI will automatically update this repository's `package.json` file
+with the latest `compiler-version` and optional dependency versions before
+tagging it for a release.