Skip to content

Merge release/1.0 into main - #310

Merged
petesramek merged 27 commits into
mainfrom
release/1.0
Oct 29, 2026
Merged

petesramek merged 27 commits into
mainfrom
release/1.0

Conversation

@github-actions

Copy link
Copy Markdown
Contributor

github-actions Bot and others added 27 commits April 4, 2026 09:43
)

## Overview

Promotes `preview/1.0` to `release/1.0` in preparation for the 1.0
release. This batch brings in a full rewrite of the library's core,
docs, CI/CD pipeline, and test suite accumulated since the last preview
snapshot.

## What's included

### 🏗️ CI/CD & Workflows
- **New workflows**: `bump-version`, `promote-branch` with source-branch
enforcement, auto merge-to-main on release
- **Branch protection**: new `lock`/`unlock` composite actions;
`preview/**` and `release/**` branches are now automatically locked
after creation
- **Fix**: removed invalid `administration` permission from
`release.yml` that caused workflow parse failures (#158)
- **Fix**: corrected pull-request-finding logic in promote workflow
- **Docs publishing**: URL-aware version switcher via `docs-versioning`
template; `versions.json` manifest; reworked `generate-docs` job (#157)

### 📚 Documentation
- New `/docs` developer guides: local development, testing conventions,
benchmarks, composite actions catalogue, CI workflow reference, branch
strategy, versioning pipeline, API doc generation, extensibility guide
(#155)
- Updated API reference YAMLs for version 1.0
- Fixed grammar, TOC typo, and outdated API references in docs
- Updated `CONTRIBUTING.md` with links to all new docs articles
- Flushed `PublicAPI.Unshipped.txt`

### 🔧 Source (library)
- Refactored internal structure: `CoordinateDelta`,
`CoordinateVariance`, `Pow10`, `Defaults`, `ExceptionGuard`, logging
helpers
- Updated `PolylineEncoder`, `PolylineDecoder`, `PolylineEncoding`,
`PolylineEncodingOptions`, `PolylineEncodingOptionsBuilder`
- Public API cleanup; `.editorconfig` updated (primary constructors
disabled)

### ✅ Tests
- Reorganized test files into proper namespace folders (`Abstraction/`,
`Extensions/`, `Internal/`)
- Added new test classes for `CoordinateDelta`, `CoordinateVariance`,
`Pow10`, `ExceptionGuard`, `LogDebugExtensions`, `LogWarningExtensions`,
`InvalidPolylineException`, `PolylineEncodingOptionsBuilder`, and
encoder/decoder extensions
- Removed stale/duplicate test files

### 🛠️ Build & Config
- Cleaned up `PolylineAlgorithm.slnx`, `Directory.Build.props`,
benchmarks config
- Updated `.gitignore` to exclude dynamically generated
`api-reference/_docs/`
- Misc cleanup (removed junk files, updated `AGENTS.md`)
…add released versions table (#176)

## Summary

Previously, versioned folders contained only API reference YAMLs while
guide pages were global (unversioned). The root `index.md` had entirely
broken links. The version switcher navigated to a bare `/{ver}/` folder
that has no `index.html`, causing 404s on GitHub Pages.

## Changes

### Workflow (`publish-documentation.yml`)
- **Guide snapshot**: copies `api-reference/guide/` into
`api-reference/{ver}/guide/` immediately after API metadata generation,
so each version folder contains a full snapshot of both guide and API
reference
- **DocFX version groups**: each group now registers two content entries
— API YAMLs (`*.yml`) and guide pages (`guide/*.{md,yml}`) — producing
`_docs/{ver}/` and `_docs/{ver}/guide/` in the build output
- **Global TOC**: `Guide` nav link now points to
`{latest}/guide/introduction.html` instead of the unversioned `guide/`
- **index.md injection**: a single step builds the released versions
table and substitutes both `{version}` and `{versions_section}`
placeholders before `docfx build` runs (no committed artefacts)

### `api-reference/api-reference.json`
- Removed `guide/*.{md,yml}` from the global content entry — guide pages
now exist only within versioned groups

### `api-reference/index.md`
- Replaced broken links with `{version}`-placeholder paths resolved at
build time
- Added a `{versions_section}` placeholder that the workflow expands
into a full released-versions table

### `docs-versioning/public/version-switcher.js`
- Fixed the fallback navigation branch to resolve the site root via the
`docfx:rel` meta tag and navigate to `/{ver}/PolylineAlgorithm.html`
instead of the bare `/{ver}/` folder
…#183)

Version switcher on the global index page produced broken URLs like
`.../index.html/1.0/PolylineAlgorithm.html`, and even when corrected
would land users on the raw API reference — a poor first-visit
experience. Introduction was also redundant as a separate guide entry.

## Changes

### `version-switcher.js`
- **URL fix**: `getSiteRoot()` treated an empty `docfx:rel` meta
attribute as a valid relative URL, causing `new URL('',
'.../index.html')` to resolve to the full page path including the
filename. Now falls back to `'./'` when the attribute is empty.
- **Better redirect from index**: Selecting a version on the global
index now navigates to `{version}/guide/getting-started.html` instead of
`{version}/PolylineAlgorithm.html`.

```js
// Before
return meta ? meta.getAttribute('content') : './';
// After — empty string is falsy, so we fall back to './'
return meta ? (meta.getAttribute('content') || './') : './';
```

### `api-reference/guide/toc.yml`
- Removed the **Introduction** entry; **Getting Started** is now the
first and default page in the versioned guide sidebar.

### `api-reference/index.md`
- Replaced the bare link list with a proper landing page: library
summary, key benefits, and a quick-start install snippet — content drawn
from `introduction.md`. The `{versions_section}` placeholder is
preserved for workflow injection.

### `publish-documentation.yml`
- Navbar `toc.yml` generation and the versions table both updated to
link to `getting-started.html` instead of the now-removed
`introduction.html`.
`gh pr create --fill` computes the PR body by running `git log
origin/<target>...HEAD`, but the shallow checkout (`fetch-depth: 1`)
only fetches the source branch. With `origin/<target>` absent from the
local repo, git fails with "ambiguous argument" and the job exits
non-zero.

## Changes

- **`.github/workflows/promote-branch.yml`** — add `git fetch origin ${{
env.target-branch }}` immediately before `gh pr create` in the "Create
PR" step, ensuring the remote tracking ref exists when `--fill` computes
the commit range.
`gh release create` requires the tag to exist on the remote — creating
it locally with `git tag` is not sufficient. The job was failing every
time with:

```
tag 1.0.69.11 exists locally but has not been pushed to petesramek/polyline-algorithm-csharp,
please push it before continuing or specify the `--target` flag to create a new tag
```

## Change

- **`.github/actions/github/create-release/action.yml`** — push the
annotated tag to `origin` immediately after creating it, before invoking
`gh release create`

```diff
     run: |
       git tag -a ${{ inputs.release-version }} -m "${{ inputs.release-version }}"
+      git push origin ${{ inputs.release-version }}
```
The `merge-to-main` job was failing because `GITHUB_TOKEN` lacked
`pull-requests: write`, causing `gh pr create` to be rejected with
`GraphQL: Resource not accessible by integration (createPullRequest)`.

## Change

- Added job-level `permissions` block to `merge-to-main` with
`pull-requests: write` and `contents: read`, scoped only to the job that
needs it rather than elevating the entire workflow.

```yaml
merge-to-main:
  ...
  permissions:
    pull-requests: write
    contents: read
```
Description

Automated branch promotion merging 2,184 commits from preview/1.0 into
release/1.0. This PR represents the culmination of all development and
preview changes and prepares them for official release.

Scope

Workflow & CI/CD Improvements
• Fixed release workflow bugs related to tag creation, git permissions,
and GitHub release generation
• Added branch locking mechanism to prevent race conditions during
automated back-merges
• Enhanced branch protection coordination across develop/1.0 →
preview/1.0 → release/1.0 promotion pipeline
•	Fixed shallow checkout issues in promote-branch workflow
• Corrected permission scoping for pull request creation in release
workflows

Documentation Enhancements
•	Improved API reference organization with versioned snapshots
•	Fixed broken navigation links in documentation landing pages
•	Implemented proper version switcher URL handling
•	Enhanced getting-started guide accessibility
•	Added released versions table for better version discovery

Code Quality & Performance
• Removed SIMD validation code in favor of optimized single-pass loop
implementation
•	Repository cleanup and maintenance

Bug Fixes
•	Fixed GitHub Actions composite action quoting bugs
•	Corrected environment variable references in release workflows
•	Resolved merge conflict handling across branch streams

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <me@petesramek.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.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: petesramek <2333452+petesramek@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This pull request introduces significant improvements to the automation
around managing branch protection during the release process, especially
when promoting API files. The main changes add the ability to safely
unlock and restore branch protection settings, ensure these settings are
preserved and restored accurately, and refactor the release workflow to
use these new capabilities. This makes the release process more robust
and secure by preventing accidental misconfiguration of branch
protection.

Key changes include:

**Branch Protection Management Enhancements:**

* The `unlock` action now captures and outputs the current branch
protection settings as compact JSON before removing protection, enabling
precise restoration later. It also robustly handles errors and outputs
the settings for downstream steps.
* The `lock` action accepts a `protection-settings` input, allowing it
to restore branch protection to its original state using the captured
JSON, rather than relying on static or default settings. This ensures
branch protection is restored exactly as it was.
[[1]](diffhunk://#diff-f4be0352990685ab834c04a82ec138995ffaf7e1c89f5855182800ef9a1ca12cR35-R38)
[[2]](diffhunk://#diff-f4be0352990685ab834c04a82ec138995ffaf7e1c89f5855182800ef9a1ca12cR47-R66)
[[3]](diffhunk://#diff-f4be0352990685ab834c04a82ec138995ffaf7e1c89f5855182800ef9a1ca12cR87-R89)

**Release Workflow Refactor:**

* In `.github/workflows/release.yml`, the promotion of API files now
uploads them as artifacts and uses the new unlock/lock actions to
temporarily remove and then restore branch protection, only if there are
changes to promote. This replaces the previous direct commit/push
approach and ensures compliance with branch protection rules.
* The workflow checks if there are changes before proceeding with
unlock, push, and restore steps, optimizing the process and avoiding
unnecessary actions.
[[1]](diffhunk://#diff-87db21a973eed4fef5f32b267aa60fcee5cbdf03c67fafdc2a9b553bb0b15f34L242-R281)
[[2]](diffhunk://#diff-87db21a973eed4fef5f32b267aa60fcee5cbdf03c67fafdc2a9b553bb0b15f34R231)

These changes collectively provide a safer and more reliable way to
handle protected branches during automated releases.

**References:**
-
[.github/actions/github/branch-protection/unlock/action.ymlR15-R83](diffhunk://#diff-53f2da988f53012cdcbae06ebfd3ab427c2f7c784a071b6e43c3aa8e789ad095R15-R83)
-
[.github/actions/github/branch-protection/lock/action.ymlR35-R38](diffhunk://#diff-f4be0352990685ab834c04a82ec138995ffaf7e1c89f5855182800ef9a1ca12cR35-R38)
-
[.github/actions/github/branch-protection/lock/action.ymlR47-R66](diffhunk://#diff-f4be0352990685ab834c04a82ec138995ffaf7e1c89f5855182800ef9a1ca12cR47-R66)
-
[.github/actions/github/branch-protection/lock/action.ymlR87-R89](diffhunk://#diff-f4be0352990685ab834c04a82ec138995ffaf7e1c89f5855182800ef9a1ca12cR87-R89)
-
[.github/workflows/release.ymlL242-R281](diffhunk://#diff-87db21a973eed4fef5f32b267aa60fcee5cbdf03c67fafdc2a9b553bb0b15f34L242-R281)
-
[.github/workflows/release.ymlR231](diffhunk://#diff-87db21a973eed4fef5f32b267aa60fcee5cbdf03c67fafdc2a9b553bb0b15f34R231)

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This pull request updates the branch protection GitHub Action to improve
how branch protection settings are processed before being applied. The
main change ensures that any `null` values within the
`required_pull_request_reviews` section of the protection settings are
filtered out, preventing invalid or unnecessary configuration from being
sent to the GitHub API.

**Branch protection settings processing:**

* Updated the assignment of the `payload` variable to filter out `null`
values from `required_pull_request_reviews` using `jq`, ensuring cleaner
and more accurate branch protection payloads.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
## Summary

Fixed release promotion of unshipped to shipped api

## Type of change

- [x] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation / samples only

## Checklist

- [ ] Unit tests added or updated (`/tests`)
- [ ] Benchmarks added or updated (`/benchmarks`) — if
performance-impacting
- [ ] XML doc comments updated for all public API changes
- [ ] `dotnet format` run with no issues
- [ ] README and `/samples` updated — if public API changed
- [ ] PR label added (`breaking` / `feat` / `fix` / `docs`) — for
changelog categorization

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…285)

## Summary

The "Promote PublicAPI files" job failed because
`branch-protection/unlock` called the classic branch protection API,
which returns 404 now that the repo uses rulesets.

- `unlock` now finds the repository rulesets applying to the branch and
adds it to each ruleset's `exclude` list (with rollback on failure);
outputs `ruleset-ids`.
- `lock` now takes `ruleset-ids` and removes the branch from the exclude
lists.
- `release.yml` and `backtrack.yml` updated accordingly (the old
`lock_branch` steps in backtrack were removed as rulesets have no
equivalent).
- Docs updated.

Not run end-to-end; requires `GH_ADMIN_TOKEN` with repository
administration write access.

## Type of change

- [x] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation / samples only

## Checklist

- [ ] Unit tests added or updated (`/tests`)
- [ ] Benchmarks added or updated (`/benchmarks`) — if
performance-impacting
- [ ] XML doc comments updated for all public API changes
- [ ] `dotnet format` run with no issues
- [ ] README and `/samples` updated — if public API changed
- [ ] PR label added (`breaking` / `feat` / `fix` / `docs`) — for
changelog categorization

---------

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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
## Summary

Allow the Create release job to run when unrelated upstream jobs are
skipped, while requiring all direct prerequisites to succeed and
preventing execution after cancellation.

## Type of change

- [x] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation / samples only

## Checklist

- [ ] Unit tests added or updated (`/tests`)
- [ ] Benchmarks added or updated (`/benchmarks`) — if
performance-impacting
- [ ] XML doc comments updated for all public API changes
- [ ] `dotnet format` run with no issues
- [ ] README and `/samples` updated — if public API changed
- [ ] PR label added (`breaking` / `feat` / `fix` / `docs`) — for
changelog categorization

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
## Summary

Minor changes to docs and pipelines.

## Type of change

- [x] Bug fix
- [ ] New feature
- [ ] Breaking change
- [x] Documentation / samples only

## Checklist

- [ ] Unit tests added or updated (`/tests`)
- [ ] Benchmarks added or updated (`/benchmarks`) — if
performance-impacting
- [ ] XML doc comments updated for all public API changes
- [ ] `dotnet format` run with no issues
- [ ] README and `/samples` updated — if public API changed
- [ ] PR label added (`breaking` / `feat` / `fix` / `docs`) — for
changelog categorization

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
## Summary

Docs removed version 0.0, fixed build action.

## Type of change

- [x] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation / samples only

## Checklist

- [ ] Unit tests added or updated (`/tests`)
- [ ] Benchmarks added or updated (`/benchmarks`) — if
performance-impacting
- [ ] XML doc comments updated for all public API changes
- [ ] `dotnet format` run with no issues
- [ ] README and `/samples` updated — if public API changed
- [ ] PR label added (`breaking` / `feat` / `fix` / `docs`) — for
changelog categorization

---------

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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ture (#303)

This pull request introduces new API reference documentation for the
abstract polyline encoder and decoder base classes, and also updates
build workflow conditions. The most significant changes are the addition
of detailed YAML documentation files for
`AbstractPolylineEncoder<TCoordinate, TPolyline>` and
`AbstractPolylineDecoder<TPolyline, TCoordinate>`, which describe their
constructors, methods, properties, and usage. Additionally, the build
workflow condition is refined to prevent running jobs for version '0.0'.

**API Reference Documentation:**

* Added comprehensive YAML documentation for the
`AbstractPolylineEncoder<TCoordinate, TPolyline>` class, including its
constructors, methods, properties, and extension methods. This
documentation provides clear guidance for implementers on how to extend
the encoder for custom types.
* Added comprehensive YAML documentation for the
`AbstractPolylineDecoder<TPolyline, TCoordinate>` class, including its
constructors, methods, properties, and exception handling. This
documentation guides developers in creating custom decoders and
understanding error scenarios.

**Build Workflow Update:**

* Updated the build workflow condition in `.github/workflows/build.yml`
to only run jobs when the version is not '0.0', preventing unnecessary
builds for placeholder versions.

---------

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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The Update CHANGELOG.md job failed with GH013 (changes must go through a
PR) on release/1.0. Both the CHANGELOG and PublicAPI.Unshipped pushes
now use artifact + branch-protection unlock + git/push-changes + lock,
matching promote-api-files. Remaining pushes (tags, new branches) don't
target protected existing branches.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: dependabot[bot] <support@github.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>
@petesramek
petesramek merged commit 3623a8c into main Oct 29, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant