Skip to content

OpenSlideSharp 4.x: upstream sync and release automation - #6

Merged
IOL0ol1 merged 38 commits into
masterfrom
feature/plan5-release
Nov 19, 2026
Merged

IOL0ol1 merged 38 commits into
masterfrom
feature/plan5-release

Conversation

@IOL0ol1

@IOL0ol1 IOL0ol1 commented Nov 18, 2026 •

Copy link
Copy Markdown
Owner

Plan 5 of the OpenSlideSharp 4.x rewrite (docs/plans/2026-11-18-plan5-release.md).

  • Upstream openslide-bin assets are checked against the GitHub release digests; the runtime package carries per-platform notices and openslide-bin.json; nuget.exe is pinned by hash.
  • Package metadata: LICENSE.txt for the runtime and tool packages, LGPL source notices that point at the openslide-bin source tarball attached to each 4.x GitHub release, and a viewer SOURCE.md written at publish time.
  • eng/Get-ReleaseVersion.ps1 computes the NuGet version from the manifest, tags and nuget.org; eng/Find-UpstreamUpdate.ps1 finds newer openslide-bin builds. Both self-test in CI.
  • release.yml tests the commit with the reusable CI workflow, packs the five packages and the three viewer archives, runs each archive on its own platform, then pushes to nuget.org, tags the commit and creates the GitHub release. Without the NUGET_API_KEY secret every run is a dry run.
  • upstream-sync.yml checks for new openslide-bin builds daily, updates the manifest on a sync branch, tests it, fast-forwards master and calls the release workflow; a failure opens one issue per build.
  • Fixes: openslide-sharp refuses a symlinked output root and checks Deep Zoom tile sizes before touching the old output; DeepZoom and thumbnail argument checks match openslide-python.
  • Docs: versioning and automatic releases, old packages to deprecate, viewer downloads.

Follow-ups are listed in docs/notes/2026-11-18-plan5-carryover.md.

…rm notices and pin nuget.exe

- Update-OpenSlideManifest.ps1 checks every archive, and the openslide-bin
  source tarball it now records as "source", against the sha256 digest of
  the GitHub release asset, and refuses to write the manifest otherwise.
- Get-OpenSlide.ps1 keeps each archive's licenses and VERSIONS.md in
  licenses/<archive key>/ instead of one archive's copy at the root, writes
  openslide-bin.json (build, versions and source tarball), and gains
  -Verify, which packing now runs first.
- OpenSlideSharp.runtime packs the per-platform licenses and
  openslide-bin.json, and states its terms in LICENSE.txt
  (PackageLicenseFile) instead of the LGPL-2.1-only expression.
- Test-Packages.ps1 pins nuget.exe 8.0.0 by version and sha256, asserts
  dependency groups exactly, and checks the new runtime, tool and viewer
  license layouts.
Replacing an output moves it aside and deletes it. When the output root was
a link to a directory holding the marker, the link was moved and the files of
the directory it points to were deleted through it. EnsureReplaceableDirectory
now refuses any output root that is a link (exit code 1, "is a link") before
anything is changed.
The constructor refused tileSize + 2 * overlap above int.MaxValue / 4 (reported
for overlap), although such a generator works wherever the tiles stay small,
for example a tile size larger than every level. GetTile now checks the tile
and the slide region it reads before allocating anything, and reports a size
too large for a .NET array for the level parameter. Tile sizes are kept as
long, so GetTileDimensions and GetTileCoordinates report wide overlaps
without overflowing.
…mum to lower

GetThumbnail allocated the output first and only then found that the level it
reads whole does not fit in a .NET array, reported for 'width'. It now checks
the level first and reports it for maxWidth or maxHeight, whichever ratio
chose the level. The body moves to an internal RenderThumbnail over any
render source, so a test can use a level larger than any fixture.
… array

Encode with ColorMode.Default caches the transform per array that holds the
image's ICC profile, by reference, so a caller that changes that array
afterwards keeps getting the transform made for the old bytes. Say so on
SkiaColorTransform, GetCached and Encode, and pin the behaviour in a test.
…n given

With OpenSlideUpstreamVersion set (the release build passes the openslide
version of the bundled openslide-bin build), InformationalVersion is
<version>+openslide.<upstream version>, without the git commit hash the SDK
appends. Without it nothing changes. The test checks the core assembly built
with the same properties.
… of the OpenSlide source

The tool package now uses PackageLicenseFile like the runtime package:
LICENSE.txt holds the MIT license of its own code and states the terms of
what it redistributes (OpenSlide with each platform's linked libraries,
SkiaSharp and Skia, OpenSeadragon and its scale bar plugin, and
System.CommandLine, whose MIT text it reproduces), pointing to their texts in
licenses/.

Nightly source tarballs on openslide/builds expire, so the runtime and tool
license files and READMEs also name the copy of
openslide-bin-<binVersion>.tar.gz attached to the OpenSlideSharp GitHub
release of the same version, checked against source.sha256 in
openslide-bin.json. Test-Packages asserts the tool's license file and that
both license files point to the source.
…form's openslide-bin notices

licenses/SOURCE.md is no longer a fixed file that gives only URL patterns.
PublishLicenses writes it from openslide-bin.json (runtime package or
artifacts/native): the exact openslide-bin build and OpenSlide version, the
source tarball's file name, sha256 and URL, the copy attached to the
OpenSlideSharp GitHub release of the viewer's version, and how to load another
OpenSlide build with OPENSLIDE_LIBRARY_PATH.

A publish now carries the openslide-bin notices of its RID's archive only
(win-x64: windows-x64, linux-x64: linux-x86_64, linux-arm64: linux-aarch64,
osx-*: macos-arm64-x86_64; all four for a publish without a RID), and fails
for a RID openslide-bin does not build. THIRD-PARTY-NOTICES.txt now
reproduces the MIT texts of MicroCom.Runtime and Tmds.DBus.Protocol.
Test-Packages checks that the viewer's openslide-bin notices are exactly the
runtime package's for its platform and that SOURCE.md names the build.
…e-bin updates

NuGetVersion.psm1 orders versions by NuGet rules. Get-ReleaseVersion.ps1 applies the version table and refuses a version that is not above the highest one on nuget.org. Find-UpstreamUpdate.ps1 lists the stable and nightly upstream releases worth syncing, lowest version first. Both have a network-free -SelfTest.
…numbering and upstream detection

Self-test cases must yield exactly one boolean. Published versions count toward the .N numbering, an empty nuget.org list is an error, the stable release is the highest one in the list rather than releases/latest, and the stable commit hash is carried into the upstream version string.
Test-Packages.ps1 -PackOnly packs the five packages the usual way and checks
their contents, without the smoke tests, leaving them in artifacts/smoke-feed.
-OpenSlideUpstreamVersion goes to every pack, and every OpenSlideSharp
assembly in the packages must then have the InformationalVersion
<version>+openslide.<upstream version>.
eng/Publish-Viewer.ps1 holds the viewer publish and its checks from
Test-Packages.ps1, now for any RID: self-contained single file with the
OpenSlide library from the runtime package in a feed, only the executable and
licenses/ in the folder, the RID's openslide-bin notices, and SOURCE.md naming
the release v<version>. On the machine's own RID it also runs --check.

-ArchiveDirectory writes the release download,
OpenSlideSharp.Viewer-<version>-<rid>.zip for Windows and .tar.gz otherwise,
entry by entry so that the executable has mode 755 whatever the host.
Test-Packages.ps1 runs the script for its viewer smoke test.
eng/Get-ReleaseFiles.ps1 adds the source tarball of eng/openslide.json to a
folder of release files, as openslide-bin-<binVersion>.tar.gz once its
sha256 matches the manifest, then fails unless the folder holds exactly the
five nupkgs, the three viewer archives and the tarball of the version. It
lists them, with sizes and sha256, in the run summary.
ci.yml can be called by another workflow with the ref to test; every job
checks that ref out. A new actionlint job lints the workflows with actionlint
1.7.12, downloaded from its release and checked against the sha256 in the
release's checksums file.
release.yml runs on pushes to master that change src/, eng/openslide.json
or Directory.*.props, by hand, and from another workflow with a ref. It
computes the version of the commit, runs ci.yml on that commit, packs the
five packages and publishes the viewer for win-x64, linux-x64 and osx-arm64.
With the NUGET_API_KEY secret it then pushes the packages to nuget.org, tags
the commit v<version> and creates the GitHub release with the packages, the
viewer archives and the openslide-bin source tarball; nightly versions are
prereleases. Without the key, with dry_run, or for a commit that is not on
master it pushes nothing and lists the release in the run summary.

Only the publish job can write to the repository. Running it again is safe:
the push skips packages already on nuget.org, and an existing tag or release
of the same commit is kept.
…suming them

