ci: add a minimal v1 to v2 transition setup

.github/workflows/ci.yaml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, v2]
   pull_request:
 
 jobs:
@@ -40,4 +40,4 @@ jobs:
     - name: Unit Tests
       run: npm run test
     # - name: ESBuild compatability
-      # run: npm run test:esbuild
+      # run: npm run test:esbuild

.github/workflows/e2e.yml

@@ -2,35 +2,37 @@ name: E2E Tests
 
 on:
   workflow_dispatch:
+  push:
+    branches: [main, v2]
   pull_request:
 
 jobs:
   e2e_tests:
     name: E2E Tests
     runs-on: ubuntu-latest
     timeout-minutes: 15
-    
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-        
+
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: npm
-          
+
       - name: Install dependencies
         run: npm ci
-        
+
       - name: Install Playwright browsers
         run: npx playwright install --with-deps chromium
-        
+
       - name: Run E2E tests
         run: npm run test:e2e:ci
         env:
           CI: true
-        
+
       - name: Test installed Playwright consumer
         run: npm run test:package-contract
         env:
@@ -43,7 +45,7 @@ jobs:
           name: playwright-report
           path: playwright-report/
           retention-days: 7
-          
+
       - name: Upload test screenshots
         if: failure()
         uses: actions/upload-artifact@v4

.github/workflows/release-v2.yml

@@ -0,0 +1,39 @@
+name: Release v2 prerelease
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        type: choice
+        description: Use premajor once for 2.0.0-next.0, then prerelease for later versions
+        default: prerelease
+        options:
+          - prerelease
+          - premajor
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    # workflow_dispatch can be started from any ref; only v2 may mint a token.
+    if: github.ref == 'refs/heads/v2'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate token
+        id: generate-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.GRAVITY_UI_APP_ID }}
+          private-key: ${{ secrets.GRAVITY_UI_APP_PRIVATE_KEY }}
+      - name: Release v2 prerelease
+        uses: gravity-ui/release-action@v1
+        with:
+          github-token: ${{ steps.generate-token.outputs.token }}
+          npm-token: ${{ secrets.GRAVITY_UI_BOT_NPM_TOKEN }}
+          # CI, E2E, and previews test the project on Node 20. The release action
+          # intentionally uses Node 24 to match the existing v1 release workflow.
+          node-version: 24
+          npm-version: ${{ inputs.version }}
+          npm-dist-tag: next
+          npm-preid: next

.github/workflows/v2-preview.yml

@@ -0,0 +1,31 @@
+name: V2 Preview
+
+on:
+  push:
+    branches: [v2]
+
+jobs:
+  v2:
+    name: Build and Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Install Packages
+        run: npm ci
+        shell: bash
+      - name: Build Storybook
+        run: npm run build-storybook
+        shell: bash
+      - name: Upload to S3
+        uses: gravity-ui/preview-upload-to-s3-action@v1
+        with:
+          src-path: storybook-static
+          dest-path: /graph/v2/
+          s3-key-id: ${{ secrets.STORYBOOK_S3_KEY_ID }}
+          s3-secret-key: ${{ secrets.STORYBOOK_S3_SECRET_KEY }}

CONTRIBUTING.md

@@ -33,4 +33,6 @@ It is enough to provide us such notification once.
 
 ## Other questions
 
-If you have any questions, please mail us at opensource@yandex-team.ru.
+If you have any questions, please mail us at opensource@yandex-team.ru.
+
+See the [v1/v2 transition guide](docs/v1-v2-transition.md) for branch and release guidance during the v2 work.

docs/v1-v2-transition.md

@@ -0,0 +1,78 @@
+# v1 to v2 transition
+
+This guide describes the temporary branch and release setup while Gravity Graph
+v2 is developed. It is intentionally small and is expected to be retired after
+the transition.
+
+## Before cutover
+
+`main` remains the stable v1 branch. It is the default branch and accepts only
+maintenance work needed by current users:
+
+- bug fixes;
+- security fixes;
+- v1 documentation fixes.
+
+New features, broad refactors, and breaking changes belong on `v2`.
+
+The release channels are:
+
+| Branch | Versions          | npm dist-tag |
+| ------ | ----------------- | ------------ |
+| `main` | stable `1.x`      | `latest`     |
+| `v2`   | `2.x` prereleases | `next`       |
+
+The existing v1 release workflow continues to handle `main` and maintenance
+release branches. V2 prereleases are started manually with the `Release v2
+prerelease` workflow. On the first run from the current v1 version, select
+`premajor` to publish `2.0.0-next.0`. Select `prerelease` on later runs to
+increment the prerelease version. The workflow runs only from the `v2` branch
+and publishes under `next`.
+
+CI and E2E run for pull requests and for pushes to both `main` and `v2`.
+Storybook previews are separate:
+
+- `main`: `/graph/main/`;
+- `v2`: `/graph/v2/`.
+
+## Choosing a pull request target
+
+Target `main` only when a change is required for the supported v1 line. Target
+`v2` for v2 development and for changes that do not need to ship in v1.
+
+If a fix is needed in both versions, land the v1 fix in `main` first. The two
+maintainers then decide whether it applies to v2. Most changes should not need a
+special process: make the decision in the issue or pull request discussion.
+
+When the v1 change applies to v2, open a reviewed pull request that merges
+`main` into `v2`. Resolve conflicts in favor of the intended v2 behavior. Do
+not automate this synchronization or run it on a schedule; it should happen
+only for the occasional relevant v1 change.
+
+When a v1 change does not apply, no port or registry entry is required. A short
+note in the issue or pull request is enough when the reason is not obvious.
+
+## Cutover
+
+Cutover happens only when v2 is ready to replace v1. The maintainers should:
+
+1. publish the final v1 release from `main`;
+2. create `release/v1` from that final v1 state;
+3. perform one final reviewed synchronization from `main` to `v2`;
+4. verify the final v2 prerelease under `next`;
+5. make the v2 line the new `main`;
+6. publish stable `2.x` under `latest`.
+
+After cutover, `main` is the stable v2 branch and `release/v1` is used only for
+necessary v1 maintenance. Release workflow configuration can be adjusted as
+part of the cutover change; it is not preconfigured in this temporary setup.
+
+## Practical limits
+
+Do not create `release/v1` before cutover. Do not publish a v2 prerelease under
+`latest`. Do not merge v2-only development back into the pre-cutover `main`
+branch.
+
+For this short transition, normal pull request review and the existing release
+action are the approval mechanism. No additional role system, SHA ledger,
+ruleset framework, or scheduled synchronization process is required.