Updated documentation based on current progress.

README.md

@@ -1,20 +1,22 @@
 # WebAssembly for .NET
 [![NuGet](https://img.shields.io/nuget/v/WebAssembly.svg)](https://www.nuget.org/packages/WebAssembly)
 
-A library able to create, read, modify, write and (incomplete) execute WebAssembly (WASM) files from .NET-based applications.
-*Execution does not use an interpreter.*
+A library able to create, read, modify, write and execute WebAssembly (WASM) files from .NET-based applications.
+*Execution does not use an interpreter or a 3rd party library:*
 WASM instructions are mapped to their .NET equivalents and converted to native machine language by the .NET JIT compiler.
 
 Available on NuGet at https://www.nuget.org/packages/WebAssembly .
 
 ## Getting Started
 
 - Use the `WebAssembly.Module` class to create, read, modify, and write WebAssembly (WASM) binary files.
+  - `Module.ReadFromBinary` reads a stream into an instance, which can then be inspected and modified through its properties.
+  - `WriteToBinary` on a module instance writes binary WASM to the provided stream.
   - There are no known issues with this functionality and the API is stable.
 - Use the `WebAssembly.Runtime.Compile` class to execute WebAssembly (WASM) binary files using the .NET JIT compiler.
-  - The only significant missing feature is Table Imports; WASM files that do not require this feature are likely to work.
+  - This part of the API is in "beta" status and may require changes to improve compliance with WASM standards.
 
-Please file an issue if you encounter an assembly that works in browsers but not with this library.
+Please report an issue if you encounter an assembly that works in browsers but not with this library.
 
 ## Sample: Create and execute a WebAssembly file in memory
 
@@ -103,17 +105,14 @@ static class Program
 }
 ```
 
-## Development Status
-
-### Required for 1.0
-
-- Implement Table Imports.
-
-### After 1.0
+## Current Development Objectives
 
+- Improve official specification compliance, using Google Chrome as the reference for correct behavior.
+- Improve exceptions thrown from problems found during compilation or execution.
 - Provide a mechanism to replace the `System.Reflection.Emit.AssemblyBuilder`-affiliated methods with replacements so that something like Mono.Cecil can be used to produce a DLL.
 - If https://github.com/dotnet/corefx/issues/4491 is fixed, use it to enable saving DLLs.
 - Remove the compiler's Data section segment size limit of 4128768 bytes.
+- Add support for new WebAssembly features as they become standardized.
 
 ## Other Information
 

WebAssembly/WebAssembly.csproj

@@ -6,7 +6,7 @@
     <Title>WebAssembly for .NET</Title>
     <AssemblyTitle>WebAssembly for .NET</AssemblyTitle>
     <Authors>Ryan Lamansky</Authors>
-    <Description>Create, read, modify, write and (incomplete) execute WebAssembly (WASM) files using pure 100% .NET.</Description>
+    <Description>Create, read, modify, write and execute WebAssembly (WASM) files using pure 100% .NET.</Description>
     <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
     <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
     <PackageReleaseNotes>Full support for creation and modification of WASM 1.0 files; .NET CLR JIT-based execution is not 100% complete.</PackageReleaseNotes>

docs/BreakingChanges.md

@@ -1,12 +1,35 @@
 # Breaking Change Information
 
-Details and migration information regarding breaking changes will be provided here after the 1.0 release.
-Preview changes will be less detailed due to low usage.
-
-## Preview Breaking Change Summary
+## Policy
+
+Breaking changes are avoided whenever possible, but are sometimes needed to achieve correct behavior and deliver highly desired functionality.
+* WebAssembly inspection, modification, and creation features have been mostly unchanged for years and this is expected to continue for any *stable* features of the official WebAssembly specification.
+  * Changes to functionality associated with final standards of WebAssembly will typically result in a new major version, unless the change is determined to be very low risk.
+  * Changes to functionality associated with *draft* versions of WebAssembly can occur in minor releases.
+* CLR JIT-based compilation and execution can change in any version to achieve closer compliance to officially specified behavior, with the current release of Google Chrome used as the reference.
+  * To minimize risk to your project, test your WASM files in Google Chrome and file bugs for deviance in WebAssembly for .NET's behavior.
+* .NET Core 3.1 will be supported *at least* as long as Microsoft supports it.
+  * .NET 5 and beyond is capable of loading .NET Core 3.1 libraries without complaint.
+  * Microsoft will transition long-term support to newer .NET releases over time, eventually leading to hardship with developing against older versions, which will trigger an update to the next oldest "LTS" release in a major version.
+  Specifically, if enabling an unsupported version of .NET causes compatibility problems with the Ubuntu-based build agent or Visual Studio Community-based Windows users, it's time to upgrade.
+  * Multi-targeted releases (for example, .NET Core 3.1 and .NET 6) may be created if the extra targets add useful features.
+  * Automated testing will cover .NET Core 3.1 and any newer compatible versions that are supported by Microsoft.
+* WebAssembly for .NET releases will *never* take a dependency on anything other than .NET itself.
+  * This minimizes the chance of "dependency hell".
+  * Extension points may be made available so that middleware can be created to combine WebAssembly for .NET with other tools. Extension point requests are tracked via GitHub issues.
+
+* Scope will not creep beyond the following objectives:
+  * Provide .NET-based data structures that can represent any binary WASM feature.
+  * Binary WASM files can be created from scratch, or read into memory for inspection and modification.
+  * Binary WASM files can be executed using the .NET CLR via run-time WASM-to-CIL conversion with Google Chrome as the reference for correctness.
+  * Provide a pathway to convert WASM files to .NET DLLs to enable ahead-of-time compilation.
+
+## Breaking Changes from Preview Releases
 
 ### 0.11.0
 
+This is the first non-preview release; these are the last breaking changes for preview versions.
+
 * `Int32Constant`, `Int64Constant`, `Float32Constant`, `Float64Constant`: several members were moved to a new base class, `Constant`.
   For users of this library working in higher-level languages like C#, this shouldn't break your build, but it's a binary incompatibility for already-built code that used the moved members.
 * Some instruction `.ToString()` calls now return additional information in WAT format.