Merge pull request #13 from gemini-testing/sp.migration-to-testplane

docs: add info about migration from hermione

docs/migrations/how-to-upgrade-hermione-to-testplane.mdx

@@ -0,0 +1,74 @@
+import Admonition from "@theme/Admonition";
+
+# Как обновить Hermione до Testplane
+
+<Admonition type="warning">
+Если в вашем проекте Hermione младше 8-й версии, то прочтите сначала:
+* «[Как обновить hermione до версии 4.x][how-to-upgrade-hermione-to-4]»;
+* «[Как обновить hermione до версии 5.x][how-to-upgrade-hermione-to-5]»;
+* «[Как обновить hermione до версии 6.x][how-to-upgrade-hermione-to-6]»;
+* «[Как обновить hermione до версии 7.x][how-to-upgrade-hermione-to-7]»;
+* «[Как обновить hermione до версии 8.x][how-to-upgrade-hermione-to-8]».
+
+Мы рекомендуем вам обновлять Hermione поэтапно, убеждаясь на каждом этапе, что все тесты проекта корректно выполняются.
+
+</Admonition>
+
+## Что изменилось? {#what_is_new}
+
+Этот проект ранее назывался Hermione, но со временем возникли некоторые проблемы с авторскими правами и товарными знаками, что привело к решению о ребрендинге. После некоторого обсуждения мы остановились на Testplane в качестве официального нового названия.
+Так как это изменение является простым ребрендингом, мы продолжили сквозное версионирование, вместо того, чтобы начинать версионирование заново. Таким образом, [email protected] является простой заменой [email protected].
+Testplane имеет полную обратную совместимость c Hermione — умеет читать конфиги Hermione, поддерживает ее плагины, а для более плавного переезда экспортирует сразу 2 bin-файла (testplane и hermione).
+
+## Как переехать? {#how_to_move}
+
+### 1. Заменить npm-зависимости `hermione` на `testplane` в package.json {#uninstall_hermione}
+
+```bash
+npm uninstall hermione
+npm install -D testplane
+```
+
+### 2. В вашем ts-конфиге `tsconfig.json` заменить поле `hermione` на `testplane` {#update_ts_config}
+
+```javascript
+{
+    "compilerOptions": {
+        "types": [
+            "testplane"
+        ]
+    }
+}
+```
+
+### 3. Заменить все импорты и декларации пакета hermione (при наличии) {#remove_from_code}
+
+-   `import ... from "hermione"` → `import ... from "testplane"`
+-   `require("hermione")` → `require("testplane")`
+-   `declare module "hermione"` → `declare module "testplane"`
+
+### 4. Опциональные изменения (не обязательны для переезда, но рекомендованные) {#optional_changes}
+
+-   при запуске используйте bin-файл `testplane` вместо `hermione`;
+-   переименуйте файл конфигурации `.hermione.conf.(t|j)s` в `.testplane.conf.(t|j)s`;
+-   используйте глобальный хелпер `globalThis.testplane` вместо `globalThis.hermione`;
+-   для переопределения конфига используйте переменные окружения, начинающиеся на `testplane_` вместо `hermione_`;
+-   используйте поле `testplane` вместо `hermione` в обработчиках событий;
+-   для тайпингов используйте [TestplaneCts][tp-ctx] вместо `HermioneCtx`;
+-   для получения контекста в тесте используйте свойство браузера `executionContext.testplaneCtx` вместо `executionContext.hermioneCtx`;
+-   если вы используете дефолтное значение опции [screenshotsDir][screenshotsdir], то переименуйте папку со скриншотами "hermione/screens" в "testplane/screens" иил явно укажите в конфиге значение;
+-   если вы используете дефолтное значение опции [sets.files][sets], то переименуйте вашу папку с тестами "hermione → testplane" или укажите явно значение опции.
+
+## Поддержка {#support}
+
+Если при переезде вы столкнетесь с проблемами или у вас возникнут какие-либо вопросы, то приходите в [github issues][gh-issues] — и мы обязательно вам поможем!
+
+[how-to-upgrade-hermione-to-4]: ../migrations/how-to-upgrade-hermione-to-4
+[how-to-upgrade-hermione-to-5]: ../migrations/how-to-upgrade-hermione-to-5
+[how-to-upgrade-hermione-to-6]: ../migrations/how-to-upgrade-hermione-to-6
+[how-to-upgrade-hermione-to-7]: ../migrations/how-to-upgrade-hermione-to-7
+[how-to-upgrade-hermione-to-8]: ../migrations/how-to-upgrade-hermione-to-8
+[tp-ctx]: https://github.com/gemini-testing/testplane/blob/master/docs/typescript.md#testplanectx-typings
+[screenshotsdir]: https://github.com/gemini-testing/testplane/blob/master/docs/config.md#https://github.com/gemini-testing/testplane/blob/master/docs/config.md#screenshotsdir
+[sets]: https://github.com/gemini-testing/testplane/blob/master/docs/config.md#sets
+[gh-issues]: https://github.com/gemini-testing/testplane/issues/

i18n/en/docusaurus-plugin-content-docs/current.json

@@ -11,6 +11,10 @@
         "message": "HTML Reporter",
         "description": "The label for category HTML Reporter in sidebar mainSidebar"
     },
+    "sidebar.mainSidebar.category.Migrations": {
+        "message": "Migrations",
+        "description": "The label for category Migrations in sidebar mainSidebar"
+    },
     "sidebar.mainSidebar.category.Plugins": {
         "message": "Plugins",
         "description": "The label for category Plugins in sidebar mainSidebar"

i18n/en/docusaurus-plugin-content-docs/current/migrations/how-to-upgrade-hermione-to-testplane.mdx

@@ -0,0 +1,72 @@
+import Admonition from "@theme/Admonition";
+
+# How to migrate from Hermione to Testplane
+
+<Admonition type="warning">
+If in your project Hermione is younger than the v8.x version, then read first:
+* «[How to update hermione to the v.4.x][how-to-upgrade-hermione-to-4]»;
+* «[How to update hermione to the v.5.x][how-to-upgrade-hermione-to-5]»;
+* «[How to update hermione to the v.6.x][how-to-upgrade-hermione-to-6]»;
+* «[How to update hermione to the v.7.x][how-to-upgrade-hermione-to-7]»;
+* «[How to update hermione to the v.8.x][how-to-upgrade-hermione-to-8]».
+
+We recommend updating Hermione step by step, ensuring at each stage that all project tests are executed correctly.
+
+</Admonition>
+
+## What has changed? {#what_is_new}
+
+This project was formerly known as "Hermione", but eventually some copyright and trademark issues surfaced, leading to the decision to rebrand. After some discussion, we settled on "Testplane" as the official new title. Considering this change as merely a rebranding, we've proceeded with the existing version count instead of starting anew. Thus, Testplane `v8.x` is a drop-in replacement for Hermione `v8.x`.
+
+## How to move? {#how_to_move}
+
+### 1. Replace hermione deps with tesplane in `package.json` {#uninstall_hermione}
+
+```bash
+npm uninstall hermione
+npm install -D testplane
+```
+
+### 2. Replace "hermione" with "testplane" in compilerOptions.types field of your tsconfig.json file {#update_ts_config}
+
+```javascript
+{
+    "compilerOptions": {
+        "types": [
+            "testplane"
+        ]
+    }
+}
+```
+
+### 3. Replace all imports, requires and declarations {#remove_from_code}
+
+-   `import ... from "hermione"` → `import ... from "testplane"`
+-   `require("hermione")` → `require("testplane")`
+-   `declare module "hermione"` → `declare module "testplane"`
+
+### 4. Optional changes list (these are not required, but recommended) {#optional_changes}
+
+-   use `testplane` binary instead of `hermione` binary;
+-   rename `.hermione.conf.ts`, `.hermione.conf.js` configs to `.testplane.conf.ts`, `.testplane.conf.js`;
+-   use `globalThis.testplane` helper instead of `globalThis.hermione`;
+-   use `testplane_` environment variables instead of `hermione_` environment variables;
+-   use testplane field instead of hermione on event handlers;
+-   use [TestplaneCtx][tp-ctx] instead of `HermioneCtx` type;
+-   use `executionContext.testplaneCtx` as browser property instead of `executionContext.hermioneCtx`;
+-   if you use default [screenshotsDir][screenshotsdir] value, rename "hermione/screens" directory to "testplane/screens" or specify the value "hermione/screens" explicitly;
+-   if you use default [sets.files][sets] value, move your tests from "hermione" to "testplane" directory or specify the value "hermione" explicitly.
+
+## Support {#support}
+
+If you encounter any problems during the migration or have any questions, come to [github issues][gh-issues] - and we will definitely help you!
+
+[how-to-upgrade-hermione-to-4]: ../migrations/how-to-upgrade-hermione-to-4
+[how-to-upgrade-hermione-to-5]: ../migrations/how-to-upgrade-hermione-to-5
+[how-to-upgrade-hermione-to-6]: ../migrations/how-to-upgrade-hermione-to-6
+[how-to-upgrade-hermione-to-7]: ../migrations/how-to-upgrade-hermione-to-7
+[how-to-upgrade-hermione-to-8]: ../migrations/how-to-upgrade-hermione-to-8
+[tp-ctx]: https://github.com/gemini-testing/testplane/blob/master/docs/typescript.md#testplanectx-typings
+[screenshotsdir]: https://github.com/gemini-testing/testplane/blob/master/docs/config.md#https://github.com/gemini-testing/testplane/blob/master/docs/config.md#screenshotsdir
+[sets]: https://github.com/gemini-testing/testplane/blob/master/docs/config.md#sets
+[gh-issues]: https://github.com/gemini-testing/testplane/issues/