Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Typescript Specifications version #15711

Closed
mtabaj opened this issue May 9, 2017 · 32 comments
Closed

Typescript Specifications version #15711

mtabaj opened this issue May 9, 2017 · 32 comments
Assignees
Labels
Spec Issues related to the TypeScript language specification

Comments

@mtabaj
Copy link

mtabaj commented May 9, 2017

I can't understand why specifications are fixed to version 1.8
They are a primary source of offline documentation, via de pdf or docx downloadables.
I know you have different issues open to update the specifications, but we talk about 6 month ago and nothing happens.
And in my opinion, is really a central issue.

@RyanCavanaugh RyanCavanaugh added the Unactionable There isn't something we can do with this issue label May 9, 2017
@frankgerhardt
Copy link

That is confusing me as well now that the release is at 2.4.

Please, somebody clarify this!

@mtabaj
Copy link
Author

mtabaj commented Jul 11, 2017

I still can't understand why specifications update is not an issue for you.
It's the primary source for learning / teaching Typescript for most people.
And is not in your planning at all.

@mhegazy mhegazy added Spec Issues related to the TypeScript language specification and removed Unactionable There isn't something we can do with this issue labels Nov 20, 2017
@mhegazy
Copy link
Contributor

mhegazy commented Nov 20, 2017

We are currently working on updating the spec. issues marked with spec should give you more details about what is missing.

@MartinJohns
Copy link
Contributor

@mhegazy Would be great if your statement would be true, but you're not working on updating the spec. :-(

@RyanCavanaugh
Copy link
Member

@MartinJohns @DanielRosenwasser is working on this

@tneward
Copy link

tneward commented Jul 30, 2018

The last updates to the TypeScript spec were three years ago, according to GitHub's commit tracking. It's really kind of hard to accept that anybody is working on this when there's zero updates--even working updates--that anybody outside of Microsoft can see. (And let's be clear, updates that nobody sees aren't really updates at all.)

Update the spec. Please. Or stop pretending, and take it down.

@RyanCavanaugh
Copy link
Member

https://github.com/Microsoft/TypeScript/commits/spec-update is the branch some work has been going in to.

Update the spec. Please. Or stop pretending, and take it down

Please maintain a constructive attitude. This isn't productive.

@mtabaj
Copy link
Author

mtabaj commented Jul 30, 2018

May be is not a constructive attitude. But two commits in 7 months is not productive neither.
I still can't understand that is not a priority for you. Is the main source for anyone that want to access typescript.

@RyanCavanaugh
Copy link
Member

The Handbook is the intended entry point for users trying to learn about TypeScript. The spec isn't intended as a user-facing document and we've prioritized it as such. There are about four people on the planet who can accurately update the spec and all of them are quite busy already.

I agree in an ideal world the spec would be up to date, but as far as we know the current state of the spec isn't blocking anyone from doing any particular thing. If there are specific sections you need advice on, we'd be happy to weigh in, but if the complaint is simply the bare fact that it's not current, I'm afraid you'll have to defer to the current state of priorities.

@tneward
Copy link

tneward commented Jul 30, 2018

For those of us who like to speak on TypeScript, or creating training around it, the spec is a non-optional piece of documentation. The Handbook is just that, a handbook, and does not contain the authoritative determination as to how the language can and should behave in various edge-case scenarios.

Frankly, it's not constructive to hold the attitude that there's only four people on the planet who are interested in the spec and they're all behind the Microsoft gate; there's a lot of people who are interested in such things and even if we can't update it, we find it interesting and useful to read.

So yes, the current state of the spec IS blocking people from doing any particular thing--such as training and lectures and such--and there is a particular section that we need information (not advice), and that's what the specification states around just about every feature introduced since 1.8.

Of course, as project maintainers, you have no obligation to update any particular piece of documentation, and in fact, I'd agree that things could move MUCH faster if you simply chose not to do any documentation whatsoever and repurposed those four peoples' time towards hacking. So do it! But don't get high-handed about it. Just mark the issue closed, remove the out-of-date documentation entirely, and call it a day. Then those of us who have an interest in promoting TypeScript to working developers (who aren't going to ever come to the website to read your handbook) can get the message clearly--that only those four people who are capable of updating the document are going to be capable of offering up anything beyond basics in terms of training and lectures. That way, we can move on to study other things. Because, surprisingly enough, we're all of us out here pretty busy too.

