Merge branch 'develop/1.0' into bugfix/incorrect-normalization

Author: petesramek

.editorconfig

@@ -274,3 +274,6 @@ dotnet_naming_style.underscore_camel_case.capitalization = camel_case
 # Public API analyzer
 
 dotnet_public_api_analyzer.require_api_files = true
+
+# RS0017: Symbol removed from public API - error severity (IDE guidance; build enforcement via WarningsAsErrors in .csproj)
+dotnet_diagnostic.RS0017.severity = error

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

@@ -12,7 +12,7 @@ inputs:
   file-version:
     description: 'Assembly file version.'
     required: true
-  treat-warnins-as-error:
+  treat-warnings-as-error:
     description: 'Treat warnings as errors.'
     required: true
   project-path:

.github/workflows/build.yml

@@ -130,7 +130,7 @@ jobs:
           assembly-version: ${{ env.assembly-version }}
           assembly-informational-version: ${{ env.assembly-informational-version }}
           file-version: ${{ env.file-version }}
-          treat-warnins-as-error: ${{ needs.workflow-variables.outputs.is-release }}
+          treat-warnings-as-error: ${{ needs.workflow-variables.outputs.is-release }}
 
   test:
     name: 'Run tests'

.github/workflows/pull-request.yml

@@ -120,7 +120,7 @@ jobs:
           assembly-version: ${{ env.assembly-version }}
           assembly-informational-version: ${{ env.assembly-informational-version }}
           file-version: ${{ env.file-version }}
-          treat-warnins-as-error: ${{ needs.workflow-variables.outputs.is-release }}
+          treat-warnings-as-error: ${{ needs.workflow-variables.outputs.is-release }}
 
   test:
     name: 'Run tests'

.github/workflows/release.yml

@@ -129,7 +129,7 @@ jobs:
           assembly-version: ${{ env.assembly-version }}
           assembly-informational-version: ${{ env.assembly-informational-version }}
           file-version: ${{ env.file-version }}
-          treat-warnins-as-error: ${{ needs.workflow-variables.outputs.is-release }}
+          treat-warnings-as-error: ${{ needs.workflow-variables.outputs.is-release }}
 
   test:
     name: 'Run tests'
@@ -169,6 +169,89 @@ jobs:
       - name: Write code coverage report summary
         run: cat ${{ steps.code-coverage-report.outputs.code-coverage-report-file }} >> $GITHUB_STEP_SUMMARY
 
