Reverted the squashed commit for #2426 to reintroduce as proper merge

.prettierignore

@@ -5,4 +5,8 @@ tmp/
 .sass-cache
 docs/_site/
 docs/js/
+docs/releases/
+docs/_releases/
 docs/assets/js/
+CHANGELOG.md
+docs/changelog.md

CHANGES.md

@@ -1,5 +1,6 @@
 # Changes
 
+<<<<<<< HEAD
 ## 13.0.0
 
 - [`cf3d6c0c`](https://github.com/sinonjs/sinon/commit/cf3d6c0cd9689c0ee673b3daa8bf9abd70304392)
@@ -201,6 +202,8 @@
 
 _Released by [Carl-Erik Kopseng](https://github.com/fatso83) on 2022-01-28._
 
+=======
+>>>>>>> parent of 41710467 (Adjust deploy scripts to archive old releases in a separate branch, move existing releases out of master (#2426))
 ## 12.0.1
 
 - [`3f598221`](https://github.com/sinonjs/sinon/commit/3f598221045904681f2b3b3ba1df617ed5e230e3)

RELEASE.md

@@ -9,9 +9,9 @@ The release process is mostly automated, here is a brief overview of the steps
    - Updates `AUTHORS`
    - Updates `package.json` with new version
    - Creates a new git tag
+   - Copies new release documentation into place in `docs/_releases/`, using the new release id
 2. `npm publish` publishes the new release to the npm registry
 3. `git push origin --follow-tags` pushes the changes to GitHub
-4. Archive the new release in the `releases` branch under the new release id
 
 Each step is described in detail below.
 

docs/_config.yml

@@ -5,7 +5,11 @@ description: >-
 url: 'https://sinonjs.org'
 github_username: sinonjs
 sinon:
+<<<<<<< HEAD
   current_release: v13.0.0
+=======
+  current_release: v12.0.1
+>>>>>>> parent of 41710467 (Adjust deploy scripts to archive old releases in a separate branch, move existing releases out of master (#2426))
 markdown: kramdown
 kramdown:
   input: GFM

docs/_releases/latest.md

@@ -0,0 +1,39 @@
+---
+layout: page
+title: API documentation - Sinon.JS
+skip_ad: true
+release_id: v12.0.1
+---
+
+# {{page.title}} - `{{page.release_id}}`
+
+This page contains the entire Sinon.JS API documentation along with brief introductions to the concepts Sinon implements.
+
+- [General setup](./general-setup)
+- [Fakes](./fakes)
+- [Spies](./spies)
+- [Stubs](./stubs)
+- [Mocks](./mocks)
+- [Spy calls](./spy-call)
+- [Promises](./promises)
+- [Fake timers](./fake-timers)
+- [Fake <code>XHR</code> and server](./fake-xhr-and-server)
+- [JSON-P](./json-p)
+- [Assertions](./assertions)
+- [Matchers](./matchers)
+- [Sandboxes](./sandbox)
+- [Utils](./utils)
+
+{% include docs/migration-guides.md %}
+
+## Compatibility and supported runtimes
+
+As of Sinon 10 we stopped maintaining compatibility with legacy browsers. Instead, we focus on compatibility with evergreen browsers, [Node.js LTS versions](https://github.com/nodejs/Release) and recent Safari versions.
+The most up-to-date reference on which runtimes and browsers we support can be found by looking at our [compatibility docs][compat-doc].
+
+If you need to support old runtimes you can try [Sinon 9][compat-doc-v9].
+
+{% include docs/contribute.md %}
+
+[compat-doc]: https://github.com/sinonjs/sinon/COMPATIBILITY.md
+[compat-doc-v9]: https://github.com/sinonjs/sinon/blob/v9.2.4/COMPATIBILITY.md

docs/_releases/latest/assertions.md

@@ -0,0 +1,190 @@
+---
+layout: page
+title: Assertions - Sinon.JS
+breadcrumb: assertions
+---
+
+Sinon.JS ships with a set of assertions that mirror most behavior verification methods and properties on spies and stubs. The advantage of using the assertions is that failed expectations on stubs and spies can be expressed directly as assertion failures with detailed and helpful error messages.
+
+To make sure assertions integrate nicely with your test framework, you should customize either `sinon.assert.fail` or `sinon.assert.failException` and look into `sinon.assert.expose` and `sinon.assert.pass`.
+
+The assertions can be used with either spies or stubs.
+
+```javascript
+"test should call subscribers with message as first argument" : function () {
+    var message = "an example message";
+    var spy = sinon.spy();
+
+    PubSub.subscribe(message, spy);
+    PubSub.publishSync(message, "some payload");
+
+    sinon.assert.calledOnce(spy);
+    sinon.assert.calledWith(spy, message);
+}
+```
+
+## Assertions API
+
+#### `sinon.assert.fail(message)`
+
+Every assertion fails by calling this method.
+
+By default it throws an error of type `sinon.assert.failException`.
+
+If the test framework looks for assertion errors by checking for a specific exception, you can override the kind of exception thrown. If that does not fit with your testing framework of choice, override the `fail` method to do the right thing.
+
+#### `sinon.assert.failException;`
+
+Defaults to `AssertError`.
+
+#### `sinon.assert.pass(assertion);`
+
+Called every time `assertion` passes.
+
+Default implementation does nothing.
+
+#### `sinon.assert.notCalled(spy);`
+
+Passes if `spy` was never called
+
+#### `sinon.assert.called(spy);`
+
+Passes if `spy` was called at least once.
+
+#### `sinon.assert.calledOnce(spy);`
+
+Passes if `spy` was called once and only once.
+
+#### `sinon.assert.calledTwice(spy);`
+
+Passes if `spy` was called exactly twice.
+
+#### `sinon.assert.calledThrice(spy)`
+
+Passes if `spy` was called exactly three times.
+
+#### `sinon.assert.callCount(spy, num)`
+
+Passes if `spy` was called exactly `num` times.
+
+#### `sinon.assert.callOrder(spy1, spy2, ...)`
+
+Passes if provided spies were called in the specified order.
+
+#### `sinon.assert.calledOn(spyOrSpyCall, obj)`
+
+Passes if `spy` was ever called with `obj` as its `this` value.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledOn(spy.firstCall, arg1, arg2, ...);`.
+
+#### `sinon.assert.alwaysCalledOn(spy, obj)`
+
+Passes if `spy` was always called with `obj` as its `this` value.
+
+#### `sinon.assert.calledWith(spyOrSpyCall, arg1, arg2, ...);`
+
+Passes if `spy` was called with the provided arguments.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledWith(spy.firstCall, arg1, arg2, ...);`.
+
+#### `sinon.assert.alwaysCalledWith(spy, arg1, arg2, ...);`
+
+Passes if `spy` was always called with the provided arguments.
+
+#### `sinon.assert.neverCalledWith(spy, arg1, arg2, ...);`
+
+Passes if `spy` was never called with the provided arguments.
+
+#### `sinon.assert.calledWithExactly(spyOrSpyCall, arg1, arg2, ...);`
+
+Passes if `spy` was called with the provided arguments and no others.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledWithExactly(spy.getCall(1), arg1, arg2, ...);`.
+
+#### `sinon.assert.calledOnceWithExactly(spyOrSpyCall, arg1, arg2, ...);`
+
+Passes if `spy` was called once and only once with the provided arguments and no others.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledOnceWithExactly(spy.getCall(1), arg1, arg2, ...);`.
+
+#### `sinon.assert.alwaysCalledWithExactly(spy, arg1, arg2, ...);`
+
+Passes if `spy` was always called with the provided arguments and no others.
+
+#### `sinon.assert.calledWithMatch(spyOrSpyCall, arg1, arg2, ...)`
+
+Passes if `spy` was called with matching arguments.
+
+This behaves the same way as `sinon.assert.calledWith(spy, sinon.match(arg1), sinon.match(arg2), ...)`.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledWithMatch(spy.secondCall, arg1, arg2, ...);`.
+
+#### `sinon.assert.alwaysCalledWithMatch(spy, arg1, arg2, ...)`
+
+Passes if `spy` was always called with matching arguments.
+
+This behaves the same way as `sinon.assert.alwaysCalledWith(spy, sinon.match(arg1), sinon.match(arg2), ...)`.
+
+#### `sinon.assert.calledWithNew(spyOrSpyCall)`
+
+Passes if `spy` was called with the `new` operator.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledWithNew(spy.secondCall, arg1, arg2, ...);`.
+
+#### `sinon.assert.neverCalledWithMatch(spy, arg1, arg2, ...)`
+
+Passes if `spy` was never called with matching arguments.
+
+This behaves the same way as `sinon.assert.neverCalledWith(spy, sinon.match(arg1), sinon.match(arg2), ...)`.
+
+#### `sinon.assert.threw(spyOrSpyCall, exception);`
+
+Passes if `spy` threw the given exception.
+
+The exception can be a `String` denoting its type, or an actual object.
+
+If only one argument is provided, the assertion passes if `spy` ever threw any exception.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.threw(spy.thirdCall, exception);`.
+
+#### `sinon.assert.alwaysThrew(spy, exception);`
+
+Like above, only required for all calls to the spy.
+
+#### `sinon.assert.match(actual, expectation);`
+
+Uses [`sinon.match`](../matchers) to test if the arguments can be considered a match.
+
+```javascript
+var sinon = require("sinon");
+
+describe("example", function () {
+  it("should match on `x` property, and ignore `y` property", function () {
+    var expected = { x: 1 },
+      actual = { x: 1, y: 2 };
+
+    sinon.assert.match(actual, expected);
+  });
+});
+```
+
+#### `sinon.assert.expose(object, options);`
+
+Exposes assertions into another object, to better integrate with the test framework. For instance, JsTestDriver uses global assertions, and to make Sinon.JS assertions appear alongside them, you can do.
+
+```javascript
+sinon.assert.expose(this);
+```
+
+This will give you `assertCalled(spy)`,`assertCallOrder(spy1, spy2, ...)` and so on.
+
+The method accepts an optional options object with two options.
+
+<dl>
+    <dt>prefix</dt>
+    <dd>is a prefix to give assertions. By default it is "assert", so <code>sinon.assert.called</code> becomes <code>target.assertCalled</code>. By passing a blank string, the exposed method will be <code>target.called</code>.</dd>
+
+    <dt>includeFail</dt>
+    <dd><code>true</code> by default, copies over the <code>fail</code> and <code>failException</code> properties</dd>
+
+</dl>

docs/_releases/latest/examples/.eslintrc.yml

@@ -0,0 +1,17 @@
+env:
+  es6: true
+
+parserOptions:
+  ecmaVersion: 2017
+
+extends:
+  - ../../../../test/.eslintrc.yml
+
+rules:
+  no-underscore-dangle: off
+  no-console: off
+  no-empty-function: off
+  mocha/no-setup-in-describe: off
+  no-var: error
+  prefer-const: error
+  strict: off # cannot use strict mode in RunKit due to it using `with` tricks

docs/_releases/latest/examples/.gitignore

@@ -0,0 +1 @@
+package-lock.json

docs/_releases/latest/examples/fakes-1-using-fakes-instead-of-spies.test.js

@@ -0,0 +1,17 @@
+require("@fatso83/mini-mocha").install();
+const sinon = require("sinon");
+const referee = require("@sinonjs/referee");
+const assert = referee.assert;
+
+describe("FakeTest", function () {
+    it("should be able to be used instead of spies", function () {
+        const foo = {
+            bar: () => "baz",
+        };
+        // wrap existing method without changing its behaviour
+        const fake = sinon.replace(foo, "bar", sinon.fake(foo.bar));
+
+        assert.equals(fake(), "baz"); // behaviour is the same
+        assert.equals(fake.callCount, 1); // calling information is saved
+    });
+});

docs/_releases/latest/examples/fakes-10-firstArg.test.js

@@ -0,0 +1,17 @@
+require("@fatso83/mini-mocha").install();
+const sinon = require("sinon");
+const referee = require("@sinonjs/referee");
+const assert = referee.assert;
+
+describe("FakeTest", function () {
+    it("should have working firstArg", function () {
+        const f = sinon.fake();
+        const date1 = new Date();
+        const date2 = new Date();
+
+        f(date1, 1, 2);
+        f(date2, 1, 2);
+
+        assert.isTrue(f.firstArg === date2);
+    });
+});

docs/_releases/latest/examples/fakes-11-lastArg.test.js

@@ -0,0 +1,21 @@
+require("@fatso83/mini-mocha").install();
+const sinon = require("sinon");
+const referee = require("@sinonjs/referee");
+const assert = referee.assert;
+
+describe("FakeTest", function () {
+    it("should have working lastArg", function () {
+        const f = sinon.fake();
+        const date1 = new Date();
+        const date2 = new Date();
+
+        f(1, 2, date1);
+        f(1, 2, date2);
+
+        assert.isTrue(f.lastArg === date2);
+        // spy call methods:
+        assert.isTrue(f.getCall(0).lastArg === date1);
+        assert.isTrue(f.getCall(1).lastArg === date2);
+        assert.isTrue(f.lastCall.lastArg === date2);
+    });
+});

docs/_releases/latest/examples/fakes-12-adding-fake-to-system-under-test.test.js

@@ -0,0 +1,20 @@
+require("@fatso83/mini-mocha").install();
+const sinon = require("sinon");
+const referee = require("@sinonjs/referee");
+const assert = referee.assert;
+
+describe("FakeTest", function () {
+    it("should be able to be added to the system under test", function () {
+        const fake = sinon.fake.returns("42");
+
+        sinon.replace(console, "log", fake);
+
+        assert.equals(console.log("apple pie"), 42);
+
+        // restores all replaced properties set by sinon methods (replace, spy, stub)
+        sinon.restore();
+
+        assert.equals(console.log("apple pie"), undefined);
+        assert.equals(fake.callCount, 1);
+    });
+});

docs/_releases/latest/examples/fakes-2-using-fakes-instead-of-stubs.test.js

@@ -0,0 +1,21 @@
+require("@fatso83/mini-mocha").install();
+const sinon = require("sinon");
+const referee = require("@sinonjs/referee");
+const assert = referee.assert;
+
+describe("FakeTest", function () {
+    it("should be able to be used instead of stubs", function () {
+        const foo = {
+            bar: () => "baz",
+        };
+        // replace method with a fake one
+        const fake = sinon.replace(
+            foo,
+            "bar",
+            sinon.fake.returns("fake value")
+        );
+
+        assert.equals(fake(), "fake value"); // returns fake value
+        assert.equals(fake.callCount, 1); // saves calling information
+    });
+});