Don't tell me that I've no reason nor the technical skill to consume a document like that. I read the ECMAScript specs. I read the Java and C# specs. (Including all four partitions of the CLI spec.) Please maintain a constructive attitude about what I find productive.

@rpetrich
Copy link

rpetrich commented Jul 31, 2018

@tneward If having a specification is so important to your ability to speak and train around TypeScript (activities that sound to be commercial in nature), I would suggest contributing edits to the existing specification to make it more in line with the current state of the language.

@kitsonk
Copy link
Contributor

kitsonk commented Jul 31, 2018

For those of us who like to speak on TypeScript, or creating training around it, the spec is a non-optional piece of documentation.

I have been dealing with TypeScript for 4 years. I have created and executed extensive training on TypeScript. Never once was the spec a challenge or constraint in accomplishing it. I am glad the core team has focused on adding functionality and solving real world problems versus updating the spec. They have worked on what is important to me.

Why are you special?

@MartinJohns
Copy link
Contributor

MartinJohns commented Jul 31, 2018

I would suggest contributing edits to the existing specification to make it more in line with the current state of the language.

@rpetrich To be fair, the PR regarding the spec are currently a dead end: https://github.com/Microsoft/TypeScript/pulls?q=is%3Apr+label%3ASpec+is%3Aopen
And my favourite PR being #20971

@RyanCavanaugh
Copy link
Member

Frankly, it's not constructive to hold the attitude that there's only four people on the planet who are interested in the spec and they're all behind the Microsoft gate; there's a lot of people who are interested in such things and even if we can't update it, we find it interesting and useful to read.

I didn't say that. I said, there are about four people on the planet who can accurately update the spec, which is true. There are more than four people interested in the spec; I am one of them. It's simply a resource constraint.

But don't get high-handed about it. Just mark the issue closed, remove the out-of-date documentation entirely, and call it a day.

The project maintainers get to decide what "open" and "closed" means on the issue tracker, and we have chosen that "open" means "work we intend to do". We intend to update the spec, so the issue is open. We do not attach any metadata, including "closed", for "Work that is not being done fast enough to satisfy certain individuals".

The dating on the spec is clearly identified and simply deleting it serves no higher goal.

Don't tell me that I've no reason nor the technical skill to consume a document like that. I read the ECMAScript specs. I read the Java and C# specs. (Including all four partitions of the CLI spec.) Please maintain a constructive attitude about what I find productive.

I said nothing of the sort and would like to understand why the things I've written so far would imply this.

Nearly every feature that we do here starts with an open issue where we have extensive discussions with other developers, gets a design review with public notes, then gets a PR which usually has lengthy implementation and design notes, followed by a period where people log bugs/questions and get direct feedback from developers on the project. The code is open source, and you can ask questions here about aspects of the code. We are very far from providing zero guidance here and the insistence that a formal spec is the only way for you to promote TS to people who won't read our own docs seems very arbitrary.

If there's some important edge case that can't be determined by reading the code, reading the PR notes, reading the originating issue, reading the extant bugs relating to the feature, reading Stack Overflow questions, reading the release blog, reading the official documentation, or experimentation, then please do log a bug here! I would treat that scenario as a documentation deficit that we would want to address in one way or another.

@mtabaj
Copy link
Author

mtabaj commented Jul 31, 2018

So instead of having one source of truth for Typescript - THE SPECS - we have to read the code, the PR notes, stack overflow, the release blog...
It's really not serious.

@RyanCavanaugh
Copy link
Member

we have to read the code, the PR notes, stack overflow, the release blog...

... the documentation?

@tneward
Copy link

tneward commented Jul 31, 2018

Look, at the end of the day, you're going to prioritize as you see fit; no words of mine are going to sway or change those decisions, particularly when you (the team) has now doubled down on the idea that the existing disparate sources (code, PRs, etc) are a reasonable place by which to establish a mental model of how TypeScript works, as opposed to having a single document that collects all of that (and adds a higher degree of precision).

