Definitelytyped: New Contribution Guide/Transition Issues DT/types-2.0 and @types

[tomwanzek]

First of all, thanks to everyone who made DefinitelyTyped and the integration with TS 2 and @types possible :+1: .

@DanielRosenwasser @RyanCavanaugh and @mhegazy thanks for the perspective and insights shared in Improve Declaration File Acquisition, the related blog post and the wonderful TypeScript Handbook resource on authoring/publishing declaration files.

Having chipped away at TS2 definitions for D3, I came across a couple of more general issues to which I do not seem to find a conclusive answer in the above resources. My issues comment 9936#issuecomment-237378115 on legacy definitions and transition provisions started off in the context of D3, so I might use D3 as an example below.

While I am looking for answers to address these immediate issues, I suppose in the medium term an updated contribution guide would be great.

Here are the questions that create the issues, I did not find covered elsewhere. A brief answer would be great for now.

Definitions Versioning/Consuming Legacy Definitions

(1) What is the recommended strategy for separating definitions for legacy versions of a library from the latest version in DefinitelyTyped/types-2.0? The old contribution guide refers to file name suffixes, while some comments in Improve Declaration File Acquisition seem to suggest sub-folders?
(2) What information in a DefinitelyTyped/types-2.0 definition drives the version number showing up in the published package on npm@types? Is it only the version tag in the first header comment line of the definition file? Is there a role for a stripped down package.json?
(3) How do I re-point a consuming definition file in DefinitelyTyped/types-2.0 to the definition of a legacy version? E. g. currently several libraries consume the old D3 v3 definitions, but we need to publish the new D3 v4 definitions which is a massive breaking change. How should this be done so it works _within_ DT/types-2.0 and propagates correctly to npm@types? I.e. npm install @types/[email protected] --save works for legacy and npm install @types/d3 --save gets the latest v4 definitions?

Change Controls in types-2.0 branch

(4) What are the change controls (RACI) for PR review/approval in the types-2.0 branch? Is it still assumed that authors listed in the Definitions By must be @-mentioned for a change affecting a definitions and have a content approval role before merging?
(5) Who should be informed (@-mentioned) when creating a PR as responsible for the actual merge to minimize noise for your already busy team?

Transition Provisions between master and types-2.0

If I understand correctly, currently the master branch is periodically refreshing the types-2.0 branch. The types-2.0 branch is published to @types. Now with a webhook triggered by a merge :+1:. Definitions using TypeScript 2 features or structure are only supported in the types-2.0 branch. At some upcoming point, the types-2.0 branch will be merged into master.

Against this backdrop:

(6) As we currently address definitions requiring TS2 in the types-2.0 branch, how do we avoid them being overwritten by merge/pub jobs from master to types-2.0, which may contain less feature-rich, outdated definitions? (I just noticed a merge which, while correct, was not notified to the authors.)
(7) Is there a rough timeline for the merge from types-2.0 to master? This would allow better planning of effort to create/maintain TS 1.8.x definitions, where TS 2 definitions already exist.

_Aplologies for the laundry list above, but as this all revolves around details for a "Contribution Guide"/transition plan, I thought I keep it together._

[DanielRosenwasser]

I haven't had the chance much to work with the infrastructure up until this point, so @mhegazy, @RyanCavanaugh, and @andy-ms will be able to answer some of these questions better than I can.

At some upcoming point, the types-2.0 branch will be merged into master.

Having discussed this with others, I don't think we can do this because it would break users who will continue to using tsd and Typings. I think the plan is instead to create a new _primary_ branch that contributors will see when they navigate to DefinitelyTyped and clone the repo. This will just be types-2.0.

While master being reserved is going to be a source of confusion, we can do our best to notify contributors that they are on a deprecated branch.

[MeirionHughes]

I've had a PR merged into master. It would be super useful to know how to get those changes onto npm. I went so far as to ask on SO.

So I need to PR from master to types-2.0?

[DanielRosenwasser]

So I need to PR from master to types-2.0?

@MeirionHughes, I believe @paulvanbrenk may be doing this in general, but if he hasn't done the port yet, any help from you would be great. :smiley:

[MeirionHughes]

Oh wow... the runner has been going for 30mins trying to test my PR to port just one module. 8|

[tomwanzek]

@DanielRosenwasser thanks for your initial quick response. And my apologies for forgetting @andy-ms in the list above. A totally unjustifiable omission on my part.

While a complete new contribution guide might take a little longer, some brief guidance to the above questions would be most appreciated in the interim.

I would love to close off the project of migrating the new definitions for D3 version 4 from the collaborative development repo I had created to DefinitelyTyped / @types. The work on the definitions is essentially complete for all standard modules that make up D3. What could be migrated has been. The remainder are additional small bells-and-whistles modules.

