Versioning

Versioning in SkiaSharp is mostly simple, but is slightly different because it is based on the version of the underlying skia library version.

Stable Versions

As with all version numbers, there are 4 parts. However, these parts are not strictly the major.minor.build[.revision] that is typically associated with .NET versioning.

The version number for SkiaSharp is as follows: major.skia.minor.patch

• major represents a major upgrade that radically changes the underlying API and/or behavior
  This usually happens after a long period of using the same skia version and several iterations have finally made APIs obsolete. Or, it may be the case that there are fairly large behavior changes that might warrant some closer testing.
  An example would be when v2 changed the way color spaces were loaded and handled as well as the way text was processed.
• skia represents the milestone/tag provided by Google
  In many cases, this is not really a major change in the same way major because even though the engine has received many updates, the overall behavior is very similar. There are often some slight behavior changes, but not in such a way that will break existing apps/libraries.
• minor represents an update with either bug fixes or new APIs
  This is usually when a new feature is added or a bug is fixed. This is typically not a breaking change, and usually does not have behavior changes (except to fix the bug).
• patch represents a very minor change to either the assemblies or packaging
  This is not very common, but sometimes there is an issue that affects the usage of the library, but not the library itself. An example was with v1.68.1.1 when there was an issue with the assembly strong naming and it was only delay signed.

Preview Labels

With regards to the pre-release versioning, it follows the typical pattern. However, there is one type that is a bit different.

Although several preview versions are found on nuget.org, many more are also periodically released to the preview feed:
https://aka.ms/skiasharp-eap/index.json

Typically, the pre-release labels are:

• -alpha is very early and has not really been tested
• -preview is mostly good and works, but a few more things need to be done (bugs, features, discussions)
• -rc is almost ready to go out, but is waiting on third party feedback (not too common)

PR Packages

The exception to the pattern is the PR versions: -pr.xxxx.yy These builds are not on NuGet, but on the preview feed. These builds are directly related to a specific PR and contain either a bugfix or untested version of a feature.

These are used to release a feature for easy install, and will be soon merged into the main branch. Sometimes these builds are not as up-to-date as the main branch because they were forked. This is not always the case, and often are updated, but not always.

Native API Versions

Many of the releases of SkiaSharp use the exact same git SHA between releases (ie: 1.68.2, 1.68.2.1, 1.68.3) so we make use of the fact that the API is being versioned, not the library. So, for example, if the C++ library has a bug and we fix that but do not touch the C API, then we do not have to bump the second version number - because the API did not change.

There are probably going to be two numbers used to make up a version: the skia milestone and the C API iteration (restarting with each milestone). For example, the new v2.80.0 will be "80.0". If we do a managed-only update, then the native version is unchanged. If we do a new binding and add a new C API, then the native version becomes "80.1". If we then do another bugfix somewhere in the native code, but do not touch the C API, then we leave the version number as the same.

With regards to backwards compat, I'll make sure that the C API never breaks for a major milestone and is always backwards compatible in that milestone. So, if the native library is "80.2", then this will work with the managed libraries that are compatible with "80.0" to "80.2". But not with a managed library built against "80.3" or later.

Changes	NuGet/Managed	Native
Initial release	v2.80.0	80.0
C# change	v2.80.1	80.0
C API added	v2.80.2	80.2
C++ bug fixed	v2.80.3	80.2
Packaging fix	v2.80.3.1	80.2
C# API added	v2.80.4	80.2
C API added	v2.80.5	80.5
Update skia	v2.84.0	84.0

We do skip iteration values, but that is not so important.