From 037ec2d2a995fb1f84f7b63ed00e632316648612 Mon Sep 17 00:00:00 2001 From: Carl-Erik Kopseng Date: Fri, 13 Sep 2024 12:54:48 +0200 Subject: [PATCH] Update migration docs --- .bundle/config | 2 + .tool-versions | 2 +- Gemfile | 1 + Gemfile.lock | 370 ++++++++++++++---------- docs/CONTRIBUTING.md | 4 +- docs/Makefile | 44 +++ docs/_includes/carbonads.html | 2 +- docs/guides/migrating-to-2.0.md | 87 ------ docs/guides/migrating-to-3.0.md | 64 ---- docs/guides/migrating-to-4.0.md | 13 - docs/guides/migrating-to-5.0.md | 49 ---- docs/guides/migrating-to-6.0.md | 9 - docs/guides/migrating-to-7.0.md | 9 - docs/guides/migration-guide.md | 288 ++++++++++++++++++ docs/release-source/release/spy-call.md | 2 +- docs/release-source/release/utils.md | 2 +- docs/releases.md | 8 +- package-lock.json | 8 +- package.json | 13 +- scripts/update-compatibility.cjs | 7 +- 20 files changed, 584 insertions(+), 400 deletions(-) create mode 100644 .bundle/config create mode 100644 docs/Makefile delete mode 100644 docs/guides/migrating-to-2.0.md delete mode 100644 docs/guides/migrating-to-3.0.md delete mode 100644 docs/guides/migrating-to-4.0.md delete mode 100644 docs/guides/migrating-to-5.0.md delete mode 100644 docs/guides/migrating-to-6.0.md delete mode 100644 docs/guides/migrating-to-7.0.md create mode 100644 docs/guides/migration-guide.md diff --git a/.bundle/config b/.bundle/config new file mode 100644 index 000000000..236922881 --- /dev/null +++ b/.bundle/config @@ -0,0 +1,2 @@ +--- +BUNDLE_PATH: "vendor/bundle" diff --git a/.tool-versions b/.tool-versions index 3c5a334db..f37e5c950 100644 --- a/.tool-versions +++ b/.tool-versions @@ -1,2 +1,2 @@ nodejs 22.2.0 -ruby 2.7.8 +ruby 3.2.2 diff --git a/Gemfile b/Gemfile index b14096e7b..5bf626ca4 100644 --- a/Gemfile +++ b/Gemfile @@ -3,3 +3,4 @@ gem 'github-pages', group: :jekyll_plugins gem "jekyll", "~> 3.7" gem 'jekyll-sitemap' gem 'jekyll-toc' +gem 'html-proofer' diff --git a/Gemfile.lock b/Gemfile.lock index f6dfc40c2..604d865fb 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,100 +1,146 @@ GEM remote: https://rubygems.org/ specs: - activesupport (6.0.3.4) - concurrent-ruby (~> 1.0, >= 1.0.2) - i18n (>= 0.7, < 2) - minitest (~> 5.1) - tzinfo (~> 1.1) - zeitwerk (~> 2.2, >= 2.2.2) - addressable (2.8.0) - public_suffix (>= 2.0.2, < 5.0) + Ascii85 (1.1.1) + activesupport (7.2.1) + base64 + bigdecimal + concurrent-ruby (~> 1.0, >= 1.3.1) + connection_pool (>= 2.2.5) + drb + i18n (>= 1.6, < 2) + logger (>= 1.4.2) + minitest (>= 5.1) + securerandom (>= 0.3) + tzinfo (~> 2.0, >= 2.0.5) + addressable (2.8.7) + public_suffix (>= 2.0.2, < 7.0) + afm (0.2.2) + async (2.17.0) + console (~> 1.26) + fiber-annotation + io-event (~> 1.6, >= 1.6.5) + base64 (0.2.0) + bigdecimal (3.1.8) coffee-script (2.4.1) coffee-script-source execjs - coffee-script-source (1.11.1) + coffee-script-source (1.12.2) colorator (1.1.0) - commonmarker (0.17.13) - ruby-enum (~> 0.5) - concurrent-ruby (1.1.7) - dnsruby (1.61.5) - simpleidn (~> 0.1) - em-websocket (0.5.2) + commonmarker (0.23.10) + concurrent-ruby (1.3.4) + connection_pool (2.4.1) + console (1.27.0) + fiber-annotation + fiber-local (~> 1.1) + json + csv (3.3.0) + dnsruby (1.72.2) + simpleidn (~> 0.2.1) + drb (2.2.1) + em-websocket (0.5.3) eventmachine (>= 0.12.9) - http_parser.rb (~> 0.6.0) - ethon (0.12.0) - ffi (>= 1.3.0) + http_parser.rb (~> 0) + ethon (0.16.0) + ffi (>= 1.15.0) eventmachine (1.2.7) - execjs (2.7.0) - faraday (1.3.0) - faraday-net_http (~> 1.0) - multipart-post (>= 1.2, < 3) - ruby2_keywords - faraday-net_http (1.0.0) - ffi (1.14.2) + execjs (2.9.1) + faraday (2.11.0) + faraday-net_http (>= 2.0, < 3.4) + logger + faraday-net_http (3.3.0) + net-http + ffi (1.17.0-aarch64-linux-gnu) + ffi (1.17.0-aarch64-linux-musl) + ffi (1.17.0-arm-linux-gnu) + ffi (1.17.0-arm-linux-musl) + ffi (1.17.0-arm64-darwin) + ffi (1.17.0-x86-linux-gnu) + ffi (1.17.0-x86-linux-musl) + ffi (1.17.0-x86_64-darwin) + ffi (1.17.0-x86_64-linux-gnu) + ffi (1.17.0-x86_64-linux-musl) + fiber-annotation (0.2.0) + fiber-local (1.1.0) + fiber-storage + fiber-storage (1.0.0) forwardable-extended (2.6.0) - gemoji (3.0.1) - github-pages (209) - github-pages-health-check (= 1.16.1) - jekyll (= 3.9.0) - jekyll-avatar (= 0.7.0) - jekyll-coffeescript (= 1.1.1) - jekyll-commonmark-ghpages (= 0.1.6) - jekyll-default-layout (= 0.1.4) - jekyll-feed (= 0.15.1) + gemoji (4.1.0) + github-pages (232) + github-pages-health-check (= 1.18.2) + jekyll (= 3.10.0) + jekyll-avatar (= 0.8.0) + jekyll-coffeescript (= 1.2.2) + jekyll-commonmark-ghpages (= 0.5.1) + jekyll-default-layout (= 0.1.5) + jekyll-feed (= 0.17.0) jekyll-gist (= 1.5.0) - jekyll-github-metadata (= 2.13.0) + jekyll-github-metadata (= 2.16.1) + jekyll-include-cache (= 0.2.1) jekyll-mentions (= 1.6.0) jekyll-optional-front-matter (= 0.3.2) jekyll-paginate (= 1.1.0) jekyll-readme-index (= 0.3.0) jekyll-redirect-from (= 0.16.0) jekyll-relative-links (= 0.6.1) - jekyll-remote-theme (= 0.4.2) + jekyll-remote-theme (= 0.4.3) jekyll-sass-converter (= 1.5.2) - jekyll-seo-tag (= 2.6.1) + jekyll-seo-tag (= 2.8.0) jekyll-sitemap (= 1.4.0) jekyll-swiss (= 1.0.0) - jekyll-theme-architect (= 0.1.1) - jekyll-theme-cayman (= 0.1.1) - jekyll-theme-dinky (= 0.1.1) - jekyll-theme-hacker (= 0.1.2) - jekyll-theme-leap-day (= 0.1.1) - jekyll-theme-merlot (= 0.1.1) - jekyll-theme-midnight (= 0.1.1) - jekyll-theme-minimal (= 0.1.1) - jekyll-theme-modernist (= 0.1.1) - jekyll-theme-primer (= 0.5.4) - jekyll-theme-slate (= 0.1.1) - jekyll-theme-tactile (= 0.1.1) - jekyll-theme-time-machine (= 0.1.1) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) jekyll-titles-from-headings (= 0.5.3) - jemoji (= 0.12.0) - kramdown (= 2.3.0) + jemoji (= 0.13.0) + kramdown (= 2.4.0) kramdown-parser-gfm (= 1.1.0) - liquid (= 4.0.3) + liquid (= 4.0.4) mercenary (~> 0.3) minima (= 2.5.1) - nokogiri (>= 1.10.4, < 2.0) - rouge (= 3.23.0) + nokogiri (>= 1.16.2, < 2.0) + rouge (= 3.30.0) terminal-table (~> 1.4) - github-pages-health-check (1.16.1) + webrick (~> 1.8) + github-pages-health-check (1.18.2) addressable (~> 2.3) dnsruby (~> 1.60) - octokit (~> 4.0) - public_suffix (~> 3.0) + octokit (>= 4, < 8) + public_suffix (>= 3.0, < 6.0) typhoeus (~> 1.3) - html-pipeline (2.14.0) + hashery (2.1.2) + html-pipeline (2.14.3) activesupport (>= 2) nokogiri (>= 1.4) - http_parser.rb (0.6.0) - i18n (0.9.5) + html-proofer (5.0.9) + addressable (~> 2.3) + async (~> 2.1) + nokogiri (~> 1.13) + pdf-reader (~> 2.11) + rainbow (~> 3.0) + typhoeus (~> 1.3) + yell (~> 2.0) + zeitwerk (~> 2.5) + http_parser.rb (0.8.0) + i18n (1.14.5) concurrent-ruby (~> 1.0) - jekyll (3.9.0) + io-event (1.6.5) + jekyll (3.10.0) addressable (~> 2.4) colorator (~> 1.0) + csv (~> 3.0) em-websocket (~> 0.5) - i18n (~> 0.7) + i18n (>= 0.7, < 2) jekyll-sass-converter (~> 1.0) jekyll-watch (~> 2.0) kramdown (>= 1.17, < 3) @@ -103,27 +149,30 @@ GEM pathutil (~> 0.9) rouge (>= 1.7, < 4) safe_yaml (~> 1.0) - jekyll-avatar (0.7.0) + webrick (>= 1.0) + jekyll-avatar (0.8.0) jekyll (>= 3.0, < 5.0) - jekyll-coffeescript (1.1.1) + jekyll-coffeescript (1.2.2) coffee-script (~> 2.2) - coffee-script-source (~> 1.11.1) - jekyll-commonmark (1.3.1) - commonmarker (~> 0.14) - jekyll (>= 3.7, < 5.0) - jekyll-commonmark-ghpages (0.1.6) - commonmarker (~> 0.17.6) - jekyll-commonmark (~> 1.2) - rouge (>= 2.0, < 4.0) - jekyll-default-layout (0.1.4) - jekyll (~> 3.0) - jekyll-feed (0.15.1) + coffee-script-source (~> 1.12) + jekyll-commonmark (1.4.0) + commonmarker (~> 0.22) + jekyll-commonmark-ghpages (0.5.1) + commonmarker (>= 0.23.7, < 1.1.0) + jekyll (>= 3.9, < 4.0) + jekyll-commonmark (~> 1.4.0) + rouge (>= 2.0, < 5.0) + jekyll-default-layout (0.1.5) + jekyll (>= 3.0, < 5.0) + jekyll-feed (0.17.0) jekyll (>= 3.7, < 5.0) jekyll-gist (1.5.0) octokit (~> 4.2) - jekyll-github-metadata (2.13.0) + jekyll-github-metadata (2.16.1) jekyll (>= 3.4, < 5.0) - octokit (~> 4.0, != 4.4.0) + octokit (>= 4, < 7, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) jekyll-mentions (1.6.0) html-pipeline (~> 2.3) jekyll (>= 3.7, < 5.0) @@ -136,138 +185,167 @@ GEM jekyll (>= 3.3, < 5.0) jekyll-relative-links (0.6.1) jekyll (>= 3.3, < 5.0) - jekyll-remote-theme (0.4.2) + jekyll-remote-theme (0.4.3) addressable (~> 2.0) jekyll (>= 3.5, < 5.0) jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) rubyzip (>= 1.3.0, < 3.0) jekyll-sass-converter (1.5.2) sass (~> 3.4) - jekyll-seo-tag (2.6.1) - jekyll (>= 3.3, < 5.0) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) jekyll-sitemap (1.4.0) jekyll (>= 3.7, < 5.0) jekyll-swiss (1.0.0) - jekyll-theme-architect (0.1.1) - jekyll (~> 3.5) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-cayman (0.1.1) - jekyll (~> 3.5) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-dinky (0.1.1) - jekyll (~> 3.5) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-hacker (0.1.2) + jekyll-theme-hacker (0.2.0) jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-leap-day (0.1.1) - jekyll (~> 3.5) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-merlot (0.1.1) - jekyll (~> 3.5) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-midnight (0.1.1) - jekyll (~> 3.5) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-minimal (0.1.1) - jekyll (~> 3.5) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-modernist (0.1.1) - jekyll (~> 3.5) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-primer (0.5.4) + jekyll-theme-primer (0.6.0) jekyll (> 3.5, < 5.0) jekyll-github-metadata (~> 2.9) jekyll-seo-tag (~> 2.0) - jekyll-theme-slate (0.1.1) - jekyll (~> 3.5) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-tactile (0.1.1) - jekyll (~> 3.5) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-time-machine (0.1.1) - jekyll (~> 3.5) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) jekyll-titles-from-headings (0.5.3) jekyll (>= 3.3, < 5.0) - jekyll-toc (0.18.0) + jekyll-toc (0.19.0) jekyll (>= 3.9) nokogiri (~> 1.12) jekyll-watch (2.2.1) listen (~> 3.0) - jemoji (0.12.0) - gemoji (~> 3.0) + jemoji (0.13.0) + gemoji (>= 3, < 5) html-pipeline (~> 2.2) jekyll (>= 3.0, < 5.0) - kramdown (2.3.0) + json (2.7.2) + kramdown (2.4.0) rexml kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) - liquid (4.0.3) - listen (3.4.0) + liquid (4.0.4) + listen (3.9.0) rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) + logger (1.6.1) mercenary (0.3.6) - mini_portile2 (2.8.6) minima (2.5.1) jekyll (>= 3.5, < 5.0) jekyll-feed (~> 0.9) jekyll-seo-tag (~> 2.1) - minitest (5.14.3) - multipart-post (2.1.1) - nokogiri (1.16.5) - mini_portile2 (~> 2.8.2) + minitest (5.25.1) + net-http (0.4.1) + uri + nokogiri (1.16.7-aarch64-linux) racc (~> 1.4) - octokit (4.20.0) - faraday (>= 0.9) - sawyer (~> 0.8.0, >= 0.5.3) + nokogiri (1.16.7-arm-linux) + racc (~> 1.4) + nokogiri (1.16.7-arm64-darwin) + racc (~> 1.4) + nokogiri (1.16.7-x86-linux) + racc (~> 1.4) + nokogiri (1.16.7-x86_64-darwin) + racc (~> 1.4) + nokogiri (1.16.7-x86_64-linux) + racc (~> 1.4) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (3.1.1) - racc (1.7.3) - rb-fsevent (0.10.4) - rb-inotify (0.10.1) + pdf-reader (2.12.0) + Ascii85 (~> 1.0) + afm (~> 0.2.1) + hashery (~> 2.0) + ruby-rc4 + ttfunk + public_suffix (5.1.1) + racc (1.8.1) + rainbow (3.1.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) ffi (~> 1.0) - rexml (3.2.8) - strscan (>= 3.0.9) - rouge (3.23.0) - ruby-enum (0.8.0) - i18n - ruby2_keywords (0.0.2) - rubyzip (2.3.0) + rexml (3.3.7) + rouge (3.30.0) + ruby-rc4 (0.1.5) + rubyzip (2.3.2) safe_yaml (1.0.5) sass (3.7.4) sass-listen (~> 4.0.0) sass-listen (4.0.0) rb-fsevent (~> 0.9, >= 0.9.4) rb-inotify (~> 0.9, >= 0.9.7) - sawyer (0.8.2) + sawyer (0.9.2) addressable (>= 2.3.5) - faraday (> 0.8, < 2.0) - simpleidn (0.1.1) - unf (~> 0.1.4) - strscan (3.1.0) + faraday (>= 0.17.3, < 3) + securerandom (0.3.1) + simpleidn (0.2.3) terminal-table (1.8.0) unicode-display_width (~> 1.1, >= 1.1.1) - thread_safe (0.3.6) - typhoeus (1.4.0) + ttfunk (1.8.0) + bigdecimal (~> 3.1) + typhoeus (1.4.1) ethon (>= 0.9.0) - tzinfo (1.2.10) - thread_safe (~> 0.1) - unf (0.1.4) - unf_ext - unf_ext (0.0.7.7) - unicode-display_width (1.7.0) - zeitwerk (2.4.2) + tzinfo (2.0.6) + concurrent-ruby (~> 1.0) + unicode-display_width (1.8.0) + uri (0.13.1) + webrick (1.8.1) + yell (2.2.2) + zeitwerk (2.6.18) PLATFORMS - ruby + aarch64-linux + aarch64-linux-gnu + aarch64-linux-musl + arm-linux + arm-linux-gnu + arm-linux-musl + arm64-darwin + x86-linux + x86-linux-gnu + x86-linux-musl + x86_64-darwin + x86_64-linux + x86_64-linux-gnu + x86_64-linux-musl DEPENDENCIES github-pages + html-proofer jekyll (~> 3.7) jekyll-sitemap jekyll-toc BUNDLED WITH - 1.17.3 + 2.5.18 diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 7d4057a38..a4032d3d5 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -23,13 +23,11 @@ However, if you're going to contribute changes that alter the overall structure cd docs # ensure you have bundler -gem install bundler # install all dependencies -bundle install --path vendor/bundle # build, serve and live-reload the site -npm run dev-docs +npm run serve-docs ``` After that you can access the site at http://localhost:4000/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..ed081e12c --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,44 @@ +# Just check out https://makefile.site + +# otherwise Make assumes that all install targets are files & folders +.PHONY: install deploy livereload build help list-targets + +help: + @make print S="These are the possible make targets you can invoke" + @make list-targets + +install: + @command -v bundle > /dev/null || (make print S="Missing Bundler. Installing" && gem install bundler ) + bundle install + @# this is just to get the output as the final line + @make check-dependencies + +copy-over-sinon-script: + @[[ -e assets/js/sinon.js ]] || npm run build && cp ../pkg/sinon.js assets/js/ + +check-dependencies: + @command -v git-lfs > /dev/null || (make print S="You need to install Git LFS before committing changes" && exit 1) + +check-links: copy-over-sinon-script + bundle exec htmlproofer --assume-extension='.html' --ignore-status-codes="403" --no-enforce-https ./_site/ + +deploy: check-dependencies + git push + +livereload: + bundle exec jekyll serve --trace --livereload --host localhost --incremental + +# only for checking out the final build +# # only for checking out the final build +build: + bundle exec jekyll build + +### UTILS ### + +#https://stackoverflow.com/a/26339924/200987 +list-targets: + @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 + +print: + @printf "\033[01;35m%s\033[00m\n" "$(S)" + diff --git a/docs/_includes/carbonads.html b/docs/_includes/carbonads.html index 7af74da3d..90f8ec961 100644 --- a/docs/_includes/carbonads.html +++ b/docs/_includes/carbonads.html @@ -1 +1 @@ - + diff --git a/docs/guides/migrating-to-2.0.md b/docs/guides/migrating-to-2.0.md deleted file mode 100644 index 1e3cc8905..000000000 --- a/docs/guides/migrating-to-2.0.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -layout: page -title: Migrating to v2.0 - Sinon.JS -breadcrumb: migrating to 2.0 ---- - -Sinon v2.0 is the second major release, we have made several breaking changes in this release as a result of modernising the internals of Sinon. This guide is intended to walk you through the changes. - -## sinon.log and sinon.logError Removed - -`sinon.log` and `sinon.logError` were used in Sinon v1.x to globally configure `FakeServer`, `FakeXMLHttpRequest` and `FakeXDomainRequest`; these three functions now allow the logger to be configured on a per-use basis. In v1.x you may have written: - -```js -sinon.log = function (msg) { // your logging impl }; -``` - -You would now individually import and configure the utility upon creation: - -```js -var sinon = require("sinon"); - -var myFakeServer = sinon.fakeServer.create({ - logger: function (msg) { // your logging impl } -}); -``` - -## sinon.test, sinon.testCase and sinon.config Removed - -`sinon.test` and `sinon.testCase` have been extracted from the Sinon API and moved into their own node module, [sinon-test](https://www.npmjs.com/package/sinon-test). Please refer to the [sinon-test README](https://github.com/sinonjs/sinon-test/blob/master/README.md) for migration examples. - -## stub.callsFake replaces stub(obj, 'meth', fn) - -`sinon.stub(obj, 'meth', fn)` return a spy, not a full stub. Behavior could not be redefined. `stub.callsFake` -now returns a full stub. Here's a [codemod script](https://github.com/hurrymaplelad/sinon-codemod) to help you migrate. -See [discussion](https://github.com/sinonjs/sinon/pull/823). - -```js -// Old -sinon.stub(obj, "meth", fn); -// New -sinon.stub(obj, "meth").callsFake(fn); -``` - -## stub.resetHistory replaces stub.reset - -`stub.reset()` now resets the history and the behaviour of the stub. Previously `stub.reset()` only reset the history of the stub. Stubs now have separate methods for resetting the history and the behaviour. To mimic the old behaviour replace all `stub.reset()` calls with `stub.resetHistory()`. - -```js -// Old -stub.reset(); -// New -stub.resetHistory(); -``` - -## 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: - -- `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` - -## `sandbox.useFakeXMLHttpRequest` no longer returns a "server" - -In Sinon 1.x, the sandbox' `useFakeXMLHttpRequest` was the same as its `useFakeServer`. In 2.x, it maps directly to `sinon.useFakeXMLHttpRequest` (but with sandboxing). If you use `sandbox.useFakeXMLHttpRequest`, replace it with `sandbox.useFakeServer`, and your tests should behave as they always did. - -## `sinon.behavior` is gone - -The `sinon.behavior` object is no longer exposed for random modification. However, there is a new mechanism in place aided to add new behavior to stubs, `sinon.addBehavior(name, fn)`, see the stub docs. diff --git a/docs/guides/migrating-to-3.0.md b/docs/guides/migrating-to-3.0.md deleted file mode 100644 index 4778a28fc..000000000 --- a/docs/guides/migrating-to-3.0.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -layout: page -title: Migrating to v3.0 - Sinon.JS -breadcrumb: migrating to 3.0 ---- - -As with all `MAJOR` releases in [`semver`](http://semver.org/), there are breaking changes in `sinon@3`. -This guide will walk you through those changes. - -## `sinon.stub(object, "method", func)` - Removed - -Please use `sinon.stub(obj, "method").callsFake(func)` instead. - -```js -var stub = sinon.stub(obj, "stubbedMethod").callsFake(function () { - return 42; -}); -``` - -A [codemod is available](https://github.com/hurrymaplelad/sinon-codemod) to upgrade your code - -## `sinon.stub(object, property, value)` - Removed - -Calling `sinon.stub` with three arguments will throw an Error. This was deprecated with `sinon@2` and has been removed with `sinon@3` - -## `sinon.useFakeTimers([now, ]prop1, prop2, ...)` - Removed - -`sinon.useFakeTimers()` signature has [changed](../fake-timers). To define which methods to fake, please use `config.toFake`. Other options are now available when configuring `useFakeTimers`. Please consult the [documentation](../fake-timers) for more information. - -## `sinon.sandbox.create(config)` - Config changes - -The [changes in configuration](../fake-timers) for fake timers implicitly affect sandbox creation. If your config used to look like `{ useFaketimers: ["setTimeout", "setInterval"]}`, you -will now need to change it to `{ useFaketimers: { toFake: ["setTimeout", "setInterval"] }}`. - -## `sandbox.stub(obj, 'nonExistingProperty')` - Throws - -Trying to stub a non-existing property will now fail to ensure you are creating -[less error-prone tests](https://github.com/sinonjs/sinon/issues/1537#issuecomment-323948482). - -## Removal of internal helpers - -The following internal functions were deprecated as of `sinon@1.x` and have been removed in `sinon@3`: - -- `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` diff --git a/docs/guides/migrating-to-4.0.md b/docs/guides/migrating-to-4.0.md deleted file mode 100644 index 82319b461..000000000 --- a/docs/guides/migrating-to-4.0.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: page -title: Migrating to v4.0 - Sinon.JS -breadcrumb: migrating to 4.0 ---- - -As with all `MAJOR` releases in [`semver`](http://semver.org/), there are breaking changes in `sinon@4`. -This guide will walk you through those changes. - -## `sinon.stub(obj, 'nonExistingProperty')` - Throws - -Trying to stub a non-existing property will now fail, to ensure you are creating -[less error-prone tests](https://github.com/sinonjs/sinon/pull/1557). diff --git a/docs/guides/migrating-to-5.0.md b/docs/guides/migrating-to-5.0.md deleted file mode 100644 index 1c40b1346..000000000 --- a/docs/guides/migrating-to-5.0.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -layout: page -title: Migrating to v5.0 - Sinon.JS -breadcrumb: migrating to 5.0 ---- - -As with all `MAJOR` releases in [`semver`](http://semver.org/), there are breaking changes in `sinon@5`. -This guide will walk you through those changes. - -## `spy.reset()` is removed, use `spy.resetHistory()` - -In a previous version we deprecated and aliased `spy.reset` in favour of using `spy.resetHistory`. `spy.reset` has now been removed, you should use `spy.resetHistory`. - -## `sinon` is now a (default) sandbox - -Since `sinon@5.0.0`, the `sinon` object is a default sandbox. Unless you have a very advanced setup or need a special configuration, you probably want to only use that one. - -The old sandbox API is still available, so you don't **have** to do anything. - -However, switching to using the default sandbox can help make your code more concise. -Now would be a good opportunity to tidy up your tests. - -### Before `sinon@5.0.0` - -In earlier versions, you would manually have to create sandboxes and keep references to them in order to restore them. - -```js -const sandbox = sinon.createSandbox(); - -describe("myFunction", function () { - afterEach(function () { - sandbox.restore(); - }); - - it("should make pie"); -}); -``` - -### From `sinon@5.0.0` - -```js -describe("myFunction", function () { - afterEach(function () { - sinon.restore(); - }); - - it("should make pie"); -}); -``` diff --git a/docs/guides/migrating-to-6.0.md b/docs/guides/migrating-to-6.0.md deleted file mode 100644 index c46ee6afd..000000000 --- a/docs/guides/migrating-to-6.0.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: page -title: Migrating to v6.0 - Sinon.JS -breadcrumb: migrating to 6.0 ---- - -There should be no reason for any code changes with the new Sinon 6. Usually, `MAJOR` releases should come with breaking changes, but there are no known breaking changes in `sinon@6` at the time of this writing. We chose to release a new major version as a [pragmatic solution to some noise related to releasing Sinon 5.1](https://github.com/sinonjs/sinon/pull/1829#issue-193284761), which featured some breaking changes related to ESM (which since has been resolved). - -If you should experience any issues moving from Sinon 5 to Sinon 6, [please let us know!](https://github.com/sinonjs/sinon/issues/new?template=Bug_report.md). diff --git a/docs/guides/migrating-to-7.0.md b/docs/guides/migrating-to-7.0.md deleted file mode 100644 index 4c2157a5a..000000000 --- a/docs/guides/migrating-to-7.0.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: page -title: Migrating to v7.0 - Sinon.JS -breadcrumb: migrating to 7.0 ---- - -For users upgrading to Sinon 7 the only known breaking API change is that **negative ticks** are not allowed in `Sinon@7` due to updating to lolex 3 internally. This means you cannot use negative values in sinon.useFakeTimers().tick(); - -If you experience any issues moving from Sinon 6 to Sinon 7, [please let us know!](https://github.com/sinonjs/sinon/issues/new?template=Bug_report.md). diff --git a/docs/guides/migration-guide.md b/docs/guides/migration-guide.md new file mode 100644 index 000000000..fff48e585 --- /dev/null +++ b/docs/guides/migration-guide.md @@ -0,0 +1,288 @@ +--- +layout: page +title: Migrating between versions +breadcrumb: migrating +--- + +## Sinon 19 + +A breaking change is that Fake Timers 13 now fake all timers by default. Previously +a couple of timers were explicitly ignored, but this no longer applies. +If you want the old behavior, specify the `toFake` option and leave the name +of the timers giving you trouble. + +The new version of fake-timers also no longer creating dates using the original Date +class, but a subclass (proxy). This should not matter unless you are doing some kind +of identity checks on the constructor: functionally they are the same. + +Removal of `legacyRoutes` option that was enabled in a previous `nise` version as the +underlying library, `path-to-regexp`, had a fundamental change to its parsing that +made the option a no-op. + +## Sinon 18 + +Mostly removal of some deprecated exports related to `sinon-test`, such as +sinon.defaultConfig and related modules. + +## Sinon 17 + +Drops support for Node 16 + +## Sinon 15 + +Removes option to pass a custom formatter. + +## Sinon 7 + +For users upgrading to Sinon 7 the only known breaking API change is that +**negative ticks** are not allowed in `Sinon@7` due to updating to lolex 3 +internally. This means you cannot use negative values in +sinon.useFakeTimers().tick(); + +If you experience any issues moving from Sinon 6 to Sinon 7, please let us +know! https://github.com/sinonjs/sinon/issues/new?template=Bug_report.md. + +## Sinon 6 + +There should be no reason for any code changes with the new Sinon 6. +Usually, `MAJOR` releases should come with breaking changes, but there are +no known breaking changes in `sinon@6` at the time of this writing. We chose +to release a new major version as a pragmatic solution to some noise related +to releasing Sinon 5.1 https://github.com/sinonjs/sinon/pull/1829#issue- +193284761, which featured some breaking changes related to ESM (which since +has been resolved). + +If you should experience any issues moving from Sinon 5 to Sinon 6, please +let us know! +https://github.com/sinonjs/sinon/issues/new?template=Bug_report.md. + +## Sinon 5 + +As with all `MAJOR` releases in semver http://semver.org/, there are +breaking changes in `sinon@5`. +This guide will walk you through those changes. + +## `spy.reset()` is removed, use `spy.resetHistory()` + +In a previous version we deprecated and aliased `spy.reset` in favour of +using `spy.resetHistory`. `spy.reset` has now been removed, you should use +`spy.resetHistory`. + +## `sinon` is now a (default) sandbox + +Since `sinon@5.0.0`, the `sinon` object is a default sandbox. Unless you +have a very advanced setup or need a special configuration, you probably +want to only use that one. + +The old sandbox API is still available, so you don't **have** to do +anything. + +However, switching to using the default sandbox can help make your code more +concise. +Now would be a good opportunity to tidy up your tests. + +### Before `sinon@5.0.0` + +In earlier versions, you would manually have to create sandboxes and keep +references to them in order to restore them. + +const sandbox = sinon.createSandbox(); + +describe("myFunction", function () { +afterEach(function () { +sandbox.restore(); +}); + +it("should make pie"); +}); + +### From `sinon@5.0.0` + +describe("myFunction", function () { +afterEach(function () { +sinon.restore(); +}); + +it("should make pie"); +}); + +## Sinon 4 + +As with all `MAJOR` releases in semver http://semver.org/, there are +breaking changes in `sinon@4`. +This guide will walk you through those changes. + +## `sinon.stub(obj, 'nonExistingProperty')` - Throws + +Trying to stub a non-existing property will now fail, to ensure you are +creating +less error-prone tests https://github.com/sinonjs/sinon/pull/1557. + +## Sinon 3 + +As with all `MAJOR` releases in semver http://semver.org/, there are +breaking changes in `sinon@3`. +This guide will walk you through those changes. + +## `sinon.stub(object, "method", func)` - Removed + +Please use `sinon.stub(obj, "method").callsFake(func)` instead. + +var stub = sinon.stub(obj, "stubbedMethod").callsFake(function () { +return 42; +}); + +A codemod is available https://github.com/hurrymaplelad/sinon-codemod to +upgrade your code + +## `sinon.stub(object, property, value)` - Removed + +Calling `sinon.stub` with three arguments will throw an Error. This was +deprecated with `sinon@2` and has been removed with `sinon@3` + +## `sinon.useFakeTimers([now, ]prop1, prop2, ...)` - Removed + +`sinon.useFakeTimers()` signature has changed +To define which methods to fake, +please use `config.toFake`. Other options are now available when configuring +`useFakeTimers`. Please consult the documentation for more information. + +## `sinon.sandbox.create(config)` - Config changes + +The changes in configuration for fake timers implicitly affect sandbox creation. +If your config used to look +like `{ useFaketimers: ["setTimeout", "setInterval"]}`, you +will now need to change it to `{ useFaketimers: { toFake: ["setTimeout", +"setInterval"] }}`. + +## `sandbox.stub(obj, 'nonExistingProperty')` - Throws + +Trying to stub a non-existing property will now fail to ensure you are +creating +less error-prone tests +https://github.com/sinonjs/sinon/issues/1537#issuecomment-323948482. + +## Removal of internal helpers + +The following internal functions were deprecated as of `sinon@1.x` and have +been removed in `sinon@3`: + +• `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` + +## Sinon 2 + +Sinon v2.0 is the second major release, we have made several breaking +changes in this release as a result of modernising the internals of Sinon. +This guide is intended to walk you through the changes. + +## sinon.log and sinon.logError Removed + +`sinon.log` and `sinon.logError` were used in Sinon v1.x to globally +configure `FakeServer`, `FakeXMLHttpRequest` and `FakeXDomainRequest`; these +three functions now allow the logger to be configured on a per-use basis. In +v1.x you may have written: + +sinon.log = function (msg) { // your logging impl }; + +You would now individually import and configure the utility upon creation: + +var sinon = require("sinon"); + +var myFakeServer = sinon.fakeServer.create({ +logger: function (msg) { // your logging impl } +}); + +## sinon.test, sinon.testCase and sinon.config Removed + +`sinon.test` and `sinon.testCase` have been extracted from the Sinon API and +moved into their own node module, sinon-test +https://www.npmjs.com/package/sinon-test. Please refer to the sinon-test +README https://github.com/sinonjs/sinon-test/blob/master/README.md for +migration examples. + +## stub.callsFake replaces stub(obj, 'meth', fn) + +`sinon.stub(obj, 'meth', fn)` return a spy, not a full stub. Behavior could +not be redefined. `stub.callsFake` +now returns a full stub. Here's a codemod script +https://github.com/hurrymaplelad/sinon-codemod to help you migrate. +See discussion https://github.com/sinonjs/sinon/pull/823. + +// Old +sinon.stub(obj, "meth", fn); +// New +sinon.stub(obj, "meth").callsFake(fn); + +## stub.resetHistory replaces stub.reset + +`stub.reset()` now resets the history and the behaviour of the stub. +Previously `stub.reset()` only reset the history of the stub. Stubs now have +separate methods for resetting the history and the behaviour. To mimic the +old behaviour replace all `stub.reset()` calls with `stub.resetHistory()`. + +// Old +stub.reset(); +// New +stub.resetHistory(); + +## 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: + +• `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` + +## `sandbox.useFakeXMLHttpRequest` no longer returns a "server" + +In Sinon 1.x, the sandbox' `useFakeXMLHttpRequest` was the same as its +`useFakeServer`. In 2.x, it maps directly to `sinon.useFakeXMLHttpRequest` +(but with sandboxing). If you use `sandbox.useFakeXMLHttpRequest`, replace +it with `sandbox.useFakeServer`, and your tests should behave as they always +did. + +## `sinon.behavior` is gone + +The `sinon.behavior` object is no longer exposed for random modification. +However, there is a new mechanism in place aided to add new behavior to +stubs, `sinon.addBehavior(name, fn)`, see the stub docs. diff --git a/docs/release-source/release/spy-call.md b/docs/release-source/release/spy-call.md index 5ac862ca1..8f379b914 100644 --- a/docs/release-source/release/spy-call.md +++ b/docs/release-source/release/spy-call.md @@ -6,7 +6,7 @@ breadcrumb: spy-call ## Spy call -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). +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/). ### `var spyCall = spy.getCall(n)` diff --git a/docs/release-source/release/utils.md b/docs/release-source/release/utils.md index 98f1e6da0..dbf54fbda 100644 --- a/docs/release-source/release/utils.md +++ b/docs/release-source/release/utils.md @@ -24,7 +24,7 @@ stubContainer.contains.returns(false); stubContainer.contains.withArgs("item").returns(true); ``` -The given constructor function is not invoked. See also the [stub API](../stubs). +The given constructor function is not invoked. See also the [stub API](../stubs/). ### `sinon.restoreObject(object);` diff --git a/docs/releases.md b/docs/releases.md index 2597e2e7a..cdc7cf09a 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -21,7 +21,13 @@ redirect_from: -{% include docs/migration-guides.md %} +### Migration guide + +The [migration guide](/guides/migration-guide) covers what to think about +when migrating to a new major version. Mostly, you should not really be +practically affected by most of the major version jumps: it's mostly trivial +stuff like dropping support for a version of Node or some very minute +detail of an implementation some people _might_ depend upon.