Documentation: migration guide from 2.x to 3.0

[acud]

If I understand correctly the next release will be a major release.
Therefore we should add a new migration guide section with the relevant information.

I can take this upon myself, but would need some further information on what has to be included.

[fatso83]

See the commit id for the last release, and then look through the list of merged pull requests since then to find relevant changes. I think that is what we basically do :)

[acud]

I was thinking that :) but actually to be explicit I just wanted to know from @mroderick if he has any specific comments about the nise import and if it breaks anything in particular that I should note for (there's 5000 deletions on that PR 😂). was there any API change between the fake xhr and nise? or was it just extracted?

[acud]

I was also thinking - maybe we could include the extracted modules as git submodules on sinon, then if we would refactor the different sections in the submodule documentation we could actually have sinon to generate the sections on the documentation from the submodules.

It would just mean we would need to refactor the different parts of the documentation on the submodules then concat them somehow with an npm job.

Thoughts?

[acud]

Another addition:
I'm just going through the migration guide from 1.x to 2.0, and there's a list of helpers that should be removed at 3.0 but weren't. The marked items were indeed removed but on a first look the rest weren't:

• sinon.calledInOrder
• sinon.create
• sinon.deepEqual
• sinon.format
• sinon.functionName
• sinon.functionToString
• sinon.getConfig
• sinon.getPropertyDescriptor
• sinon.objectKeys
• sinon.orderByFirstCall
• sinon.restore
• sinon.timesInWorlds
• sinon.valueToString
• sinon.walk
• sinon.wrapMethod

• sinon.Event
• sinon.CustomEvent
• sinon.EventTarget
• sinon.ProgressEvent

• sinon.typeOf
• sinon.extend

Proceeding with removal of the rest if there's no objection.
EDIT: I thought this would be more straightforward but references to these helpers are still all over the codebase

[fatso83]

@elad-nach Are you sure there are references all over the codebase, or just in _docs? A quick test for calledInOrder, create, and extend showed no occurences:

ag sinon.walk lib/ test/

[acud]

in assert.js:

var calledInOrder = require("./util/core/called-in-order");
var orderByFirstCall = require("./util/core/order-by-first-call");
var timesInWords = require("./util/core/times-in-words");
var format = require("./util/core/format");

in behaviour.js:

var extend = require("./util/core/extend");
var functionName = require("./util/core/function-name");
var valueToString = require("./util/core/value-to-string");

in call.js:

var deepEqual = require("./util/core/deep-equal").use(sinonMatch);
var functionName = require("./util/core/function-name");
var sinonFormat = require("./util/core/format");
var valueToString = require("./util/core/value-to-string");

you get the point.
the list goes on and on (almost every file in lib references one or more of those)

[fatso83]

you miss the point :-) the point was removing the explicit exports (the public interface), not the actual functions. they are internal implementation details we would not want people to depend upon. removing the actual functions would have made Sinon a very slim package 😄

[acud]

OK :)
but the migration guide for 2.0 said the following:

Deprecation of internal helpers
The following utility functions are being marked as deprecated and are planned for removal in Sinon v3.0; please check your codebase for usage to ease future migrations:

So the basic assumption was that they are to be removed.

Back to the topic: so basically removing exposeCoreUtils from sinon.js should fulfil the purpose?

[fatso83]

Yes, I think that should be sufficient. But now I start wondering why we haven't marked them as deprecated, like we did everywhere else before removing stuff. Maybe we should do that first, and then remove them in the next major version. We did specify it in the v1 docs, though... Thoughts, @mroderick?

[mroderick]

We did specify it in the v1 docs, though.

I've created #1506 to remove all the deprecated exports from sinon/util/core/

[acud]

nice one @mroderick 🍻