Typescript Specifications version #15711
Comments
RyanCavanaugh
added
the
Unactionable
|
That is confusing me as well now that the release is at 2.4. Please, somebody clarify this! |
|
I still can't understand why specifications update is not an issue for you. |
mhegazy
added
Spec
|
We are currently working on updating the spec. issues marked with spec should give you more details about what is missing. |
|
@mhegazy Would be great if your statement would be true, but you're not working on updating the spec. :-( |
|
@MartinJohns @DanielRosenwasser is working on this |
|
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. |
|
https://github.com/Microsoft/TypeScript/commits/spec-update is the branch some work has been going in to.
Please maintain a constructive attitude. This isn't productive. |
|
May be is not a constructive attitude. But two commits in 7 months is not productive neither. |
|
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. |
|
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. |
|
@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. |
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? |
@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 |
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.
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.
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. |
|
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... |
... the documentation? |
|
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:
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. |
|
@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 I'm sure several of us that frequent the spec page would be happy to at least attempt to contribute to this effort :) |
|
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:
|
|
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 |
|
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
Go on... get those four people in a room at Microsoft mansion and lock the door! :) |
|
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. 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. |
It's introduced when it appears for the third time: http://www.typescriptlang.org/docs/handbook/advanced-types.html#index-types
|
|
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. |
|
Can't wait. 👍 |
|
@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. |
|
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. 🤔 |
|
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. |
|
I can’t understand how a project like typescript, followed by all main frameworks today, can’t have one person to update both the handbook and the language reference guide. It’s unbelievable.
De : Randy Hudson <notifications@github.com>
Envoyé : mercredi 6 mai 2020 15:37
À : microsoft/TypeScript <TypeScript@noreply.github.com>
Cc : Marcos Tabaj <mt@bapiness.com>; Author <author@noreply.github.com>
Objet : Re: [microsoft/TypeScript] Typescript Specifications version (#15711)
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 <https://www.typescriptlang.org/v2/docs/handbook/generics.html> handbook and the spec. Is this only documented in the <https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-3.html> 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.
—
You are receiving this because you authored the thread.
Reply to this email directly, <#15711 (comment)> view it on GitHub, or <https://github.com/notifications/unsubscribe-auth/AAHTOEN7NICAYKEOCZERR2TRQFRZFANCNFSM4DKYAXCA> unsubscribe. <https://github.com/notifications/beacon/AAHTOENXZBGOZH74TUPFH3DRQFRZFA5CNFSM4DKYAXCKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEU5XPQY.gif>
|
|
Maybe we can create some funding schema, a Microsoft Patreon account for funding TypeScript documentation ;) Let's help Microsoft! :) |
|
Maybe it is because sooner or later TypeScript will be Ecmascript 202x? |
|
The spec is now an "archived" artifact and we won't be tracking defects against it anymore. |
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.
The text was updated successfully, but these errors were encountered: