Skip to content

Commit 037ec2d

Browse files
fatso83fatso83
committedSep 13, 2024
Update migration docs
·
v20.0.0v19.0.1
1 parent 62724bb commit 037ec2d

20 files changed

+584
-400
lines changed
 

‎.bundle/config

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
---
2+
BUNDLE_PATH: "vendor/bundle"

‎.tool-versions

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
nodejs 22.2.0
2-
ruby 2.7.8
2+
ruby 3.2.2

‎Gemfile

+1
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@ gem 'github-pages', group: :jekyll_plugins
33
gem "jekyll", "~> 3.7"
44
gem 'jekyll-sitemap'
55
gem 'jekyll-toc'
6+
gem 'html-proofer'

‎Gemfile.lock

+224-146
Large diffs are not rendered by default.

‎docs/CONTRIBUTING.md

+1-3
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,11 @@ However, if you're going to contribute changes that alter the overall structure
2323
cd docs
2424

2525
# ensure you have bundler
26-
gem install bundler
2726

2827
# install all dependencies
29-
bundle install --path vendor/bundle
3028

3129
# build, serve and live-reload the site
32-
npm run dev-docs
30+
npm run serve-docs
3331
```
3432

3533
After that you can access the site at http://localhost:4000/

‎docs/Makefile

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Just check out https://makefile.site
2+
3+
# otherwise Make assumes that all install targets are files & folders
4+
.PHONY: install deploy livereload build help list-targets
5+
6+
help:
7+
@make print S="These are the possible make targets you can invoke"
8+
@make list-targets
9+
10+
install:
11+
@command -v bundle > /dev/null || (make print S="Missing Bundler. Installing" && gem install bundler )
12+
bundle install
13+
@# this is just to get the output as the final line
14+
@make check-dependencies
15+
16+
copy-over-sinon-script:
17+
@[[ -e assets/js/sinon.js ]] || npm run build && cp ../pkg/sinon.js assets/js/
18+
19+
check-dependencies:
20+
@command -v git-lfs > /dev/null || (make print S="You need to install Git LFS before committing changes" && exit 1)
21+
22+
check-links: copy-over-sinon-script
23+
bundle exec htmlproofer --assume-extension='.html' --ignore-status-codes="403" --no-enforce-https ./_site/
24+
25+
deploy: check-dependencies
26+
git push
27+
28+
livereload:
29+
bundle exec jekyll serve --trace --livereload --host localhost --incremental
30+
31+
# only for checking out the final build
32+
# # only for checking out the final build
33+
build:
34+
bundle exec jekyll build
35+
36+
### UTILS ###
37+
38+
#https://stackoverflow.com/a/26339924/200987
39+
list-targets:
40+
@LC_ALL=C $(MAKE) -pRrq -f $(firstword $(MAKEFILE_LIST)) : 2>/dev/null | awk -v RS= -F: '/(^|\n)# Files(\n|$$)/,/(^|\n)# Finished Make data base/ {if ($$1 !~ "^[#.]") {print $$1}}' | sort | grep -E -v -e '^[^[:alnum:]]' -e '^$@$$' | grep -v print
41+
42+
print:
43+
@printf "\033[01;35m%s\033[00m\n" "$(S)"
44+

‎docs/_includes/carbonads.html

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
<script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?serve=CE7D453M&placement=sinonjsorg" id="_carbonads_js"></script>
1+
<script async type="text/javascript" src="https://cdn.carbonads.com/carbon.js?serve=CE7D453M&placement=sinonjsorg" id="_carbonads_js"></script>

‎docs/guides/migrating-to-2.0.md

-87
This file was deleted.

‎docs/guides/migrating-to-3.0.md

-64
This file was deleted.

‎docs/guides/migrating-to-4.0.md

-13
This file was deleted.

‎docs/guides/migrating-to-5.0.md

-49
This file was deleted.

‎docs/guides/migrating-to-6.0.md

-9
This file was deleted.

‎docs/guides/migrating-to-7.0.md

-9
This file was deleted.

‎docs/guides/migration-guide.md

+288
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
---
2+
layout: page
3+
title: Migrating between versions
4+
breadcrumb: migrating
5+
---
6+
7+
## Sinon 19
8+
9+
A breaking change is that Fake Timers 13 now fake all timers by default. Previously
10+
a couple of timers were explicitly ignored, but this no longer applies.
11+
If you want the old behavior, specify the `toFake` option and leave the name
12+
of the timers giving you trouble.
13+
14+
The new version of fake-timers also no longer creating dates using the original Date
15+
class, but a subclass (proxy). This should not matter unless you are doing some kind
16+
of identity checks on the constructor: functionally they are the same.
17+
18+
Removal of `legacyRoutes` option that was enabled in a previous `nise` version as the
19+
underlying library, `path-to-regexp`, had a fundamental change to its parsing that
20+
made the option a no-op.
21+
22+
## Sinon 18
23+
24+
Mostly removal of some deprecated exports related to `sinon-test`, such as
25+
sinon.defaultConfig and related modules.
26+
27+
## Sinon 17
28+
29+
Drops support for Node 16
30+
31+
## Sinon 15
32+
33+
Removes option to pass a custom formatter.
34+
35+
## Sinon 7
36+
37+
For users upgrading to Sinon 7 the only known breaking API change is that
38+
**negative ticks** are not allowed in `Sinon@7` due to updating to lolex 3
39+
internally. This means you cannot use negative values in
40+
sinon.useFakeTimers().tick();
41+
42+
If you experience any issues moving from Sinon 6 to Sinon 7, please let us
43+
know! https://github.com/sinonjs/sinon/issues/new?template=Bug_report.md.
44+
45+
## Sinon 6
46+
47+
There should be no reason for any code changes with the new Sinon 6.
48+
Usually, `MAJOR` releases should come with breaking changes, but there are
49+
no known breaking changes in `sinon@6` at the time of this writing. We chose
50+
to release a new major version as a pragmatic solution to some noise related
51+
to releasing Sinon 5.1 https://github.com/sinonjs/sinon/pull/1829#issue-
52+
193284761, which featured some breaking changes related to ESM (which since
53+
has been resolved).
54+
55+
If you should experience any issues moving from Sinon 5 to Sinon 6, please
56+
let us know!
57+
https://github.com/sinonjs/sinon/issues/new?template=Bug_report.md.
58+
59+
## Sinon 5
60+
61+
As with all `MAJOR` releases in semver http://semver.org/, there are
62+
breaking changes in `sinon@5`.
63+
This guide will walk you through those changes.
64+
65+
## `spy.reset()` is removed, use `spy.resetHistory()`
66+
67+
In a previous version we deprecated and aliased `spy.reset` in favour of
68+
using `spy.resetHistory`. `spy.reset` has now been removed, you should use
69+
`spy.resetHistory`.
70+
71+
## `sinon` is now a (default) sandbox
72+
73+
Since `sinon@5.0.0`, the `sinon` object is a default sandbox. Unless you
74+
have a very advanced setup or need a special configuration, you probably
75+
want to only use that one.
76+
77+
The old sandbox API is still available, so you don't **have** to do
78+
anything.
79+
80+
However, switching to using the default sandbox can help make your code more
81+
concise.
82+
Now would be a good opportunity to tidy up your tests.
83+
84+
### Before `sinon@5.0.0`
85+
86+
In earlier versions, you would manually have to create sandboxes and keep
87+
references to them in order to restore them.
88+
89+
const sandbox = sinon.createSandbox();
90+
91+
describe("myFunction", function () {
92+
afterEach(function () {
93+
sandbox.restore();
94+
});
95+
96+
it("should make pie");
97+
});
98+
99+
### From `sinon@5.0.0`
100+
101+
describe("myFunction", function () {
102+
afterEach(function () {
103+
sinon.restore();
104+
});
105+
106+
it("should make pie");
107+
});
108+
109+
## Sinon 4
110+
111+
As with all `MAJOR` releases in semver http://semver.org/, there are
112+
breaking changes in `sinon@4`.
113+
This guide will walk you through those changes.
114+
115+
## `sinon.stub(obj, 'nonExistingProperty')` - Throws
116+
117+
Trying to stub a non-existing property will now fail, to ensure you are
118+
creating
119+
less error-prone tests https://github.com/sinonjs/sinon/pull/1557.
120+
121+
## Sinon 3
122+
123+
As with all `MAJOR` releases in semver http://semver.org/, there are
124+
breaking changes in `sinon@3`.
125+
This guide will walk you through those changes.
126+
127+
## `sinon.stub(object, "method", func)` - Removed
128+
129+
Please use `sinon.stub(obj, "method").callsFake(func)` instead.
130+
131+
var stub = sinon.stub(obj, "stubbedMethod").callsFake(function () {
132+
return 42;
133+
});
134+
135+
A codemod is available https://github.com/hurrymaplelad/sinon-codemod to
136+
upgrade your code
137+
138+
## `sinon.stub(object, property, value)` - Removed
139+
140+
Calling `sinon.stub` with three arguments will throw an Error. This was
141+
deprecated with `sinon@2` and has been removed with `sinon@3`
142+
143+
## `sinon.useFakeTimers([now, ]prop1, prop2, ...)` - Removed
144+
145+
`sinon.useFakeTimers()` signature has changed
146+
To define which methods to fake,
147+
please use `config.toFake`. Other options are now available when configuring
148+
`useFakeTimers`. Please consult the documentation for more information.
149+
150+
## `sinon.sandbox.create(config)` - Config changes
151+
152+
The changes in configuration for fake timers implicitly affect sandbox creation.
153+
If your config used to look
154+
like `{ useFaketimers: ["setTimeout", "setInterval"]}`, you
155+
will now need to change it to `{ useFaketimers: { toFake: ["setTimeout",
156+
"setInterval"] }}`.
157+
158+
## `sandbox.stub(obj, 'nonExistingProperty')` - Throws
159+
160+
Trying to stub a non-existing property will now fail to ensure you are
161+
creating
162+
less error-prone tests
163+
https://github.com/sinonjs/sinon/issues/1537#issuecomment-323948482.
164+
165+
## Removal of internal helpers
166+
167+
The following internal functions were deprecated as of `sinon@1.x` and have
168+
been removed in `sinon@3`:
169+
170+
• `sinon.calledInOrder`
171+
• `sinon.create`
172+
• `sinon.deepEqual`
173+
• `sinon.format`
174+
• `sinon.functionName`
175+
• `sinon.functionToString`
176+
• `sinon.getConfig`
177+
• `sinon.getPropertyDescriptor`
178+
• `sinon.objectKeys`
179+
• `sinon.orderByFirstCall`
180+
• `sinon.restore`
181+
• `sinon.timesInWorlds`
182+
• `sinon.valueToString`
183+
• `sinon.walk`
184+
• `sinon.wrapMethod`
185+
• `sinon.Event`
186+
• `sinon.CustomEvent`
187+
• `sinon.EventTarget`
188+
• `sinon.ProgressEvent`
189+
• `sinon.typeOf`
190+
• `sinon.extend`
191+
192+
## Sinon 2
193+
194+
Sinon v2.0 is the second major release, we have made several breaking
195+
changes in this release as a result of modernising the internals of Sinon.
196+
This guide is intended to walk you through the changes.
197+
198+
## sinon.log and sinon.logError Removed
199+
200+
`sinon.log` and `sinon.logError` were used in Sinon v1.x to globally
201+
configure `FakeServer`, `FakeXMLHttpRequest` and `FakeXDomainRequest`; these
202+
three functions now allow the logger to be configured on a per-use basis. In
203+
v1.x you may have written:
204+
205+
sinon.log = function (msg) { // your logging impl };
206+
207+
You would now individually import and configure the utility upon creation:
208+
209+
var sinon = require("sinon");
210+
211+
var myFakeServer = sinon.fakeServer.create({
212+
logger: function (msg) { // your logging impl }
213+
});
214+
215+
## sinon.test, sinon.testCase and sinon.config Removed
216+
217+
`sinon.test` and `sinon.testCase` have been extracted from the Sinon API and
218+
moved into their own node module, sinon-test
219+
https://www.npmjs.com/package/sinon-test. Please refer to the sinon-test
220+
README https://github.com/sinonjs/sinon-test/blob/master/README.md for
221+
migration examples.
222+
223+
## stub.callsFake replaces stub(obj, 'meth', fn)
224+
225+
`sinon.stub(obj, 'meth', fn)` return a spy, not a full stub. Behavior could
226+
not be redefined. `stub.callsFake`
227+
now returns a full stub. Here's a codemod script
228+
https://github.com/hurrymaplelad/sinon-codemod to help you migrate.
229+
See discussion https://github.com/sinonjs/sinon/pull/823.
230+
231+
// Old
232+
sinon.stub(obj, "meth", fn);
233+
// New
234+
sinon.stub(obj, "meth").callsFake(fn);
235+
236+
## stub.resetHistory replaces stub.reset
237+
238+
`stub.reset()` now resets the history and the behaviour of the stub.
239+
Previously `stub.reset()` only reset the history of the stub. Stubs now have
240+
separate methods for resetting the history and the behaviour. To mimic the
241+
old behaviour replace all `stub.reset()` calls with `stub.resetHistory()`.
242+
243+
// Old
244+
stub.reset();
245+
// New
246+
stub.resetHistory();
247+
248+
## Deprecation of internal helpers
249+
250+
The following utility functions are being marked as deprecated and are
251+
planned for removal in Sinon v3.0; please check your codebase for usage to
252+
ease future migrations:
253+
254+
• `sinon.calledInOrder`
255+
• `sinon.create`
256+
• `sinon.deepEqual`
257+
• `sinon.format`
258+
• `sinon.functionName`
259+
• `sinon.functionToString`
260+
• `sinon.getConfig`
261+
• `sinon.getPropertyDescriptor`
262+
• `sinon.objectKeys`
263+
• `sinon.orderByFirstCall`
264+
• `sinon.restore`
265+
• `sinon.timesInWorlds`
266+
• `sinon.valueToString`
267+
• `sinon.walk`
268+
• `sinon.wrapMethod`
269+
• `sinon.Event`
270+
• `sinon.CustomEvent`
271+
• `sinon.EventTarget`
272+
• `sinon.ProgressEvent`
273+
• `sinon.typeOf`
274+
• `sinon.extend`
275+
276+
## `sandbox.useFakeXMLHttpRequest` no longer returns a "server"
277+
278+
In Sinon 1.x, the sandbox' `useFakeXMLHttpRequest` was the same as its
279+
`useFakeServer`. In 2.x, it maps directly to `sinon.useFakeXMLHttpRequest`
280+
(but with sandboxing). If you use `sandbox.useFakeXMLHttpRequest`, replace
281+
it with `sandbox.useFakeServer`, and your tests should behave as they always
282+
did.
283+
284+
## `sinon.behavior` is gone
285+
286+
The `sinon.behavior` object is no longer exposed for random modification.
287+
However, there is a new mechanism in place aided to add new behavior to
288+
stubs, `sinon.addBehavior(name, fn)`, see the stub docs.

‎docs/release-source/release/spy-call.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ breadcrumb: spy-call
66

77
## Spy call
88

9-
A spy call is an object representation of an individual call to a _spied_ function, which could be a [fake](../fakes), [spy](../spies), [stub](../stubs) or [mock method](../mocks).
9+
A spy call is an object representation of an individual call to a _spied_ function, which could be a [fake](../fakes), [spy](../spies/), [stub](../stubs/) or [mock method](../mocks/).
1010

1111
### `var spyCall = spy.getCall(n)`
1212

‎docs/release-source/release/utils.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ stubContainer.contains.returns(false);
2424
stubContainer.contains.withArgs("item").returns(true);
2525
```
2626

