docs(devs-infra): prepare docs for v27 (#2614)

website/versioned_docs/version-27.0/babel7-or-ts.md

@@ -0,0 +1,76 @@
+---
+id: babel7-or-ts
+title: Babel7 or TypeScript
+---
+
+In Sept. 2018 Babel7 got released with an interesting preset: `@babel/preset-typescript`.
+
+The goal is to make it easy for users using Babel to try TypeScript without moving out from Babel, just by adding a preset in their Babel config (here is the [MSDN blog post](https://blogs.msdn.microsoft.com/typescript/2018/08/27/typescript-and-babel-7/) about TypeScript and Babel 7).
+
+## Limitations
+
+While `@babel/preset-typescript` is a great preset, you must know the limitation of it. Here is what is possible with TypeScript (and `ts-jest`), which is not with Babel7 and `@babel/preset-typescript`:
+
+#### No type-checking
+
+This is the big **PRO** of using TypeScript vs Babel, you have type-checking out of the box.
+
+You'll get a more fluent TDD experience (when using `ts-jest`) since files will be type-checked at the same time they're compiled and ran.
+
+Here TypeScript will throw while Babel won't:
+
+```ts
+const str: string = 42
+```
+
+With Babel, files are transpiled as isolated modules, there is no notion of "project". With TypeScript, files are part of a project and are compiled in that scope.
+
+---
+
+#### No `namespace`
+
+```ts
+namespace app {
+  export const VERSION = '1.0.0'
+  export class App {
+    /* ... */
+  }
+}
+```
+
+---
+
+#### No `const enum`
+
+```ts
+const enum Directions {
+  Up,
+  Down,
+  Left,
+  Right,
+}
+```
+
+---
+
+#### No declaration merging (`enum`, `namespace`, ...)
+
+You won't be able to do [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html).
+
+---
+
+#### No legacy `import`/`export`
+
+```ts
+import lib = require('lib')
+// ...
+export = myVar
+```
+
+---
+
+#### No caret type-casting with JSX enabled
+
+```ts
+const val = <string>input
+```

website/versioned_docs/version-27.0/contributing.md

@@ -0,0 +1,174 @@
+---
+id: contributing
+title: Contributing
+---
+
+When contributing to this repository, please first discuss the change you wish to make via [`ts-jest` GitHub discussion](https://github.com/kulshekhar/ts-jest/discussions) or [issue](https://github.com/kulshekhar/ts-jest/issues) with the owners of this repository before making a change.
+
+Please note we have a code of conduct, please follow it in all your interactions with the project.
+
+## Pull Request Process
+
+1. Ensure the tests are passing and that you have latest `master` branch merged in.
+2. Update the `docs/` with details of your changes if required.
+3. If possible, squash your commits. There must be only one commit in your PR (until a review). Then after each review requesting changes, DO NOT squash your commits with the one before the review, so that we can see intermediate modifications.
+4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
+
+_These are internal technical documents. If you're not a contributor to `ts-jest`, but simply trying to use the library you'll find nothing of value here_
+
+## E2E Testing
+
+### Preparing
+
+The preparation of E2E test directory is done in `scripts/e2e.js`. Here is the process:
+
+```plantuml
+start
+
+:bundle ts-jest;
+note right
+will build ts-jest before creating the bundle
+end note
+
+:create temp work dir;
+note right
+`e2e/~__workdir_symlink__` links to it
+except on CI environments
+end note
+
+while (for each template)
+note right
+templates are in `e2e/~__templates__/`
+end note
+
+if (template's build directory) then (exists)
+:wipe but `node_modules` dir;
+else (not exists)
+:create;
+endif
+
+:copy files from template's dir to its build dir;
+
+if (package lock file) then (exists)
+:read metadata;
+
+    if (package lock file) then (has changed)
+      :remove `node_modules` dir;
+
+      :npm install (or ci);
+
+      :npm install ts-jest bundle;
+
+    else if (ts-jest bundle) then (has changed)
+      :npm install ts-jest bundle;
+
+    else (hasn't changed)
+    endif
+    :write updated metadata;
+
+else (not exists)
+endif
+
+endwhile (done)
+
+:all templates ready;
+
+stop
+```
+
+### Running
+
+When a test-case needs to be run with a given template within tests, here is what's happening (in `e2e/__helpers__/test-case/runtime.ts`):
+
+```plantuml
+start
+
+:create work dir;
+note right
+It'll be different per test-case
+and per template basis.
+end note
+-> e2e/~__workdir_symlink__/{template}/{test-case};
+
+if (has a node_modules dir?) then (yes)
+:symlink node_modules;
+note left
+avoid re-running npm install
+for each test case and template;
+end note
+else (no)
+endif
+
+:copy files from template;
+note right
+all files in template dir are
+copied to test case work dir
+except `node_modules` and
+`package-lock.json`
+end note
+
+while (for each file in test case dir)
+if (is snapshot dir) then (yes)
+:symlink dir;
+note left
+snapshots directories are symlinked
+to test case source dir so that
+updating them would update in the
+source folder
+end note
+
+else if (is jest.config.js) then (yes)
+if (jest.config.js is function?) then (yes)
+:call with parent content;
+note left
+allows for
+extending
+end note
+else (no)
+endif
+
+else (others)
+:copy;
+note right
+all files in test case source
+dir are copied to the work dir
+except `node_modules` and
+`package-lock.json`
+end note
+
+endif
+endwhile
+
+:create special files;
+note right
+some special files are created
+to handle hooks for example and
+grab `process()` IO for later
+expectations
+end note
+
+:update package.json;
+note right
+set a custom but fixed name
+and version in package.json
+which is specific to the
+test case + template
+end note
+
+#tomato:run tests;
+
+while (for each snapshot) is (missing in test case)
+:copy;
+note right
+while we symlinked each snapshots
+directory, newly created snapshots
+in non existing dir will need to
+be copied over into
+e2e/~__cases__/{test-case}
+end note
+endwhile
+
+:return results;
+
+stop
+```

website/versioned_docs/version-27.0/debugging.md

@@ -0,0 +1,22 @@
+---
+id: debugging
+title: Debugging ts-jest
+---
+
+You can activate the debug logger by setting the environment variable `TS_JEST_LOG` before running tests.
+The output of the logger will be in **ts-jest.log** in current working directory.
+
+The debug logger contains some useful information about how internal `ts-jest` works, including which files are processed,
+which Jest config or TypeScript config is used etc.
+
+**Linux/MacOS**
+
+```
+export TS_JEST_LOG=ts-jest.log
+```
+
+**Windows**
+
+```
+set TS_JEST_LOG=ts-jest.log
+```

website/versioned_docs/version-27.0/getting-started/installation.md

@@ -0,0 +1,58 @@
+---
+id: installation
+title: Installation
+---
+
+### Dependencies
+
+You can install `ts-jest` and dependencies all at once with one of the following commands.
+
+#### NPM
+
+```sh
+npm install --save-dev jest typescript ts-jest @types/jest
+```
+
+#### Yarn
+
+```sh
+yarn add --dev jest typescript ts-jest @types/jest
+```
+
+:::tip
+
+Tip: If you get an error with the following `npm` commands such as `npx: command not found`, you can replace `npx XXX` with `node node_modules/.bin/XXX` from the root of your project.
+
+:::
+
+### Jest config file
+
+#### Creating
+
+By default, Jest can run without any config files, but it will not compile `.ts` files.
+To make it transpile TypeScript with `ts-jest`, we will need to create a configuration file that will tell Jest to use a `ts-jest` preset.
+
+`ts-jest` can create the configuration file for you automatically:
+
+#### NPM
+
+```sh
+npx ts-jest config:init
+```
+
+#### Yarn
+
+```sh
+yarn ts-jest config:init
+```
+
+This will create a basic Jest configuration file which will inform Jest about how to handle `.ts` files correctly.
+
+You can also use the `jest --init` command (prefixed with either `npx` or `yarn` depending on what you're using) to have more options related to Jest.
+However, answer `no` to the Jest question about whether or not to enable TypeScript. Instead, add the line: `preset: "ts-jest"` to the `jest.config.js` file afterwards.
+
+#### Customizing
+
+For customizing jest, please follow their [official guide online](https://jestjs.io/docs/en/configuration.html).
+
+`ts-jest` specific options can be found [here](options).