| Index: packages/path/README.md
|
| diff --git a/packages/path/README.md b/packages/path/README.md
|
| index 5a172cdf26320c70e5713766bd8ede385ec9eaa4..580347066ba756e2d22da61000e720fedc32c974 100644
|
| --- a/packages/path/README.md
|
| +++ b/packages/path/README.md
|
| @@ -41,13 +41,34 @@ context.join("directory", "file.txt");
|
| This will join "directory" and "file.txt" using the Windows path separator,
|
| even when the program is run on a POSIX machine.
|
|
|
| +## Stability
|
| +
|
| +The `path` package is used by many Dart packages, and as such it strives for a
|
| +very high degree of stability. For the same reason, though, releasing a new
|
| +major version would probably cause a lot of versioning pain, so some flexibility
|
| +is necessary.
|
| +
|
| +We try to guarantee that **operations with valid inputs and correct output will
|
| +not change**. Operations where one or more inputs are invalid according to the
|
| +semantics of the corresponding platform may produce different output over time.
|
| +Operations for which `path` produces incorrect output will also change so that
|
| +we can fix bugs.
|
| +
|
| +Also, the `path` package's URL handling is based on [the WHATWG URL spec][].
|
| +This is a living standard, and some parts of it haven't yet been entirely
|
| +solidified by vendor support. The `path` package reserves the right to change
|
| +its URL behavior if the underlying specification changes, although if the change
|
| +is big enough to break many valid uses we may elect to treat it as a breaking
|
| +change anyway.
|
| +
|
| +[the WHATWG URL spec]: https://url.spec.whatwg.org/
|
| +
|
| ## FAQ
|
|
|
| ### Where can I use this?
|
|
|
| -Pathos runs on the Dart VM and in the browser under both dart2js and Dartium.
|
| -Under dart2js, it currently returns "." as the current working directory, while
|
| -under Dartium it returns the current URL.
|
| +The `path` package runs on the Dart VM and in the browser under both dart2js and
|
| +Dartium. On the browser, `window.location.href` is used as the current path.
|
|
|
| ### Why doesn't this make paths first-class objects?
|
|
|
|
|