One of only two "structural" issues remaining is the relation to legacy versions and the master branch listed above (resolution required for PR #10453).

The other structural issue is the separate tracked TypeScript UMD global merge Issue #9681.

That being said, again my eternal gratitude for making TypeScript possible!

[tomwanzek]

cc @gustavderdrache FYI forgot to copy you when I spun this issue off.

[RyanCavanaugh]

What is the recommended strategy for separating definitions for legacy versions of a library from the latest version in DefinitelyTyped/types-2.0?

The strategy we plan to use is to have a layout like this

foo/index.d.ts <-- "latest"
foo/v2/index.d.ts <-- legacy version
foo/v3/index.d.ts <-- legacy version

This isn't implemented yet; we currently just publish the 'latest'.

What information in a DefinitelyTyped/types-2.0 definition drives the version number showing up in the published package on npm@types? Is it only the version tag in the first header comment line of the definition file?

Yes, we parse the version number from the header comment.

Is there a role for a stripped down package.json?

Yes. We read certain fields from package.json and copy them into the published package. @andy-ms can point you at the list of supported fields.

How do I re-point a consuming definition file in DefinitelyTyped/types-2.0 to the definition of a legacy version?

Updating package.json should be sufficient. We'll need to figure out how to make the tests still pass when this happens.

What are the change controls (RACI) for PR review/approval in the types-2.0 branch? Is it still assumed that authors listed in the Definitions By must be @-mentioned for a change affecting a definitions and have a content approval role before merging?

Our experience from looking at the PR backlog has been that authors don't respond to PR requests with anywhere near the needed frequency. The plan going forward is that the TypeScript team will be reviewing PRs for "the appearance of correctness" and merging things under the assumption that people aren't actively sabotaging the definition files.

Who should be informed (@-mentioned) when creating a PR as responsible for the actual merge to minimize noise for your already busy team?

We're going to be merging pretty aggressively. If there's a specific maintainer who should look at something, the PR comment should mention that the submitter _wants_ the PR to be blocked on that person signing off.

As we currently address definitions requiring TS2 in the types-2.0 branch, how do we avoid them being overwritten by merge/pub jobs from master to types-2.0, which may contain less feature-rich, outdated definitions?

The merge from master to types-2.0 is manual, so "bad" merges in that direction shouldn't be happening. If you see this happen, let us know.

Is there a rough timeline for the merge from types-2.0 to master?

Current plan is 6 weeks after TypeScript 2.0 releases. At that point types-2.0 will 'become' master, and the current master will be renamed to 1.8. We'll still accept PRs to 1.8 for anyone who needs a 1.8-compatible definition but the default should be types-2.0 (AKA master at that time).

[tomwanzek]

@RyanCavanaugh thanks a lot for the breakout of answers!!! Really appreciated.

@andy-ms could you please point me to the information regarding the "stub"-package.json files, which could be placed into DefinitelyTyped/types-2.0 branch definition directories?

Based on the above info, I can formulate a follow-up approach to resolving the D3 module definitions related issues/PRs with what is possible right now. I will keep the details out of this thread to keep it lean, but, I suspect, some of your support will be necessary to quickly move the resulting PRs through the pipeline. I will @-mention you on the resulting changes on the few D3-specific issues/PRs, thanks for your efforts in advance.

The main outstanding issue becomes the handling of the legacy folders, as, at present, I would not be able to update the /d3 folder with a new D3 version 4 standard bundle definition (re-exports of relevant constituent modules) without breaking the dependencies within DT on D3 v3.5.17 definitions.

I also noticed that, the parsing of the header comments for the new D3 modules already published in types-2.0, e.g. d3-selection, does not seem to catch the major and minor version number? I will open a separate issue on types-publisher.

Again, massively grateful for all your hard work!

cc @gustavderdrache @Ledragon

[andy-ms]

@tomwanzek Currently a package.json should only include a "dependencies" field, which if present will be mixed with any inferred dependencies (with explicit versions overriding anything implicitly detected) and put into the full package.json generated by types-publisher. For an example, see pikaday/package.json.

[tomwanzek]

@andy-ms thanks for the information and all your hard work on the types-publisher!

So I guess, I have a couple of take-aways:

(1) From what I saw, you have fixed the 'freak'-version-parsing error :smile: introduced by having a number being part of the D3 module names. Would be great, if the open PRs #10741 and #10947 could then be merged. Thx, in advance!!!

(2) Thanks for the reference to the pikaday example. I'll have to mull this over to have a concise follow-up question pertaining to how this helps us address the open issue with legacy definitions. It will be easier to frame this, once the merges under (1) are done. As the version numbers in @types will make for a better reference point.

Cheers.

[andy-ms]

Hope #12070 answers these questions.

[tomwanzek]

@andy-ms Thanks a lot!!! Great work. 🎉