std/0.50.0

Add std/version.ts and document unstableness of std.

docs/examples/os_signals.md

@@ -1,7 +1,7 @@
 ## Handle OS Signals
 
 > This program makes use of an unstable Deno feature. Learn more about
-> [unstable features](../../runtime/unstable).
+> [unstable features](../runtime/stability.md).
 
 [API Reference](https://deno.land/typedoc/index.html#signal)
 

docs/examples/permissions.md

@@ -1,7 +1,7 @@
 ## Inspecting and revoking permissions
 
 > This program makes use of an unstable Deno feature. Learn more about
-> [unstable features](../../runtime/unstable).
+> [unstable features](../runtime/stability.md).
 
 Sometimes a program may want to revoke previously granted permissions. When a
 program, at a later stage, needs those permissions, it will fail.

docs/linking_to_external_code/import_maps.md

@@ -1,7 +1,7 @@
 ## Import maps
 
 > This is an unstable feature. Learn more about
-> [unstable features](../../runtime/unstable).
+> [unstable features](../runtime/stability.md).
 
 Deno supports [import maps](https://github.com/WICG/import-maps).
 

docs/runtime/stability.md

@@ -0,0 +1,21 @@
+## Stability
+
+As of Deno 1.0.0, the `Deno` namespace APIs are stable. That means that we will
+strive to make code working under 1.0.0 continue to work in future versions.
+
+However, not all of Deno's features are ready for production yet. Features which
+are not ready because they are still in draft phase are locked behind the
+`--unstable` command line flag. Passing this flag does a few things:
+
+- It enables the use of unstable APIs during runtime.
+- It adds the
+ [`lib.deno.unstable.d.ts`](https://github.com/denoland/deno/blob/master/cli/js/lib.deno.unstable.d.ts)
+ file to the list of TypeScript definitions that are used for typechecking.
+ This includes the output of `deno types`.
+
+You should be aware that unstable APIs have probably **not undergone a security
+review**, are likely to have **breaking API changes** in the future and are
+**not ready for production**.
+
+Furthermore Deno's standard modules (https://deno.land/std/) are not yet stable.
+We version the standard modules differently from the CLI to reflect this.

docs/toc.json

@@ -16,9 +16,9 @@
  "runtime": {
  "name": "The Runtime",
  "children": {
+ "stability": "Stability",
  "program_lifecycle": "Program Lifecycle",
  "compiler_apis": "Compiler APIs",
- "unstable": "Unstable APIs",
  "workers": "Workers"
  }
  },

std/version.ts

@@ -0,0 +1,7 @@
+/** Version of the Deno standard modules
+ *
+ * Deno std is versioned differently than Deno cli because it is still unstable;
+ * the cli's API is stable. In the future when std becomes stable, likely we
+ * will match versions with cli as we have in the past.
+ */
+export const VERSION = "0.50.0";