What I also know is that:

  • It is difficult for anyone who is not a TypeScript expert to know whether a particular snippet of code is supposed to behave as it does without a specification.
  • Perl ran for years without a specification, and when they tried to write a spec after the fact, it failed miserably. Perl's inconsistencies dogged the language for years.
  • The longer the spec lags behind the current implementation, the harder it will be to write one, and the more difficult it will be to justify writing one and bringing it up to date.
  • A specification is extremely hard to write from the outside of the core committer group, because it requires a degree of familiarity with not only the existing code, but the intent behind the features, particularly where features intersect. I doubt anyone who isn't a core committer can accurately capture the specification.

At the end of the day, it's not my project; run it as you see fit. But having seen this decision (and this line of justification) many times before, I will make a bet with anyone on the team, right now: By this time (July 31) in 2019, the TypeScript specification PDF/DOCX will still be 1.8, because it will still be lower on the priority scale than the other things. If I'm wrong, I'll take the team out to a nice dinner here in Bellevue/Redmond area: Daniel's Broiler, maybe, or Ruth's Chris.

Let the community write the handbook based off of what's in the spec. Just because the handbook is easier to write (due to a lower bar of precision) doesn't mean it can be used as a spec.

Peace, out.

@csantos42
Copy link
Contributor

@RyanCavanaugh @DanielRosenwasser would the core team be open to contributions from the community for Spec updates?

Even though many of the spec issues require knowledge of internals, it looks like there might be some issues that can be accomplished with small-to-medium updates (these PRs could be made against the spec-update branch). I'm thinking it will save time for the core team (assuming the contributions are not totally incorrect) as you'll be able to focus on reviewing/approving/guiding spec updates as opposed to having to make the updates from scratch, which understandably is a challenge to prioritize.

I'm sure several of us that frequent the spec page would be happy to at least attempt to contribute to this effort :)

@cwellsx
Copy link

cwellsx commented Apr 13, 2019

Is there a current grammar?

Ignoring the rest of the spec, is there somewhere a definition of just the current grammar?

I see that these are identical ...

... so (I don't know what other changes are in the spec-update branch, but) apparently there's no updated grammar there.

Is there an updated grammar?

Or is the only grammar definition what might be inferred from:

@Luxcium
Copy link

Luxcium commented Jun 9, 2019

Hello, I am not a professional and I don't have studied in software engineering...

I kind of agree with both side here... But because I would like to refer to an authoritative document (a bible) I kind of agreeing more with the consumer side of the language than those on the production side.

But since I have great respect for the latest group who build this language that we all like so much I don't know on which side I am ...

Regardless it seems now that we won't make you change your mind about the specs which I think should be important but I am not maintainer or committer...

I would dream to work on those specs but my lack of professional experience and internal knowledge can be a big problem...

You need to leverage the help of the community but since I know nothing I can't tell you what to do ... I am here to learn not to give advice ...

I would like to bring something positive and constructive with my comment so you finally understand how important it is for us and then help us to make you put that higher in your priorities.

even if all of us would be qualified to do the specs its something that needs to be done in one shot and not small pieces by small pieces by random peoples ...

Can you set our expectations differently at least (this is easier than producing the specs) because from now if I paraphrase what I have understood you agree it is important to have it but you don't agree it is important to produce it...

I wanted to have access to the specs because it's another way to learn the language than reading the source code, handbook and all past PR etc ...

So please can you reformulate what you said regarding this in order to be more clear about why we don't need specs and why you will not do them? because now it's confusing you kind of say that you will do it but since it is not important you will do it never (I am asking here) and then I am confused ...

I also feel that reading all the PR and what else is not really productive (it may be to understand something specific but not to understand the big picture)...

Thanks for all the great work and thanks for clarification on how to learn Typescript beyond the HandBook

@David-Else
Copy link

The spec is on the front page of the main site, it made me cringe when I saw how out of date it is.

How about in 2019 we at least get up to Version 2.0?! Just add:

https://en.wikipedia.org/wiki/Microsoft_TypeScript

2.0 | 22 September 2016
null- and undefined-aware types,
control flow based type analysis,
discriminated union types,
never type,
readonly keyword,
type of this for functions

Go on... get those four people in a room at Microsoft mansion and lock the door! :)

@Jeansen
Copy link

Jeansen commented Jan 5, 2020