+  update-api-unshipped:
+    name: 'Update PublicAPI.Unshipped.txt'
+    needs: [workflow-variables, validate-release]
+    # Run even when build fails — the build may fail solely because a dropped preview API is still
+    # listed in Unshipped.txt (RS0017). This job fixes exactly that, so it must not be gated on build.
+    if: ${{ needs.workflow-variables.outputs.is-preview == 'true' && needs.validate-release.result == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout ${{ github.ref }}'
+        uses: actions/checkout@v6
+
+      - name: 'Setup .NET'
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: ${{ env.dotnet-sdk-version }}
+
+      - name: 'Snapshot PublicAPI.Shipped.txt'
+        shell: bash
+        run: cp src/PolylineAlgorithm/PublicAPI.Shipped.txt src/PolylineAlgorithm/PublicAPI.Shipped.txt.bak
+
+      - name: 'Sync PublicAPI.Unshipped.txt (add new + remove dropped preview APIs)'
+        shell: bash
+        run: dotnet format analyzers src/PolylineAlgorithm/PolylineAlgorithm.csproj --diagnostics RS0016 RS0017
+
+      - name: 'Guard against accidental shipped API removal'
+        shell: bash
+        run: |
+          SHIPPED="src/PolylineAlgorithm/PublicAPI.Shipped.txt"
+          if ! diff -q "$SHIPPED" "$SHIPPED.bak" > /dev/null 2>&1; then
+            echo "::error::Breaking change detected — a shipped API was removed from PublicAPI.Shipped.txt."
+            echo "::error::This requires a major version bump. Reverting the unintended change."
+            cp "$SHIPPED.bak" "$SHIPPED"
+            exit 1
+          fi
+          rm -f "$SHIPPED.bak"
+
+      - name: 'Configure git identity'
+        uses: './.github/actions/git/configure-identity'
+
+      - name: 'Commit and push updated API files'
+        shell: bash
+        run: |
+          git add src/PolylineAlgorithm/PublicAPI.Unshipped.txt
+          git diff --staged --quiet || (
+            git commit -m "Sync PublicAPI.Unshipped.txt (add new, remove dropped preview APIs)" &&
+            git pull --rebase origin ${{ github.ref_name }} &&
+            git push
+          )
+
+  promote-api-files:
+    name: 'Promote PublicAPI files (Unshipped -> Shipped)'
+    needs: [workflow-variables, test, validate-release]
+    if: ${{ needs.workflow-variables.outputs.is-release == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout ${{ github.ref }}'
+        uses: actions/checkout@v6
+
+      - name: 'Promote Unshipped.txt into Shipped.txt'
+        shell: bash
+        run: |
+          UNSHIPPED="src/PolylineAlgorithm/PublicAPI.Unshipped.txt"
+          SHIPPED="src/PolylineAlgorithm/PublicAPI.Shipped.txt"
+
+          # Append every non-blank, non-header line from Unshipped into Shipped
+          tail -n +2 "$UNSHIPPED" | grep -v '^[[:space:]]*$' >> "$SHIPPED" || true
+
+          # Reset Unshipped to just the nullable-enable header (with BOM to match convention)
+          printf '\xef\xbb\xbf#nullable enable\n' > "$UNSHIPPED"
+
+      - name: 'Configure git identity'
+        uses: './.github/actions/git/configure-identity'
+
+      - name: 'Commit and push promoted API files'
+        shell: bash
+        run: |
+          git add src/PolylineAlgorithm/PublicAPI.Shipped.txt src/PolylineAlgorithm/PublicAPI.Unshipped.txt
+          git diff --staged --quiet || (
+            git commit -m "Promote PublicAPI.Unshipped.txt into PublicAPI.Shipped.txt for release" &&
+            git pull --rebase origin ${{ github.ref_name }} &&
+            git push
+          )
+
   pack:
     name: 'Package binaries'
     needs: [versioning, build, test, validate-release]
@@ -219,8 +302,14 @@ jobs:
 
   publish-package:
     name: 'Publish package'
-    needs: [pack, validate-release, publish-documentation]
-    if: ${{ always() && needs.pack.result == 'success' && needs.validate-release.result == 'success' && (needs.publish-documentation.result == 'success' || needs.publish-documentation.result == 'skipped') }}
+    needs: [pack, validate-release, publish-documentation, update-api-unshipped, promote-api-files]
+    if: |
+      always() &&
+      needs.pack.result == 'success' &&
+      needs.validate-release.result == 'success' &&
+      (needs.publish-documentation.result == 'success' || needs.publish-documentation.result == 'skipped') &&
+      (needs.promote-api-files.result == 'success' || needs.promote-api-files.result == 'skipped') &&
+      (needs.update-api-unshipped.result == 'success' || needs.update-api-unshipped.result == 'skipped')
     env:
       package-artifact-name: ${{ needs.pack.outputs.package-artifact-name }}
     runs-on: ubuntu-latest
@@ -277,6 +366,9 @@ jobs:
     needs: [workflow-variables, release, versioning]
     if: ${{ needs.workflow-variables.outputs.is-release == 'true' }}
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
     env:
       GH_TOKEN: ${{ github.token }}
       current-branch: ${{ github.ref_name }}
@@ -368,17 +460,10 @@ jobs:
           git checkout -b "${{ steps.resolve-support-branch.outputs.support-branch }}"
           git push --set-upstream origin "${{ steps.resolve-support-branch.outputs.support-branch }}"
 
-      - name: 'Lock support branch'
-        if: ${{ steps.check-support-branch.outputs.support-branch-exists == 'false' }}
-        uses: './.github/actions/github/branch-protection/lock'
-        with:
-          branch: ${{ steps.resolve-support-branch.outputs.support-branch }}
-          token: ${{ secrets.GH_ADMIN_TOKEN }}
-
       - name: 'Write support branch summary'
         run: |
           if [[ "${{ steps.check-support-branch.outputs.support-branch-exists }}" == "false" ]]; then
-            echo "✅ Created and locked support branch **${{ steps.resolve-support-branch.outputs.support-branch }}**." >> $GITHUB_STEP_SUMMARY
+            echo "✅ Created support branch **${{ steps.resolve-support-branch.outputs.support-branch }}**." >> $GITHUB_STEP_SUMMARY
           else
             echo "⏭️ Support branch **${{ steps.resolve-support-branch.outputs.support-branch }}** already exists." >> $GITHUB_STEP_SUMMARY
           fi

PolylineAlgorithm.slnx

@@ -7,6 +7,7 @@
   </Folder>
   <Folder Name="/samples/">
     <Project Path="samples/PolylineAlgorithm.NetTopologySuite.Sample/PolylineAlgorithm.NetTopologySuite.Sample.csproj" Id="27a8fc47-0a3c-49c7-af5e-530514827785" />
+    <Project Path="samples/PolylineAlgorithm.SensorData.Sample/PolylineAlgorithm.SensorData.Sample.csproj" />
   </Folder>
   <Folder Name="/src/">
     <Project Path="src/PolylineAlgorithm/PolylineAlgorithm.csproj" />

README.md

@@ -1,6 +1,10 @@
 # PolylineAlgorithm for .NET
 
-Lightweight .NET Standard 2.1 library implementing Google-compliant Encoded Polyline Algorithm with strong input validation, modern API patterns, and extensibility for custom coordinate types.
+[![NuGet](https://img.shields.io/nuget/v/PolylineAlgorithm)](https://www.nuget.org/packages/PolylineAlgorithm)
+[![Build](https://github.com/petesramek/polyline-algorithm-csharp/actions/workflows/build.yml/badge.svg)](https://github.com/petesramek/polyline-algorithm-csharp/actions/workflows/build.yml)
+[![License: MIT](https://img.shields.io/github/license/petesramek/polyline-algorithm-csharp)](./LICENSE)
+
+Google's Encoded Polyline Algorithm compresses sequences of geographic coordinates into a compact ASCII string, widely used in mapping APIs. This library provides a fully compliant .NET implementation with extensible, type-safe encoding and decoding APIs.
 
 ## Table of Contents
 
@@ -17,15 +21,16 @@ Lightweight .NET Standard 2.1 library implementing Google-compliant Encoded Poly
 ## Features
 
 - Fully compliant Google Encoded Polyline Algorithm for .NET Standard 2.1+
-- Extensible encoding and decoding APIs for custom coordinate and polyline types (`IPolylineEncoder<TCoordinate, TPolyline>`, `IPolylineDecoder<TPolyline, TCoordinate>`, `AbstractPolylineEncoder<TCoordinate, TPolyline>`, `AbstractPolylineDecoder<TPolyline, TCoordinate>`)
-- Extension methods for encoding from `List<T>` and arrays (`PolylineEncoderExtensions`)
-- Robust input validation with descriptive exceptions for malformed/invalid data
+- Extensible APIs — implement your own encoder/decoder for any coordinate or polyline type
+- Robust input validation with descriptive exceptions for malformed or out-of-range data
 - Advanced configuration via `PolylineEncodingOptions` (precision, buffer size, logging)
-- Logging and diagnostic support for CI/CD and developer diagnostics via `Microsoft.Extensions.Logging`
-- Low-level utilities for normalization, validation, encoding and decoding via static `PolylineEncoding` class
+- Extension methods for encoding directly from `List<T>` and arrays
+- Logging and diagnostic support via `Microsoft.Extensions.Logging`
+- Low-level utilities for normalization, validation, and bit-level operations via static `PolylineEncoding` class
+- Thread-safe, stateless APIs
 - Thorough unit tests and benchmarks for correctness and performance
 - Auto-generated API documentation ([API Reference](https://petesramek.github.io/polyline-algorithm-csharp/))
-- Support for .NET Core, .NET 5+, Xamarin, Unity, Blazor, and other platforms supporting `netstandard2.1`
+- Supports .NET Core, .NET 5+, Xamarin, Unity, Blazor, and any platform targeting `netstandard2.1`
 
 ## Installation
 
@@ -43,7 +48,19 @@ Install-Package PolylineAlgorithm
 
 ## Usage
 
-The library provides abstract base classes to implement your own encoder and decoder for any coordinate and polyline type.
+The library provides abstract base classes to implement your own encoder and decoder for any coordinate and polyline type. Inherit from `AbstractPolylineEncoder` or `AbstractPolylineDecoder`, override the coordinate accessors, then call `Encode` or `Decode`.
+
+### Quick Start
+
+```csharp
+// 1. Implement a minimal encoder (see full example below)
+var encoder = new MyPolylineEncoder();
+string encoded = encoder.Encode(coordinates);    // e.g. "yseiHoc_MwacOjnwM"
+
+// 2. Implement a minimal decoder (see full example below)
+var decoder = new MyPolylineDecoder();
+IEnumerable<(double Latitude, double Longitude)> decoded = decoder.Decode(encoded);
+```
 
 ### Custom encoder and decoder
 
@@ -56,23 +73,9 @@ using PolylineAlgorithm;
 using PolylineAlgorithm.Abstraction;
 
 public sealed class MyPolylineEncoder : AbstractPolylineEncoder<(double Latitude, double Longitude), string> {
-    public MyPolylineEncoder()
-        : base() { }
-
-    public MyPolylineEncoder(PolylineEncodingOptions options)
-        : base(options) { }
-
-    protected override double GetLatitude((double Latitude, double Longitude) coordinate) {
-        return coordinate.Latitude;
-    }
-
-    protected override double GetLongitude((double Latitude, double Longitude) coordinate) {
-        return coordinate.Longitude;
-    }
-
-    protected override string CreatePolyline(ReadOnlyMemory<char> polyline) {
-        return polyline.ToString();
-    }
+    protected override double GetLatitude((double Latitude, double Longitude) coordinate) => coordinate.Latitude;
+    protected override double GetLongitude((double Latitude, double Longitude) coordinate) => coordinate.Longitude;
+    protected override string CreatePolyline(ReadOnlyMemory<char> polyline) => polyline.ToString();
 }
 ```
 
@@ -102,19 +105,8 @@ using PolylineAlgorithm;
 using PolylineAlgorithm.Abstraction;
 
 public sealed class MyPolylineDecoder : AbstractPolylineDecoder<string, (double Latitude, double Longitude)> {
-    public MyPolylineDecoder()
-        : base() { }
-
-    public MyPolylineDecoder(PolylineEncodingOptions options)
-        : base(options) { }
-
-    protected override (double Latitude, double Longitude) CreateCoordinate(double latitude, double longitude) {
-        return (latitude, longitude);
-    }
-
-    protected override ReadOnlyMemory<char> GetReadOnlyMemory(in string polyline) {
-        return polyline.AsMemory();
-    }
+    protected override (double Latitude, double Longitude) CreateCoordinate(double latitude, double longitude) => (latitude, longitude);
+    protected override ReadOnlyMemory<char> GetReadOnlyMemory(in string polyline) => polyline.AsMemory();
 }
 ```
 
@@ -136,8 +128,13 @@ Full API docs and guides (auto-generated from source) are available at [API Refe
 
 ## Benchmarks
 
-- See `/benchmarks` in the repo for performance evaluation.
-- Contributors: Update benchmarks and document results for performance-impacting PRs.
+- See [`/benchmarks`](./benchmarks) in the repo for benchmark projects.
+- Run benchmarks with:
+  ```shell
+  dotnet run --project benchmarks/PolylineAlgorithm.Benchmarks --configuration Release
+  ```
+- For guidance on writing and interpreting benchmarks, see [docs/benchmarks.md](./docs/benchmarks.md).
+- Contributors: update benchmarks and document results for performance-impacting PRs.
 
 ## FAQ
 
@@ -173,13 +170,13 @@ A: Currently, only batch encode/decode is supported. For streaming scenarios, im
 
 ## Contributing
 
-- Follow code style and PR instructions in [AGENTS.md](./AGENTS.md).
+- Follow code style and PR instructions in [CONTRIBUTING.md](./CONTRIBUTING.md).
 - Ensure all features are covered by tests and XML doc comments.
 - For questions or suggestions, open an issue and use the provided templates.
 
 ## Support
 
-Have a question, bug, or feature request? [Open an issue!](https://github.com/petesramek/polyline-algorithm-csharp/issues)
+Have a question, bug, or feature request? [Open an issue](https://github.com/petesramek/polyline-algorithm-csharp/issues/new/choose) — bug report and feature request templates are available to guide you.
 
 ---
 

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineDecoder.cs

@@ -12,7 +12,7 @@ namespace PolylineAlgorithm.NetTopologySuite.Sample;
 /// <summary>
 /// Polyline decoder using NetTopologySuite.
 /// </summary>
-public sealed class NetTopologyPolylineDecoder : AbstractPolylineDecoder<string, Point> {
+internal sealed class NetTopologyPolylineDecoder : AbstractPolylineDecoder<string, Point> {
     /// <summary>
     /// Creates a NetTopologySuite point from latitude and longitude.
     /// </summary>

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs

@@ -11,7 +11,7 @@ namespace PolylineAlgorithm.NetTopologySuite.Sample;
 /// <summary>
 /// Polyline encoder using NetTopologySuite's Point type.
 /// </summary>
-public sealed class NetTopologyPolylineEncoder : AbstractPolylineEncoder<Point, string> {
+internal sealed class NetTopologyPolylineEncoder : AbstractPolylineEncoder<Point, string> {
     /// <summary>
     /// Creates encoded polyline string from memory.
     /// </summary>
@@ -31,9 +31,7 @@ protected override string CreatePolyline(ReadOnlyMemory<char> polyline) {
     /// <param name="current">Point instance.</param>
     /// <returns>Latitude value.</returns>
     protected override double GetLatitude(Point current) {
-        if (current is null) {
-            throw new ArgumentNullException(nameof(current));
-        }
+        ArgumentNullException.ThrowIfNull(current);
 
         // NetTopologySuite Point: Y = latitude
         return current.Y;
@@ -45,9 +43,7 @@ protected override double GetLatitude(Point current) {
     /// <param name="current">Point instance.</param>
     /// <returns>Longitude value.</returns>
     protected override double GetLongitude(Point current) {
-        if (current is null) {
-            throw new ArgumentNullException(nameof(current));
-        }
+        ArgumentNullException.ThrowIfNull(current);
 
         // NetTopologySuite Point: X = longitude
         return current.X;

samples/PolylineAlgorithm.NetTopologySuite.Sample/PolylineAlgorithm.NetTopologySuite.Sample.csproj

@@ -1,7 +1,8 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
 	<PropertyGroup>
-		<TargetFramework>netstandard2.1</TargetFramework>
+		<OutputType>Exe</OutputType>
+		<TargetFramework>net10.0</TargetFramework>
 	</PropertyGroup>
 
 	<PropertyGroup>