@things-factory/labeling 9.1.19

package/MIGRATION_GUIDE.md

@@ -0,0 +1,310 @@
+# Migration Guide: labeling-scenario → labeling (workflow)
+
+## Overview
+
+This guide covers the migration from the old `labeling-scenario` implementation in `@things-factory/integration-label-studio` to the new `@things-factory/labeling` package with `workflow` terminology.
+
+## What Changed
+
+### 1. Package Structure
+
+**Before:**
+```
+packages/integration-label-studio/
+  server/
+    types/scenario-types.ts
+    service/labeling-scenario-service.ts
+```
+
+**After:**
+```
+packages/labeling/                    # NEW PACKAGE
+  server/
+    types/workflow-types.ts           # Renamed from scenario-types
+    service/labeling-workflow-service.ts  # Renamed from labeling-scenario-service
+```
+
+### 2. Terminology Changes
+
+All `Scenario` terms have been renamed to `Workflow`:
+
+| Old Term | New Term |
+|----------|----------|
+| `LabelingScenario` | `LabelingWorkflow` |
+| `ScenarioStep` | `WorkflowStep` |
+| `ScenarioStepType` | `WorkflowStepType` |
+| `ScenarioStatus` | `WorkflowStatus` |
+| `ScenarioExecution` | `WorkflowExecution` |
+| `ScenarioExecutionStep` | `WorkflowExecutionStep` |
+| `CreateScenarioRequest` | `CreateWorkflowRequest` |
+| `ExecuteScenarioRequest` | `ExecuteWorkflowRequest` |
+| `LabelingScenarioList` | `LabelingWorkflowList` |
+| `ScenarioExecutionList` | `WorkflowExecutionList` |
+| `LabelingScenarioService` | `LabelingWorkflowService` |
+
+### 3. GraphQL API Changes
+
+#### Mutations
+
+| Old Mutation | New Mutation |
+|-------------|-------------|
+| `createLabelingScenario` | `createLabelingWorkflow` |
+| `executeScenario` | `executeLabelingWorkflow` |
+| `pauseScenario` | `pauseLabelingWorkflow` |
+| `resumeScenario` | `resumeLabelingWorkflow` |
+
+#### Queries
+
+| Old Query | New Query |
+|-----------|-----------|
+| `labelingScenario` | `labelingWorkflow` |
+| `labelingScenarios` | `labelingWorkflows` |
+| `scenarioExecution` | `workflowExecution` |
+| `scenarioExecutions` | `workflowExecutions` |
+
+#### Arguments
+
+| Old Argument | New Argument |
+|-------------|-------------|
+| `scenarioId` | `workflowId` |
+
+## Migration Steps
+
+### For Backend Code
+
+1. **Update package dependencies** in your `package.json`:
+
+   ```json
+   {
+     "dependencies": {
+       "@things-factory/labeling": "^9.1.0"
+     }
+   }
+   ```
+
+2. **Update imports**:
+
+   **Before:**
+   ```typescript
+   import {
+     LabelingScenario,
+     ScenarioStep,
+     CreateScenarioRequest
+   } from '@things-factory/integration-label-studio/dist-server/types/scenario-types.js'
+   ```
+
+   **After:**
+   ```typescript
+   import {
+     LabelingWorkflow,
+     WorkflowStep,
+     CreateWorkflowRequest
+   } from '@things-factory/labeling/dist-server/types/workflow-types.js'
+   ```
+
+3. **Update type references** in your code:
+
+   ```typescript
+   // Replace all occurrences
+   LabelingScenario → LabelingWorkflow
+   ScenarioStep → WorkflowStep
+   ScenarioStatus → WorkflowStatus
+   // etc.
+   ```
+
+### For GraphQL Queries/Mutations
+
+1. **Update mutation calls**:
+
+   **Before:**
+   ```graphql
+   mutation {
+     createLabelingScenario(input: {
+       name: "My Scenario"
+       projectId: 123
+       steps: [...]
+     }) {
+       id
+       name
+     }
+   }
+   ```
+
+   **After:**
+   ```graphql
+   mutation {
+     createLabelingWorkflow(input: {
+       name: "My Workflow"
+       projectId: 123
+       steps: [...]
+     }) {
+       id
+       name
+     }
+   }
+   ```
+
+2. **Update query calls**:
+
+   **Before:**
+   ```graphql
+   query {
+     labelingScenarios(projectId: 123) {
+       items {
+         id
+         name
+       }
+     }
+   }
+   ```
+
+   **After:**
+   ```graphql
+   query {
+     labelingWorkflows(projectId: 123) {
+       items {
+         id
+         name
+       }
+     }
+   }
+   ```
+
+3. **Update execution calls**:
+
+   **Before:**
+   ```graphql
+   mutation {
+     executeScenario(input: {
+       scenarioId: "uuid"
+     }) {
+       executionId
+     }
+   }
+   ```
+
+   **After:**
+   ```graphql
+   mutation {
+     executeLabelingWorkflow(input: {
+       workflowId: "uuid"
+     }) {
+       executionId
+     }
+   }
+   ```
+
+### For Frontend Code
+
+1. **Update GraphQL query strings** in your components:
+
+   ```typescript
+   // Before
+   const GET_SCENARIOS = gql`
+     query {
+       labelingScenarios {
+         items {
+           id
+           name
+         }
+       }
+     }
+   `
+
+   // After
+   const GET_WORKFLOWS = gql`
+     query {
+       labelingWorkflows {
+         items {
+           id
+           name
+         }
+       }
+     }
+   `
+   ```
+
+2. **Update component props and state**:
+
+   ```typescript
+   // Before
+   interface Props {
+     scenario: LabelingScenario
+   }
+
+   // After
+   interface Props {
+     workflow: LabelingWorkflow
+   }
+   ```
+
+## Breaking Changes
+
+### 1. GraphQL Schema
+
+All GraphQL operations have new names. Old operations will not work and must be updated.
+
+### 2. Package Location
+
+The service is no longer in `@things-factory/integration-label-studio`. You must add `@things-factory/labeling` as a dependency.
+
+### 3. Privilege Categories
+
+The privilege category has changed from `"label-studio"` to `"labeling"`:
+
+**Before:**
+```typescript
+@Directive('@privilege(category: "label-studio", privilege: "mutation")')
+```
+
+**After:**
+```typescript
+@Directive('@privilege(category: "labeling", privilege: "mutation")')
+```
+
+You may need to update your user roles and permissions accordingly.
+
+## Backward Compatibility
+
+**There is NO backward compatibility.** This is a breaking change that requires:
+
+1. Updating all code references
+2. Updating all GraphQL queries/mutations
+3. Migrating any stored scenario data (if applicable)
+
+The old files have been marked as `.deprecated` in `integration-label-studio` and will be removed in a future version.
+
+## Data Migration
+
+If you have existing scenario data stored in a database or configuration:
+
+1. Export existing scenario definitions
+2. Transform field names: `scenarioId` → `workflowId`, etc.
+3. Update GraphQL type names in JSON configs
+4. Re-import using the new workflow API
+
+## Testing Checklist
+
+- [ ] All imports updated to use `@things-factory/labeling`
+- [ ] All type references changed from `Scenario*` to `Workflow*`
+- [ ] All GraphQL queries/mutations updated
+- [ ] Privilege categories updated to `"labeling"`
+- [ ] Frontend components updated
+- [ ] Integration tests passing
+- [ ] End-to-end workflow execution verified
+
+## Support
+
+If you encounter issues during migration, please:
+
+1. Check this guide for common problems
+2. Review the [README.md](./README.md) for usage examples
+3. Contact the Things-Factory team
+
+## Timeline
+
+- **Current Version**: `9.1.0` - New `@things-factory/labeling` package introduced
+- **Deprecation**: Old scenario files marked as `.deprecated`
+- **Future Version**: Old files will be removed entirely
+
+Please migrate as soon as possible to avoid disruption.