Sinon 2.0 Release

[jonnyreeves]

What do we want to achieve in preparation for releasing a 2.0 release candidate of Sinon?

@mantoni @fatso83 @cjohansen Here are a handful of proposed tasks; please edit this Issue, or comment below so we can get a list of tasks together and get 2.0 shipped 🚀

CommonJS Migrations

• Migrate sinon.spy Commonjs-ified sinon.spy #920
• Migrate sinon.stub CommonJSify sinon.stub #932
• Migrate sinon.mock CommonJSify sinon.mock #933
• Migrate fake_server and friends (Bulk of work done in CommonJSify sinon utils package #934, useFakeXMLHttpRequest still referenced, see Feature/cjsify fake server tests #1118)
• Migrate sinon.sandbox (Bulk of work done in Extract sandbox into a CommonJS module. #936) Feature/cjsify sinon sandbox tests #1088
• Migrate sinon.format (Tightly coupled in tests) Remove the use of sinon.format from the codebase #967
• Migrate sinon.collection CJSify collection tests #1084

Test Suite CommonJS Migrations

• Migrate assert suite CJSify sinon.assert tests #1078
• Migrate call suite CJSify sinon.call tests #1079
• Migrate collection suite CJSify collection tests #1084
• Migrate extend suite Feature/cjsify typeof extend tests #1085
• Migrate match suite CJSify match tests #1086
• Migrate mock suite CJSify mock tests #1087
• Migrate sandbox suite Feature/cjsify sinon sandbox tests #1088
• Migrate spy suite CJSify Spy and Stub Tests. #1001
• Migrate stub suite CJSify Spy and Stub Tests. #1001
• Migrate typeOf suite Feature/cjsify typeof extend tests #1085
• Migrate util/core suites CJSify Core Util Tests. #998, CJSify get-config tests #1081
• Migrate util/event suite Migrate sinon.Event testsuite to CommonJS #1115
• Migrate util/fake-timers suite CJSify fake-timer tests #1116
• Migrate util/fake-server suite Feature/cjsify fake server tests #1118
• Migrate util/fake-server-with-clock suite Feature/cjsify fake server tests #1118
• Migrate util/fake-xdomain-request suite
• Migrate util/fake-xml-http-request suite CJSify fake-xml-http-request tests. #1125

Cleanup Tasks

• Break down test/sinon-test.js suite Re-organise Tests (removes sinon-test.js) #968
• Remove sinon.config usage (Decision: #936. Removed entirely in Remove sinon.test() and sinon.testCase. #973)
• Remove sinon.logError and sinon.log [Remove sinon.log and sinon.logError #972]
• Use CommonJS imports in tests (No more sinon global access, allows us to remove internal helpers from the public API) Migrate Packaged Tests to use a Browserified Build.  #996
• Document API changes from 1.17 -> 2.0 and provide upgrade advice. Add v2.0 Migration Guide #1090

Public API Changes

tasks with a ? require clarification from maintainers

• Extract sinon.test and sinon.testCase into their own NPM module (sinon-test) Migrate sinon-test from sinon package. sinon-test#1 and Remove sinon.test() and sinon.testCase. #973
• Deprecate use of internal core utils (see Add v2.0 Migration Guide #1090)
• Internalise sinon.extend (General utility not related to Sinon) Internalise typeOf and extends #1235
• Internalise sinon.typeOf (General utility not related to Sinon) Internalise typeOf and extends #1235
• Remove Legacy IE support / workarounds?
• Refactor util/fake_server.js so as not to use sinon global

Outside of Scope

• Extract sinon.mock into its own module (sinon-mock) (Decision: Deprecate mock #745). Not removed until 3.0

New documentation site

• Create and publish a new documentation site, see Task: Publish new website #1220 for details on remaining work.

[mroderick]

I would like to create a new documentation website, based on the work that is already in /docs. I am hoping to spend some hours on that during my vacation next week.

[spinningarrow]

@mroderick If you have the work pushed somewhere, let me know. I might be able to help with the docs!

[fatso83]

Updated the checkboxes. Not sure if "Migrate sinon.sandbox" should be checked, but at least the PR is closed.

[fatso83]

@jonnyreeves : not sure why we should remove sinon.test. This is a sandbox around the test that cleans any created stubs and spys up automatically after the test. That alleviates people from lots of beforeEach and afterEach functions. Very useful, and has little to do with testing frameworks.

Users would need to see an easy alternative to this for this to be removed in favor of something else (better).

I have never used sinon.testCase myself, probably because its api fits BusterJS (where each test case is a property of the test suite) and not Mocha (where each test is an anonymous function running in the body of the test suite).

[jonnyreeves]

@fatso83 The main issue I have with sinon.test is the fact that it relies on the sinon.config singleton. IMHO Users can have far more control by creating (and restoring) a sandbox in their test-framework's beofreEach and afterEach hooks.

If we are going to keep sinon.test (and sinon.testCase) in the public API; then we need to address both of these issues - although a long time user / support of sinon, I'm new to hacking ont his project - how should we reach concensous?

[fatso83]

@jonnyreeves OK, it made more sense when you mentioned it relied on sinon.config. IMHO explicitly creating and restoring sandboxes is fine as long as we supply this as an alternative for people coming from Sinon 1 and wondering what ever happened to sinon.test. So the doucmentation should read something like

sinon.test

This has been deprecated in version 2 in favor of explictly creating a sandboxe. See link to sandbox.

I am all in for a leaner API in version 2, so stuff like typeOf, extends and sinon.test* could be better served by other NPM modules or other existing functionality.

[cjohansen]

I think something like npm install sinon-test and var sinonTest = require('sinon-test')(config); could be a decent replacement.

[fatso83]

👍 to moving utilities like this into separate npm modules. Less code in the core

[jonnyreeves]

Thanks for the input; I've updated the overview up top to reflect the discussion so far (mainly removing question marks, making tasks clearer), please take a look.

Also, could we get similar closure on:

• removing sinon.log and sinon.logError (both are used by the fake_server; and would probably be better passed as configuration to those instances)
• removing sinon.mock from 2.0

Thanks

[mantoni]

I never used sinon.testCase, however I'm a heavy user of sinon.test. I'm fine with it going into a separate library, but just to not forget: there are quite a few people using test frameworks that don't support beforeEach by design (e.g. tape) with the argument that these setup functions lead to coupled test cases. We might cause a lot of problems for these users if there's no simple to drop-in replacement.

I guess we could offer something like this as a migration path:

sinon.test = require('sinon-test');

[fatso83]

@mantoni : Great suggestion. By just assigning to the the now unused test property it gives people the least amount of hassle by just including one extra line in their tests. We just have to make sure that the sinon object is not frozen (as in Object.freeze(sinon)) at some point ...

[fatso83]

@jonnyreeves : regarding sinon.mock I remember that @mroderick suggested to wait until 2.0 was released before removing this. We have already signaled for some time that it has been deprecated, so it should be fine to remove it after the 2.0 release IMHO. But since we already have CommonJS support I would not mind removing it before the 2.0 release if we have extracted the code into a module of its own. Then people could just let sinon.mock = require('sinon-mock'), if they so pleased.

Regarding sinon.log*, I see no reason to cling on to them as public features if we could just supply them as configuration when needed.

[jonnyreeves]

WRT factoring out a sinon-test, just note that we would need to allow consumers to supply a configuration, ie:

sinon.test = require('sinon-test').withConfig({ ... });

or similar.

[jonnyreeves]

Just spotted another possible API change whilst creating a sinon-test package; any thoughts as to what should happen to sinon.assert? Again this doesn't feel like a core part of the sinon API to me and may be better suited by migrating to a sinon-test package alongside sinon.test and sinon.testCase?

[jonnyreeves]

@fatso83 @mantoni @cjohansen; I've got a working build of a sinon-test package ready for review - could one of you please initialise an empty git repo over at sinonjs/sinon-test so I can raise a PR against it please?

Thanks

[cjohansen]

That was quick! https://github.com/sinonjs/sinon-test

[jonnyreeves]

@cjohansen could you just push an empty README to it please? Looks like I can't raise a PR in the current state.

[cjohansen]

Done

[jonnyreeves]

Thanks, PR raised - feedback welcome: sinonjs/sinon-test#1

[mroderick]

@mroderick If you have the work pushed somewhere, let me know. I might be able to help with the docs!

@spinningarrow that would be great. I have created #991 to track this separately from the rest of the effort. I'll be updating this in upcoming days with my thoughts, and we can take it from there.

[fatso83]

We are having a few issues every now and then relating to mocks. Now that @jonnyreeves has done the hard work of actually extracting the module, would it not make sense to move the module into a repo if its own? Then we could just move all discussions relating to mocks there, and close the issues here. This is mainly just to ease the administration burden.

[mroderick]

We are having a few issues every now and then relating to mocks. Now that @jonnyreeves has done the hard work of actually extracting the module, would it not make sense to move the module into a repo if its own? Then we could just move all discussions relating to mocks there, and close the issues here. This is mainly just to ease the administration burden.

That would also mean administration burden of keeping that repository in sync with dev tools, etc.
Perhaps we should make sure we have easy shared dev tools set up first? cc: @mantoni

[jonnyreeves]

@mroderick @fatso83 OK, let's see if we can get 2.0 out the door.

I've updated the overview of this Issue to cover what I consider to be all outstanding migrations (including CJSification of the testsuite, please, if you are reading this - help!) - please take a look and let me know if you agree with the outstanding work.

Additionally, I would like to get consensus on the following:

1. Should we remove typeOf and extend from the public (sinon.) API, or should this wait for Sinon 3.x which (I assume) will undergo a modernisation of the API.
2. Should we remove the legacy IE support/hacks from 2.0? This may simplify the migration as we could drop the 'fakeXDM' code - I haven't looked closely so I can't really estimate this work yet.
3. Is shipping the new docs site a prerequisite of the 2.0 release? I'm concerned that it doesn't have a lot of traction :)

Thanks all.

[fatso83]

@jonnyreeves: You have certainly been a busy bee tonight 😺. I have a long vacation ahead of me, so I could certainly help with the outstanding migrations of the test suite (there is a "but" below).

Regarding your points:

1. They should go. I thought this was pretty much settled (ref, the overview above).
2. Let's just define "legacy IE" first. Versions < 10, or the entire sinon-ie package? IE9 was still shipping with some weird CORS alternative called XDR. If there are anyone still aiming to support IE versions released before 2012 they could always use the 1.x branch, I guess. Not sure what you refer to by XDM? I am not sure for which browser versions sinon-ie is needed, so I cannot be too bombastic about the package not being needed. We should be certain of the consequences.
3. Documentation is a pain point right now, but I am a bit unsure of what to say here. I could start digging into New documentation site #991 before helping with the other points above. Having somewhere to push docs would make life better.

[ELLIOTTCABLE]

Curious what the status on this is? Doesn't look like there's been much progress since ~6mo ago; I'm currently depending on a pre-release for various reasons (functioning Symbol support being a huge one) — I don't mean to push, but a simple ‘there is a timeline’ / ‘there is no timeline as of yet’ would be great! <3

[fatso83]

@ELLIOTTCABLE as we don't have funding, there is no set time line. It progresses as we in the maintainer group - or other volunteers such as yourself - have time to work on the list above. That being said, I think you could have answered the "status" bit yourself if you bothered to poke around a bit more 😉:

1. Even though you see "... referenced on 8 Jul 2016" above, that only means that the first comment in the list is from that date. The latest issue, Internalise typeOf and extends #1235, referenced this "12 days ago".
2. The list of issues is near-complete - unlike half a year ago.

So ... we are getting somewhere, but overseeing bug fixes for the previous version, as well as a constant supply of new features, suck up a lot of our maintenance time. Just researching and writing this took half an hour in the end 😅

Basically, after looking over the list above there are just two main issues that remain:

• "Migrate fake_server and friends" (90% resolved, just a little bit left - see above).
• Publish the website (see Task: Publish new website #1220: one minor, super-easy thing and one medium task up for grabs)

I think most of the other uncloses checkmarks above relate to old IE releases (6-10) which I am quite certain will not be supported, based upon the discussions in #1221, so they can be ignored. Will address that now.

[fatso83]

@sinonjs/sinon-core: the previous comment made me aware that we have some issues above that we are not likely to complete based on the discussion in #1221:

1. Remove Legacy IE support / workarounds?
2. Fixing xdomain

Care if I create a PR to just remove the legacy IE bits if we won't touch them anyhow? I would assume xdomain can end up in the historical land fill as well, as that was mostly an IE-only CORS-alike hack, so it can be removed?

[ELLIOTTCABLE]

@fatso83 Ahhhh, k. I missed the updated comments on the referenced Issues. I hope reviewing this for me was of use to you!

Unrelatedly: Looks like part of this is abandoning support for IE6. That's unfortunate. Ah well, c'est la marche du progrès! /=

[cjohansen]

We're basically there, the docs site has its own issue.

[jonnyreeves]

Hey chaps - anything preventing us from marking 2.0 as the "stable" sinon release and killing 1.x? :)

[fatso83]

Think we wanted #1297 in as the last thing.

[cjohansen]

ETA on that? I suggest we ship no later than next week, postponing that one feature if it's not done.

[ELLIOTTCABLE]

You guys are beautiful. <3