3.1:Rename SymbolFlags.JSContainer->Assignment

API-Breaking-Changes.md

@@ -1,3 +1,7 @@
+# TypeScript 3.1
+
+- `SymbolFlags.JSContainer` has been renamed to `SymbolFlags.Assignment` to reflect that Typescript now supports expando assignments to functions.
+
 # TypeScript 3.0
 
 - The deprecated internal method `LanguageService#getSourceFile` has been removed. See #24540.
@@ -31,11 +35,11 @@ See https://github.com/Microsoft/TypeScript/pull/15594 for more details.
 
 # TypeScript 2.1
 
-- `ParseConfigHost` now require a new member `readFile` to support [configuration inheritance](https://github.com/Microsoft/TypeScript/pull/9941).
+- `ParseConfigHost` now requires a new member `readFile` to support [configuration inheritance](https://github.com/Microsoft/TypeScript/pull/9941).
 
 # TypeScript 1.9
 
-- `LanguageService.getSourceFile` is removed (https://github.com/Microsoft/TypeScript/pull/7584), `LanguageService.getProgram().getSourceFile` should be used instead.
+- [`LanguageService.getSourceFile` is removed](https://github.com/Microsoft/TypeScript/pull/7584); `LanguageService.getProgram().getSourceFile` should be used instead.
 
 # TypeScript 1.7
 
@@ -95,4 +99,4 @@ We did some cleanup to the public interfaces, here is the full list of changes:
 
 The two files exposed helpers in the past that were not part of the supported TypeScript API. If you were using any of these APIs please file an issue to re-expose them; requests for exposing helper APIs will be triaged on a case-per-case basis.
 
-For more information please see the [full change](https://github.com/Microsoft/TypeScript/pull/2692).
+For more information please see the [full change](https://github.com/Microsoft/TypeScript/pull/2692).

How-the-User-Tests-Work.md

@@ -0,0 +1,26 @@
+There are two types of user tests: npm install and submodule.
+
+## NPM Install Tests
+
+npm install tests have two purposes. 
+
+1. Test the user experience of a Typescript package.
+2. Test compilation of a Javascript package without having to use submodules.
+
+These tests have at least a package.json and a tsconfig.json.
+
+In the Typescript-user case, there is also an index.ts that matches how the user is expected to use the library. However, today, most of these files are just `import x = require('x')`. This just makes sure that the typings exported by the project continue to work with new versions of Typescript, even if the authors aren't paying attention to new versions.
+
+In the Javascript-source case, the tsconfig.json points into the node_modules directory: `include: ['node_modules/x/src']` or something similar. Many Javascript projects ship their source or something close to it, and an npm install is **much** easier than a git submodule.
+
+# Submodule Tests
+
+Submodule tests let us test project source without needing to check in a copy to a repo that we own. This is better than our internal real-world code tests, because reproing errors is much easier: just clone the repo and run tsc. However, it requires an open source project that can build with a single call to tsc. That excludes modern Angular and many Microsoft-internal projects.
+
+Also you have to use submodules.
+
+
+# Pitfalls of submodules
+
+1. They are submodules!
+2. The submodule repo name needs to be the same as the containing directory name.