add upgrading guide

docs/UpgradingGuide.md

@@ -0,0 +1,84 @@
+---
+id: upgrading-guide
+title: From v27 to v28
+---
+
+Upgrading Jest from v27 to v28? This guide aims to help refactoring your tests.
+
+## Fake Timers
+
+Fake timers were refactored to allow passing options to the underlying [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers).
+
+### `fakeTimers`
+
+The `timers` configuration option was renamed to [`fakeTimers`](Configuration.md#faketimers-object) and now takes an object with options:
+
+```diff title="jest.config.js (default)"
+- timers: 'real'
++ fakeTimers: {
++   enableGlobally: false
++ }
+```
+
+```diff title="jest.config.js"
+- timers: 'fake'
++ fakeTimers: {
++   enableGlobally: true
++ }
+```
+
+```diff title="jest.config.js"
+- timers: 'modern'
++ fakeTimers: {
++   enableGlobally: true
++ }
+```
+
+```diff title="jest.config.js"
+- timers: 'legacy'
++ fakeTimers: {
++   enableGlobally: true,
++   legacyFakeTimers: true
++ }
+```
+
+### `jest.useFakeTimers()`
+
+An object with options now should be passed to [`jest.useFakeTimers()`](JestObjectAPI.md#jestusefaketimersfaketimersconfig) as well:
+
+```diff title="fakeTimers.test.js (default)"
+- jest.useFakeTimers('modern')
++ jest.useFakeTimers()
+```
+
+Or if legacy fake timers are enabled in Jest config file, but you would like to use the default fake timers backed by `@sinonjs/fake-timers`:
+
+```diff title="fakeTimers.test.js"
+- jest.useFakeTimers('modern')
++ jest.useFakeTimers({
++   legacyFakeTimers: false
++ })
+```
+
+```diff title="fakeTimers.test.js"
+- jest.useFakeTimers('legacy')
++ jest.useFakeTimers({
++   legacyFakeTimers: true
++ })
+```
+
+## Test Environment
+
+If you are using JSDOM [test environment](Configuration.md#testenvironment-string), `jest-environment-jsdom` package now must be installed additionally:
+
+```bash npm2yarn
+npm install --save-dev jest-environment-jsdom
+```
+
+## Test Runner
+
+If you are using Jasmine [test runner](Configuration.md#testrunner-string), `jest-jasmine2` package now must be installed additionally:
+
+```bash npm2yarn
+npm install --save-dev jest-jasmine2
+```

website/sidebars.json

@@ -32,6 +32,9 @@
       "tutorial-react",
       "tutorial-react-native",
       "testing-frameworks"
+    ],
+    "Upgrade Guides": [
+      "upgrading-guide"
     ]
   },
   "api": [