27-
The given constructor function is not invoked. See also the [stub API](../stubs).
27+
The given constructor function is not invoked. See also the [stub API](../stubs/).
2828

2929
### `sinon.restoreObject(object);`
3030

‎docs/releases.md

+7-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,13 @@ redirect_from:
2121

2222
</div>
2323

24-
{% include docs/migration-guides.md %}
24+
### Migration guide
25+
26+
The [migration guide](/guides/migration-guide) covers what to think about
27+
when migrating to a new major version. Mostly, you should not really be
28+
practically affected by most of the major version jumps: it's mostly trivial
29+
stuff like dropping support for a version of Node or some very minute
30+
detail of an implementation some people _might_ depend upon.
2531

2632
<div class="in-content releases">
2733
<ul>

‎package-lock.json

+4-4
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

+6-7
Original file line numberDiff line numberDiff line change
@@ -39,20 +39,19 @@
3939
"test-webworker": "mochify --driver puppeteer --serve . test/webworker/webworker-support-assessment.js",
4040
"test-esm-support": "mocha test/es2015/module-support-assessment-test.mjs",
4141
"test-esm-browser-build": "node test/es2015/check-esm-bundle-is-runnable.js",
42-
"test-docker-image": "docker-compose up",
4342
"test-runnable-examples": "docs/release-source/release/examples/run-test.sh",
43+
"test-docs": "cd docs; make check-links",
4444
"test": "npm run test-node && npm run test-headless && npm run test-webworker",
4545
"check-dependencies": "dependency-check package.json --no-dev --ignore-module esm",
46+
"update-compatibility": "node ./scripts/update-compatibility.cjs",
4647
"build": "node ./build.cjs",
47-
"dev-docs": "cd docs; rsync -r --delete release-source/ releases/dev; npm run serve-docs",
48-
"build-docs": "cd docs; bundle exec jekyll build",
49-
"serve-docs": "cd docs; bundle exec jekyll serve --incremental --verbose --livereload",
48+
"build-docs": "cd docs; make build",
49+
"serve-docs": "cd docs; make livereload",
5050
"lint": "eslint --max-warnings 0 '**/*.{js,cjs,mjs}'",
5151
"unimported": "unimported .",
5252
"pretest-webworker": "npm run build",
53-
"prebuild": "rimraf pkg && npm run check-dependencies",
53+
"prebuild": "rimraf pkg && npm run check-dependencies && npm run update-compatibility",
5454
"postbuild": "npm run test-esm-support && npm run test-esm-browser-build",
55-
"prebuild-docs": "./scripts/update-compatibility.js",
5655
"prepublishOnly": "npm run build",
5756
"prettier:check": "prettier --check '**/*.{js,css,md}'",
5857
"prettier:write": "prettier --write '**/*.{js,css,md}'",
@@ -85,7 +84,7 @@
8584
"@sinonjs/fake-timers": "13.0.1",
8685
"@sinonjs/samsam": "^8.0.1",
8786
"diff": "^7.0.0",
88-
"nise": "^6.1.0",
87+
"nise": "^6.1.1",
8988
"supports-color": "^7.2.0"
9089
},
9190
"devDependencies": {

‎scripts/update-compatibility.cjs

+3-4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
#!/usr/bin/env nodejs
21
/*
32
* Purpose: update/align our docs and our .browserlistrc file
43
* so that we do not spread out-of-date information
@@ -16,12 +15,12 @@ const compatibilityPath = `${root}/COMPATIBILITY.md`;
1615
const debug = require("debug")("update-compatibility");
1716

1817
debug(
19-
"Copy browserslistrc file to root for running our own linting using compat/compat"
18+
"Copy browserslistrc file to root for running our own linting using compat/compat",
2019
);
2120
shell.cp(sourceFile, root);
2221

2322
debug(
24-
`Inline browserslistrc file into ${compatibilityPath} to keep contents in-sync`
23+
`Inline browserslistrc file into ${compatibilityPath} to keep contents in-sync`,
2524
);
2625
const rl = readline.createInterface({
2726
input: fs.createReadStream(compatibilityPath),
@@ -50,7 +49,7 @@ const processLine = (() => {
5049
state = STATES.AFTER;
5150
// newlines following Prettier's formatting
5251
return `\n\`\`\`\n${fs.readFileSync(
53-
sourceFile
52+
sourceFile,
5453
)}\`\`\`\n\n${line}`;
5554
}
5655
return NOOP;

0 commit comments

Comments
 (0)
Please sign in to comment.