Support multiple major.minor versions

[RyanCavanaugh]

We should allow folder structures like this:

/jquery
  index.d.ts
  tsconfig.json
  jquery-tests.ts
  /v2
    index.d.ts
    tsconfig.json
    jquery-v2-tests.ts
  /v3.1
    index.d.ts
    tsconfig.json
    jquery-v3.1-tests.ts

This should parse the major and optional minor version number from the folder name and generate versioned packages published under the same name as the parent folder.

[blakeembrey]

This come up in a Gitter chat, but instead of putting meaning onto the directory it might be useful to use semantic folder names and embed the version meaning in package.json. For instance, to support multiple TypeScript versions alongside multiple package versions. To keep it simpler, I'd suggest always nesting or always having it flat - so either multiple versions or not, and not a mix, as mixing it will make it very tricky to keep track of in the case where you're writing .d.ts files for nested files.

So, in this case:

/jquery
  index.d.ts
  tsconfig.json
  jquery-tests.ts

Or:

/jquery
  /v2
    index.d.ts
    tsconfig.json
    jquery-tests.ts
  /v3.1
    index.d.ts
    tsconfig.json
    jquery-tests.ts

Where v2 and v3.1 are not used for the version but are instead only semantic. The actual version is stored in package.json so it could also have a typescriptVersion and other matrix-release related properties.

[Zlatkovsky]

@RyanCavanaugh , @andy-ms : is there significance to the "v" prefix (or any other special patterns?).

I.e., suppose I want to have a regular version as well as a beta version. In our case, we already have an @types/office-js package published, and we want to continue to have that work as is; but at the same time, we also want to have an easy beta version. What would your recommendation be? Is it possible to have both a @types/office-js and @types/office-js@beta, and if so, what should the directory structure look like?

Thanks!

[RyanCavanaugh]

v is simply ignored

There isn't any support for tagged releases right now. I suppose we could add support for version numbers like 2.4-beta and there shouldn't be any problems from that. Thoughts @andy-ms ?

[Zlatkovsky]

@RyanCavanaugh , could you help me understand your proposal a bit more?

If I understood your comment correctly, I would create both a 1.1 folder and a 1.1-beta folder, with the appropriate typings inside of them. But in that case, can we still make it so the default one (the "latest" from an NPM perspective) be the 1.1 one? I.e., I want to make sure that someone using @types/office-js would continue to have his/her typings work as is.

(One appendment to your idea, that might make it "just work": if you're thinking of having a hyphen denote the tag, should my default folder be named 1.1-latest, and that way it fits in with the NPM notion of the "latest" tag?)

Thanks!

[Zlatkovsky]

(@RyanCavanaugh , please see the comment above -- and note that I edited it since I first saw it, so please look at it on GitHub rather than in your email)

[RyanCavanaugh]

Tags and versions are independent. The @latest tag would point to the non -beta version in this proposal. It's fairly difficult in NPM to install a -foo-suffixed version (you would have to explicitly say npm install @types/office@1.1-beta) so there wouldn't be a danger of someone accidently getting it instead of the 1.1 version.

[Zlatkovsky]

So what would my folder structure and usage look like?

For folder structure, would I put 1.1 and 1.1-beta side-by-side as siblings (and no files at the root), like @blakeembrey had mentioned in an earlier ocmment?

/office-js
    /v1.1
        index.d.ts
        tsconfig.json
        office-js-tests.ts
    /v1.1-beta
        index.d.ts
        tsconfig.json
        office-js-tests.ts

And then the tool would look through, and create two package.json-s: one that has a version 1.1.X, and another that's 1.1.X-beta.0, publishing the latter with a beta tag? But how would the tool know which one is my default/latest -- i.e., what if I also had a v2.0 folder, how would it choose?

And then for usage, for the default, a developer would just do:

npm install --save-dev @types/office-js

And for beta:

npm install --save-dev @types/office-js@beta

correct?

[RyanCavanaugh]

And then the tool would look through, and create two package.json-s: one that has a version 1.1.X, and another that's 1.1.X-beta.0, publishing the latter with a beta tag?

The version number would be 1.1.x-beta; I don't think we'd support an additional beta tag unless there was a compelling reason to do so.

But how would the tool know which one is my default/latest -- i.e., what if I also had a v2.0 folder, how would it choose?

The latest tag would point to the highest non--suffixed version number

npm install --save-dev @types/office-js@beta

I think we'd only support npm install --save-dev @types/office-js@1.1.314-beta

[Zlatkovsky]

I think the compelling reason is... well, to make it easy to try out beta :-). From the standpoint of how the tool would run its publishing automation, I think all it would need to do differently is add a --tag beta to the publish command: npm publish --tag beta.

At least for Office.js, we have an evergreen CDN (https://appsforoffice.microsoft.com/lib/beta/hosted/office.js) where the JS files are hosted, so version numbers don't mean much -- no one would know that they need to do @types/office-js@1.1.314-beta, because the 1.1.314 number wouldn't really exist anywhere. Whereas having the simple instructions of "to use Office.js with TypeScript, do an npm install of @types/office-js (appending @beta to the beta version)" seems like a very straightforward way of having folks try out the APIs. And it should't make it any harder on the tool, as far as I can tell...

Having the tag also makes it easy to view (& copy-paste) the latest file via unpkg.com:

// for the "release" version:
https://unpkg.com/@types/office-js/index.d.ts

// for the beta version:
https://unpkg.com/@types/office-js@beta/index.d.ts

[RyanCavanaugh]

It all sounds doable, but this thing publishes thousands of packages and adding code to handle a single thing isn't a totally great trade-off. Since you're internal anyway we can just give you publish rights to @types/office-js and you can push whatever version under whatever tags you want; nothing should actually break the types-publisher as it's fairly resilient to extant conditions of the package. Thoughts?