Complete rewrite and v1.0 release preparation (#146)

## Complete rewrite and v1.0 release preparation

This PR represents a full rewrite of the PolylineAlgorithm library,
modernizing the API surface, improving extensibility, and preparing for
a stable v1.0 release targeting .NET Standard 2.1+.

---

### Breaking Changes / New Public API

- **New generic interfaces** `IPolylineEncoder<TCoordinate, TPolyline>`
and `IPolylineDecoder<TPolyline, TCoordinate>` replace the old encoding
abstraction, allowing callers to use any coordinate and polyline
representation.
- **Abstract base classes** `AbstractPolylineEncoder<TCoordinate,
TPolyline>` and `AbstractPolylineDecoder<TPolyline, TCoordinate>`
provide the shared encoding/decoding algorithm; consumers override only
`GetLatitude`, `GetLongitude`, `CreatePolyline` (encoder) or
`CreateCoordinate`, `GetReadOnlyMemory` (decoder).
- **Extension methods** `PolylineEncoderExtensions` and
`PolylineDecoderExtensions` add convenience overloads for `List<T>` and
arrays.
- **`PolylineEncoding`** static utility class exposes low-level
normalization, validation, encoding and decoding primitives.
- **`PolylineEncodingOptions`** and **`PolylineEncodingOptionsBuilder`**
expose configurable precision, stack-alloc buffer limit and
`ILoggerFactory` integration.
- **`InvalidPolylineException`** added for descriptive error reporting
on malformed input.
- All `Encode`/`Decode` methods accept an optional `CancellationToken`.

### Other Changes

- Integrated `Microsoft.Extensions.Logging` support for diagnostics / CI
audit trails.
- Added `PolylineAlgorithm.NetTopologySuite.Sample` demonstrating
integration with NetTopologySuite.
- Comprehensive XML doc comments on all public APIs.
- Updated README, CONTRIBUTING, AGENTS and all guide docs under
`api-reference/guide/` (getting-started, advanced-scenarios,
configuration, FAQ).
- DocFX API reference updated for v1.0 under `api-reference/1.0/`.
- Updated unit tests and benchmarks.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 6 people

.editorconfig

@@ -131,7 +131,7 @@ csharp_prefer_simple_using_statement = false
 csharp_prefer_system_threading_lock = true
 csharp_style_namespace_declarations = file_scoped
 csharp_style_prefer_method_group_conversion = false
-csharp_style_prefer_primary_constructors = true
+csharp_style_prefer_primary_constructors = false
 csharp_style_prefer_top_level_statements = false
 
 # Expression-level preferences
@@ -270,3 +270,7 @@ dotnet_naming_style.underscore_camel_case.required_prefix = _
 dotnet_naming_style.underscore_camel_case.required_suffix = 
 dotnet_naming_style.underscore_camel_case.word_separator = 
 dotnet_naming_style.underscore_camel_case.capitalization = camel_case
+
+# Public API analyzer
+
+dotnet_public_api_analyzer.require_api_files = true

.github/actions/documentation/docfx-build/action.yml

@@ -21,12 +21,10 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: 'Checkout ${{ github.head_ref || github.ref }}'
-      uses: actions/checkout@v5
     - name: Dotnet Setup
       uses: actions/setup-dotnet@v4
       with:
-        dotnet-version: ${{ env.dotnet-sdk-version }}
+        dotnet-version: ${{ inputs.dotnet_sdk_version }}
     - name: 'testing variables'
       shell: bash
       run: |
@@ -41,7 +39,7 @@ runs:
       run: docfx build ${{ inputs.docfx-json-manifest }}
       shell: bash
     - name: Upload artifact
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: ${{ inputs.artifact-name }}
         path: ${{ inputs.output-directory }}

.github/actions/documentation/docfx-metadata/action.yml

@@ -26,7 +26,7 @@ runs:
   using: composite
   steps:
     - name: 'Checkout ${{ github.head_ref || github.ref }}'
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
     - name: Dotnet Setup
       uses: actions/setup-dotnet@v4
       with:
@@ -59,7 +59,7 @@ runs:
         mkdir -p ${{ inputs.output-directory }}
         cp -r ${{ inputs.temporary-directory }}/* ${{ inputs.output-directory }}
     - name: 'Upload artifact'
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
          name: ${{ inputs.artifact-name }}
          path: ${{ inputs.output-directory }}

.github/actions/git/push-changes/action.yml

@@ -28,7 +28,7 @@ runs:
   using: "composite"
   steps:
     - name: 'Checkout ${{ github.head_ref || github.ref }}'
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: Dotnet Setup
       uses: actions/setup-dotnet@v4
@@ -37,7 +37,7 @@ runs:
 
     - name: Download a single artifact
       if: ${{ inputs.artifact-name != '' }}
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v8
       with:
         name: ${{ inputs.artifact-name }}
         path: ${{ inputs.working-directory }}

.github/actions/github/branch-protection/lock/action.yml

@@ -0,0 +1,37 @@
+name: 'Lock branch'
+author: 'Pete Sramek'
+description: 'Apply branch protection to prevent direct pushes. Requires PRs with at least one approval.'
+inputs:
+  branch:
+    description: 'Branch name to lock.'
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: 'Lock branch ${{ inputs.branch }}'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        if ! gh api --method PUT /repos/${{ github.repository }}/branches/${{ inputs.branch }}/protection \
+          --input - << 'EOF'
+        {
+          "required_status_checks": null,
+          "enforce_admins": false,
+          "required_pull_request_reviews": {
+            "dismiss_stale_reviews": true,
+            "require_code_owner_reviews": false,
+            "required_approving_review_count": 1
+          },
+          "restrictions": null,
+          "allow_force_pushes": false,
+          "allow_deletions": false,
+          "lock_branch": false
+        }
+        EOF
+        then
+          echo "::error::Failed to apply branch protection to '${{ inputs.branch }}'. Ensure the token has 'administration: write' permission and the branch exists."
+          exit 1
+        fi
+        echo "🔒 Branch '${{ inputs.branch }}' is now protected." >> $GITHUB_STEP_SUMMARY

.github/actions/github/branch-protection/unlock/action.yml

@@ -0,0 +1,18 @@
+name: 'Unlock branch'
+author: 'Pete Sramek'
+description: 'Remove branch protection to allow a workflow to push directly. Always re-lock after the operation.'
+inputs:
+  branch:
+    description: 'Branch name to unlock.'
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: 'Unlock branch ${{ inputs.branch }}'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        gh api --method DELETE /repos/${{ github.repository }}/branches/${{ inputs.branch }}/protection || true
+        echo "🔓 Branch protection removed from '${{ inputs.branch }}'." >> $GITHUB_STEP_SUMMARY

.github/actions/github/create-release/action.yml

@@ -1,4 +1,4 @@
-name: 'Create GitHub release'
+name: 'Create GitHub release'
 author: 'Pete Sramek'
 description: 'Create GitHub release.'
 inputs:
@@ -17,14 +17,18 @@ runs:
   using: composite
   steps:
     - name: 'Checkout ${{ github.head_ref || github.ref }}'
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
     - run: |
         echo "release-version=${{ inputs.release-version }}"
         echo "is-preview=${{ inputs.is-preview }}"
         echo "preview-argument=${{ inputs.is-preview == 'true' && '--prerelease' || '' }}"
         echo "notes-start-tag=${{ inputs.notes-start-tag }}"
         echo "notes-start-tag-argument="${{ inputs.notes-start-tag != '' && '--notes-start-tag $(inputs.notes-start-tag)' || '' }}"
       shell: bash
+    - name: 'Create git tag ${{ env.release-version }}'
+      shell: bash
+      run: |
+        git tag -a ${{ env.release-version }} -m "${{ env.release-version }}"
     - name: 'Create GitHub release PolylineAlgorithm ${{ env.release-version }}'
       shell: bash
       env:

.github/actions/github/write-file-to-summary/action.yml

@@ -1,4 +1,4 @@
-name: 'Write file to step summary'
+name: 'Write file to step summary'
 author: 'Pete Sramek'
 description: 'Writes file contents to step summary.'
 inputs:
@@ -17,7 +17,7 @@ runs:
   using: composite
   steps:
     - name: 'Checkout ${{ github.head_ref || github.ref }}'
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: Writing ${{ inputs.file }} to step summary
       shell: bash

.github/actions/nuget/publish-package/action.yml

@@ -38,10 +38,10 @@ runs:
           exit 1
 
     - name: 'Checkout ${{ github.head_ref || github.ref }}'
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: Download package artifact
-      uses: actions/download-artifact@v5
+      uses: actions/download-artifact@v8
       with:
         name: ${{ inputs.package-artifact-name }}
 

.github/actions/source/compile/action.yml

@@ -50,7 +50,7 @@ runs:
   using: "composite"
   steps:
     - name: 'Checkout ${{ github.head_ref || github.ref }}'
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: 'Setup .NET ${{ inputs.dotnet_sdk_version }}'
       uses: actions/setup-dotnet@v4
@@ -68,7 +68,7 @@ runs:
 
     - name: 'Upload build artifacts'
       if: ${{ inputs.upload-build-artifacts == 'true' }}
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: ${{ inputs.build-artifacts-name }}
         path: ${{ inputs.build-artifacts-glob-pattern }}