Provide flexible way to update TypeScript specification

[ikokostya]

TypeScript Version: 2.1.5

Problem

Current specification doesn't describe some features from latest stable version of compiler, e.g. null is not assignable to void #11758

Specification can't be easy changed, because is first authored as a Microsoft Word (docx) file https://github.com/Microsoft/TypeScript/tree/master/doc#spec-contributions:

• It's closed format and requires special editors.
• It's binary format and doesn't allow see changes between versions.

Suggestion

• Use markdown as source format for specification.
  Pros:
  • Don't need special editors.
  • This is text format which allow to see changes between versions.
  • This format already used in handbook https://github.com/Microsoft/TypeScript-Handbook
• Generate other formats from markdown.

[simonbuchan]

There is already a markdown version: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md - is it not suitable as a source for some reason? Copy editors? Validation?

The source is mostly very clean and idiomatic markdown, the only real grossness I've seen in there is the grammar using  , which seems like it could use <pre> and regular spaces (  is ~ 2 spaces?)

It would be nice if it could get into a state good enough that PRs that would affect the spec must also update spec.md before merging - would maintaining this as multiple issues update be a burden? (twice the change conflicts)

Should it be broken up into spec_4_statements.md etc?

Would PRs against it as it currently is be accepted? I'm no spec writer, but I could definitely try to go through the release blogs and offer strawman updates.

[RyanCavanaugh]

The spec is now an "archived" artifact and we won't be tracking defects against it anymore.