I must agree, I am also missing the spec being up to date. I am new to TS and as an example while reading through the handbook, suddenly this 'keyof' operator was mentioned. But nowhere in the handbook had it been introduced. Unfortunately there is also no index of operators and the like that I could quickly have a look at. Something like the reference navigation on the left side on https://developer.mozilla.org/en-US/docs/Web/JavaScript.
There you can quickly find what you are looking for and get a short explanation (instead of searching through a handbook).

So, I thought, let's have a look at the spec. Something must be in there, ultimately. But sadly the spec is now 3 to 4 years behind.

Put aside the fact of priorities and the like my personal feeling is that I feel somehow of lost if I do not have an up-to-date reference or spec that I can resort to. I belong those who also like to understand the inner workings of a language and not just it's application. Also, it leaves some bitter taste when there is language (with a good handbook and a lot of tutorials) but something like the spec is utterly outdated. Especially when the handbook tells you to see the spec for more information.

I know, it is not critical. The Interweb is full of other resources just some key-strokes away. But, still. It feels like the language is not being developed with full sincerity.

Therefore I must admit and add myself to the already growing list of people who would like to see the spec up to date with the current language version.

Actually I must say that from all the languages and documentations I've worked with over the years, Kotlin (https://kotlinlang.org/docs/reference/) is my absolute favorite. If the TS site would be similar to that one (including a reference and also the ability to download the documentation as PDF), that would be terrific.

Don't get me wrong, TS is a great peace of work. But I still see room for improvements.

@MartinJohns
Copy link
Contributor

[...] suddenly this 'keyof' operator was mentioned. But nowhere in the handbook had it been introduced.

It's introduced when it appears for the third time: http://www.typescriptlang.org/docs/handbook/advanced-types.html#index-types

First is keyof T, the index type query operator. For any type T, keyof T is the union of known, public property names of T.

@ghost
Copy link

ghost commented Mar 16, 2020

I can't deny that the handbook is a very good reference. However, in my personal opinion, I don't think that even a handbook covers TypeScript comprehensively. In the handbook, some of the features of TypeScript were only covered in "What's new?", So sometimes I had to follow the version history. However, as a new handbook is being prepared, it is worth looking forward to.

@Jeansen
Copy link

Jeansen commented Mar 17, 2020

Can't wait. 👍

@mprinc
Copy link

mprinc commented Apr 9, 2020

@tneward is absolutely and sadly right, it will be harder and harder to write

@RyanCavanaugh is suggesting the community onboard. Well, as already discussed, this is not so easy.

I think this status-quo strategy from the TypeScript maintainer/contributors side is not super healthy. At least give us an open hand rather than just using this as a defence.

However, would make sense that TypeScript maintainer/contributors at least provide placeholders and track new things that need to be documented. In such way at least this will be a good record for them, and an invitation for our community to participate and team up.

@Jeansen
Copy link

Jeansen commented Apr 9, 2020

I actually wonder why not have it in code, like with https://github.com/asciidoctor/asciidoctor.js/ . Whenever something changes, put it there, generate the doc and you are all set. 🤔

@dinofx
Copy link

dinofx commented May 6, 2020

Whether it is a spec or the handbook, it would be nice if all of the language features were captured in one place. For example, a generic type's parameter can have a default value like:

interface Reference<T = string> {
  ref: T;
}

const stringRef: Reference = { ref: 'string' };
const numberRef: Reference<number> = { ref: 3 };

But this is missing from both the handbook and the spec. Is this only documented in the 2.3 release notes?

The release notes are really helpful, but they don't provide long-term value like the handbook. If resource limitations mean a new language feature can't be documented in both the handbook and the release notes, to me the handbook should get priority.

@mtabaj
Copy link
Author

mtabaj commented May 6, 2020 via email

@mprinc
Copy link

mprinc commented May 6, 2020

Maybe we can create some funding schema, a Microsoft Patreon account for funding TypeScript documentation ;) Let's help Microsoft! :)

@Jeansen
Copy link

Jeansen commented May 6, 2020

Maybe it is because sooner or later TypeScript will be Ecmascript 202x?

@RyanCavanaugh
Copy link
Member

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

@microsoft microsoft locked as resolved and limited conversation to collaborators Jul 20, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Spec Issues related to the TypeScript language specification
Projects
None yet
Development

No branches or pull requests