The tool pack and the viewer publish restored OpenSlideSharp.runtime from the
local feed and nuget.org alike, and the OpenSlideSharp* ids are not reserved
there, so a package of the same id and version on nuget.org could have put
another native library into the tool and the viewer archive.

eng/LocalFeed.psm1 writes a NuGet.config that maps OpenSlideSharp* to the
local feed only and everything else to nuget.org; the tool pack and the
viewer publish restore with it. The smoke project's NuGet.config maps
OpenSlideSharp* the same way, and the smoke tool install uses the feed as its
only source. After each of these restores, every OpenSlideSharp package it
resolved must have the sha512 of the feed's nupkg, or the build fails.
A called ci.yml uploads its packages artifact into the caller's run, and the
upstream sync calls it twice (for the sync branch, then through release.yml),
so the second upload failed on the existing name. The calls run one after the
other, so the second now replaces the first's packages.
Being on master was not enough: re-running an old run with "Re-run all jobs",
or running the workflow on a tag or a merged branch, released an older commit
under a higher version, and a version already on nuget.org was taken for this
release's own earlier attempt.

eng/Test-ReleaseCommit.ps1 now fails the version job for a commit that
carries a release tag or does not contain the latest one, and, before the
publish job pushes anything, for a tag v<version> on another commit or a
package of the version on nuget.org, or in the release files, built from
another commit (the commit in its nuspec). The workflow's header says to use
"Re-run failed jobs" after a failure.
…uild

eng/Report-SyncFailure.ps1 opens "Upstream sync failed: openslide-bin <tag>" (or "... update check" when the
run failed before finding a build), or comments on the open issue of that title, with the run link and each job's
result, then deletes the run's sync/<tag> branch. -SelfTest runs it against a mocked GitHub API.
upstream-sync.yml takes the next newer openslide-bin build: it commits the manifest and the regenerated bindings
on sync/<tag>, tests the commit with ci.yml, fast-forwards master to it (or opens a pull request when master moved)
and releases it with release.yml. A failure changes nothing on master and is reported once per build. A dry run
commits in the runner only and shows the diff in the run summary.
… old output

With -s/-e large enough that a tile, or the slide region read for it, needs
more bytes than a .NET array can hold, GetTile failed only after the old
output had been moved aside and deleted, naming a 'level' parameter the user
never gave. Check the largest tiles of every image first and exit with 2,
naming -s and -e. A tile size larger than a small slide still works.
…censes

It describes the nupkg's layout (licenses/<platform>/, runtimes/), which the
viewer's licenses/ folder does not have; THIRD-PARTY-NOTICES.txt and SOURCE.md
say the same for the viewer. Publish-Viewer checks that it is gone.
…after a nightly

A stable release's notes said that the upstream nightly URL expires. When the
release before a stable one was built on a nightly, the notes now also say
that functions only that nightly had may be gone from OpenSlideSharp.Native
(design 7.2, rule 5). The previous release is the highest lower v* tag or
published version; its channel comes from its tagged eng/openslide.json, or
from its version's form when that is not available.
The release publishes all three viewer archives on Linux, and only linux-x64
was ever run. A new job extracts each archive on windows-latest, ubuntu-latest
or macos-latest and runs it with --check (eng/Test-ViewerArchive.ps1); on
Windows it also checks the version resource, application manifest and GUI
subsystem that the SDK writes into the executable. publish and the dry run
summary wait for it.
A dry run dispatched on a branch shared the single release group with the
releases of master, and a newer pending run cancels the older one. The group
is now publish-<ref>: the upstream sync's calls and pushes to master still
share one. It is not release-<ref>, which, as group names are case
insensitive, equals the group of the ci.yml call inside the run.
…ing and gets no CI by itself

A pull request opened with the workflow token starts no workflow, so CI runs
on it only after it is closed and reopened; its description now says so. The
merge job also notes that opening it needs "Allow GitHub Actions to create and
approve pull requests".
@IOL0ol1
IOL0ol1 force-pushed the feature/plan5-release branch from fb03a90 to 38437ba Compare November 18, 2026 16:29
@IOL0ol1
IOL0ol1 marked this pull request as ready for review November 19, 2026 02:15
@IOL0ol1
IOL0ol1 merged commit b36a535 into master Nov 19, 2026
12 checks passed
@IOL0ol1
IOL0ol1 deleted the feature/plan5-release branch November 19, 2026 02:41
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