add backtrack workflow with branch locking to prevent race conditions

.github/workflows/backtrack.yml

@@ -0,0 +1,107 @@
+name: 'Backtrack'
+
+on:
+  pull_request:
+    types:
+      - closed
+    branches:
+      - 'preview/**'
+      - 'release/**'
+
+permissions:
+  actions: read
+  contents: write
+
+concurrency:
+  group: backtrack-${{ github.base_ref }}
+  cancel-in-progress: false
+
+jobs:
+  backtrack:
+    name: 'Backtrack changes from ${{ github.base_ref }}'
+    if: ${{ github.event.pull_request.merged == true }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout ${{ github.base_ref }}'
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.base_ref }}
+          fetch-depth: 0
+          token: ${{ secrets.GH_ADMIN_TOKEN }}
+
+      - name: 'Configure git'
+        run: |
+          git config user.name "$(git log -n 1 --pretty=format:%an)"
+          git config user.email "$(git log -n 1 --pretty=format:%ae)"
+
+      - name: 'Resolve backtrack targets'
+        id: targets
+        run: |
+          base_ref="${{ github.base_ref }}"
+          if [[ "$base_ref" == preview/* ]]; then
+            version="${base_ref#preview/}"
+            echo "preview-branch=" >> $GITHUB_OUTPUT  # no intermediate branch; merge directly into develop
+            echo "develop-branch=develop/$version" >> $GITHUB_OUTPUT
+            echo "merge-source=$base_ref" >> $GITHUB_OUTPUT
+          elif [[ "$base_ref" == release/* ]]; then
+            version="${base_ref#release/}"
+            echo "preview-branch=preview/$version" >> $GITHUB_OUTPUT
+            echo "develop-branch=develop/$version" >> $GITHUB_OUTPUT
+            echo "merge-source=preview/$version" >> $GITHUB_OUTPUT
+          fi
+
+      - name: 'Check if develop branch exists'
+        id: check-develop
+        run: |
+          git fetch origin
+          if git ls-remote --exit-code --heads origin "${{ steps.targets.outputs.develop-branch }}" > /dev/null 2>&1; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+            echo "::warning::Develop branch '${{ steps.targets.outputs.develop-branch }}' not found, skipping backtrack."
+          fi
+
+      - name: 'Lock develop branch'
+        id: lock-develop
+        if: ${{ steps.check-develop.outputs.exists == 'true' }}
+        uses: './.github/actions/github/branch-protection/lock'
+        with:
+          branch: ${{ steps.targets.outputs.develop-branch }}
+          token: ${{ secrets.GH_ADMIN_TOKEN }}
+
+      - name: 'Backtrack: merge ${{ github.base_ref }} into ${{ steps.targets.outputs.preview-branch }}'
+        if: ${{ steps.targets.outputs.preview-branch != '' }}
+        run: |
+          git fetch origin
+          git checkout -B ${{ steps.targets.outputs.preview-branch }} origin/${{ steps.targets.outputs.preview-branch }}
+          git merge --no-ff origin/${{ github.base_ref }} -m "Backtrack: merge ${{ github.base_ref }} into ${{ steps.targets.outputs.preview-branch }}"
+          git push origin ${{ steps.targets.outputs.preview-branch }}
+
+      - name: 'Backtrack: merge ${{ steps.targets.outputs.merge-source }} into ${{ steps.targets.outputs.develop-branch }}'
+        if: ${{ steps.check-develop.outputs.exists == 'true' }}
+        run: |
+          git fetch origin
+          git checkout -B ${{ steps.targets.outputs.develop-branch }} origin/${{ steps.targets.outputs.develop-branch }}
+          git merge --no-ff origin/${{ steps.targets.outputs.merge-source }} -m "Backtrack: merge ${{ steps.targets.outputs.merge-source }} into ${{ steps.targets.outputs.develop-branch }}"
+          git push origin ${{ steps.targets.outputs.develop-branch }}
+
+      - name: 'Unlock develop branch'
+        if: ${{ always() && steps.lock-develop.outcome != 'skipped' }}
+        uses: './.github/actions/github/branch-protection/unlock'
+        with:
+          branch: ${{ steps.targets.outputs.develop-branch }}
+          token: ${{ secrets.GH_ADMIN_TOKEN }}
+
+      - name: 'Write backtrack summary'
+        if: ${{ always() }}
+        run: |
+          echo "## 🔁 Backtrack Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Branch | Merged from |" >> $GITHUB_STEP_SUMMARY
+          echo "|--------|-------------|" >> $GITHUB_STEP_SUMMARY
+          if [[ "${{ steps.targets.outputs.preview-branch }}" != "" ]]; then
+            echo "| \`${{ steps.targets.outputs.preview-branch }}\` | \`${{ github.base_ref }}\` |" >> $GITHUB_STEP_SUMMARY
+          fi
+          if [[ "${{ steps.check-develop.outputs.exists }}" == "true" ]]; then
+            echo "| \`${{ steps.targets.outputs.develop-branch }}\` | \`${{ steps.targets.outputs.merge-source }}\` |" >> $GITHUB_STEP_SUMMARY
+          fi

.github/workflows/publish-documentation.yml

@@ -139,7 +139,7 @@ jobs:
           {
             echo "### YamlMime:TableOfContent"
             echo "- name: Guide"
-            echo "  href: ${latest}/guide/introduction.html"
+            echo "  href: ${latest}/guide/getting-started.html"
             echo "- name: API Reference"
             echo "  href: ${latest}/PolylineAlgorithm.html"
           } > api-reference/toc.yml
@@ -159,7 +159,7 @@ jobs:
               else
                 label="v${ver}"
               fi
-              echo "| ${label} | [Guide](${ver}/guide/introduction.html) | [API Reference](${ver}/PolylineAlgorithm.html) |"
+              echo "| ${label} | [Guide](${ver}/guide/getting-started.html) | [API Reference](${ver}/PolylineAlgorithm.html) |"
             done
           } > /tmp/versions_section.md
           awk '/{versions_section}/{while((getline line < "/tmp/versions_section.md") > 0) print line; close("/tmp/versions_section.md"); next} {print}' \

api-reference/docs-versioning/public/version-switcher.js

@@ -13,7 +13,7 @@
 
   function getSiteRoot() {
     var meta = document.querySelector('meta[name="docfx:rel"]');
-    return meta ? meta.getAttribute('content') : './';
+    return meta ? (meta.getAttribute('content') || './') : './';
   }
 
   var VERSION_PATTERN = /\/\d+(\.\d+)*\//;
@@ -83,7 +83,7 @@
         );
       } else {
         var siteRootPath = new URL(getSiteRoot(), window.location.href).pathname.replace(/\/$/, '');
-        newPathname = siteRootPath + '/' + targetVersion + '/PolylineAlgorithm.html';
+        newPathname = siteRootPath + '/' + targetVersion + '/guide/getting-started.html';
       }
 
       window.location.pathname = newPathname;

api-reference/guide/toc.yml

@@ -1,6 +1,4 @@
-- name: Introduction
-  href: introduction.md
-- name: Getting Started
+- name: Getting Started
   href: getting-started.md
 - name: Configuration
   href: configuration.md

api-reference/index.md

@@ -1,20 +1,33 @@
-# PolylineAlgorithm API Reference
+# PolylineAlgorithm for .NET
 
-Welcome! This documentation provides guides, configuration options, examples, and FAQs for the PolylineAlgorithm library.  
-For detailed class and method docs, see the versioned [API Reference]({version}/PolylineAlgorithm.html).
+Welcome to **PolylineAlgorithm for .NET**, a modern library for Google-compliant polyline encoding and decoding with strong input validation, extensible API design, and robust performance.
 
-## Contents
+## What is PolylineAlgorithm?
 
-- [Introduction]({version}/guide/introduction.html)
-- [Getting Started]({version}/guide/getting-started.html)
-- [Configuration Options]({version}/guide/configuration.html)
-- [Advanced Scenarios]({version}/guide/advanced-scenarios.html)
-- [Samples]({version}/guide/sample.html)
-- [FAQ]({version}/guide/faq.html)
+PolylineAlgorithm provides tools for encoding a sequence of geographic coordinates into a compact string format used by Google Maps and other mapping platforms, and for decoding those strings back into coordinates. Its simple API and thorough documentation make it suitable for .NET Core, .NET 5+, and any framework supporting `netstandard2.1`.
+
+## Key Benefits
+
+- **Standards compliance**: Implements Google's Encoded Polyline Algorithm as specified
+- **Immutable, strongly-typed objects**: Guarantees reliability and thread safety
+- **Extensible**: Custom coordinate/polyline support via abstract base classes and interfaces
+- **Robust input validation**: Throws descriptive exceptions for out-of-range or malformed input
+- **Configuration and logging**: Advanced options and integration with `ILoggerFactory`
+- **Benchmarked and tested**: Includes unit and performance tests
+
+## Getting Started
+
+Install via the .NET CLI:
+
+```shell
+dotnet add package PolylineAlgorithm
+```
+
+Then explore the versioned guide and API reference below to learn more.
 
 {versions_section}
 
 ## Links
 
-- [API Reference]({version}/PolylineAlgorithm.html)
 - [Contributing Guidelines](https://github.com/petesramek/polyline-algorithm-csharp/blob/main/CONTRIBUTING.md)
+- [Report an Issue](https://github.com/petesramek/polyline-algorithm-csharp/issues)