docs: add braking change documentation for semgrep action update

docs/breaking-changes/v2.md

@@ -0,0 +1,82 @@
+# Breaking Changes for v2
+
+## Introduction
+
+The v2 version of the open-turo/actions-security repository introduces a significant refactoring of the Semgrep configuration path. These changes are designed to enhance maintainability and consistency across consuming repositories. However, this update may require action from repositories using older configurations to prevent workflow disruptions.
+
+## Breaking Change Details
+
+### 1. Refactored Path for security-scan.yaml
+
+- _What Changed_:
+
+  - The action.yaml file for Semgrep has been moved from:
+
+    open-turo/actions-security/static-analysis/semgrep@v1
+
+    _to:_
+
+    open-turo/actions-security/static-analysis@v2
+
+- _Impact_:
+  - Any workflow file referencing the old path (static-analysis/semgrep@v1) will fail to locate the action and result in pipeline failures.
+
+## Migration Instructions
+
+### Step 1: Update Workflow Files
+
+1. Locate all GitHub Actions workflow files in your repository referencing static-analysis/semgrep.
+2. Update the uses field to point to the new path:
+   ```yaml
+   - uses: open-turo/actions-security/static-analysis@v2
+   ```
+
+### Step 2: Validate Workflow
+
+1. After updating the workflow, run the GitHub Actions pipeline to ensure it works as expected.
+2. Monitor the pipeline logs for any issues related to the Semgrep action.
+
+---
+
+## Troubleshooting
+
+### Common Errors
+
+- _Error_: Failed to locate action: open-turo/actions-security/static-analysis/semgrep@v1
+
+  - _Solution_: Update the uses field to open-turo/actions-security/static-analysis@v2.
+
+- _Error_: Workflow file is invalid: Unexpected value 'semgrep-app-token'
+  - _Solution_: Ensure the required secrets are configured correctly in your repository:
+    - Add SEMGREP*APP_TOKEN under \_Settings > Secrets and variables > Actions*.
+
+---
+
+### Debugging Tips
+
+- Verify that your workflow file points to static-analysis@v2.
+- Ensure that your repository has the latest version of the open-turo/actions-security action.
+
+---
+
+## Example Workflow File
+
+Below is an example of an updated GitHub Action workflow file using v2:
+
+```yaml
+name: Security scan
+on:
+  pull_request: {}
+  workflow_dispatch: {}
+  push:
+    branches: [main]
+jobs:
+  code-scan:
+    name: Security scan
+    runs-on: [self-hosted, general-ubuntu]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: open-turo/actions-security/static-analysis@v2
+        with:
+          semgrep-app-token: ${{ secrets.SEMGREP_APP_TOKEN }}
+```