The Palaso repo is a collection of shared libraries that are used in SIL .NET applications. The libraries are mostly cross-platform compatible. All non-test assemblies have a corresponding nuget package.
The Palaso library adheres to Semantic Versioning and keeps a Changelog to record noteworthy changes.
- Overview over the assemblies
- See wiki for documentation
Every commit creates a nuget package that is available on nuget.org.
To get the source code, you'll need Git. Then from a command line, give this command:
git clone https://github.com/sillsdev/libpalaso
- Building libpalaso requires the .NET 9 SDK or later (the code uses C# 13). You might want to install Visual Studio 2022 >= 17.12, or JetBrains Rider >= 2024.3.
On Ubuntu 24.04 (Noble), install the .NET 10 SDK, plus the .NET 8 runtime for
running the net8.0 unit tests:
sudo apt update
sudo apt install dotnet-sdk-10.0 dotnet-runtime-8.0 libicu-devAlternatively, install .NET by following https://learn.microsoft.com/dotnet/core/install/linux-ubuntu.
Running the .NET Framework (net462/net48) unit tests additionally needs Mono:
sudo apt install mono-complete libcanberra-gtk-module-
Create a local topic branch:
git fetch git checkout -b my-work origin/master
-
Build:
Open
Palaso.slnin Visual Studio and build.Open and build
Palaso.slnin JetBrains Rider. Or use the command line.EnableWindowsTargetinglets thenet8.0-windowsprojects build on Linux.dotnet build Palaso.sln -p:EnableWindowsTargeting=true
-
Verify that there were no new unit test failures:
build\TestBuild Debug TestRun the
net8.0tests one test project at a time (the WinForms test projects have nonet8.0target), with the same filter CI uses:dotnet test SIL.Core.Tests -f net8.0 -p:EnableWindowsTargeting=true \ --filter "(TestCategory != SkipOnTeamCity) & (TestCategory != RequiresAudioInputDevice)"
On WSL, first remove the Windows folders (
/mnt/c/...) fromPATH. On Linux,FileLocationUtilitiessearches everyPATHfolder and its subfolders for programs, and searching the Windows drive from WSL is slow enough that theFileLocationUtilitiesTeststake more than 15 minutes:export PATH=$(echo "$PATH" | tr ':' '\n' | grep -v '^/mnt/' | paste -sd:)
-
Test in client projects (as applicable):
- Set an environment variable
LOCAL_NUGET_REPOwith the path to a folder on your computer (or local network) to publish locally-built packages - See these instructions to enable local package sources
build /t:packwill pack nuget packages and publish them toLOCAL_NUGET_REPO
- Set an environment variable
Further instructions at https://github.com/sillsdev/libpalaso/wiki/Developing-with-locally-modified-nuget-packages
- Updating langtags.json and ianaSubtagRegistry.txt:
- Instructions for updating the langtags.json and ianaSubtagRegistry.txt files are in SIL.WritingSystems/Readme.md
-
Commit. Push:
$ git push origin TOPICBRANCHNAME
-
Send a pull request (https://help.github.com/articles/using-pull-requests). Specify destination branch if not
master.
Palaso is localized with L10NSharp. Palaso-specific documentation is in l10n/README.md.
These libraries use GitVersion. For simplicity, all library versions advance in lockstep.
-
When a commit introduces a breaking change, include
+semver:majorat the start of the commit message. -
For API additions or other backward-compatible enhancements, use
+semver:minor.
Beta builds are published automatically to nuget.org by the build-test GitHub Action.
To publish an official release version:
-
Push a Git tag in the format
v10.5.1(matching the current beta version calculated by GitVersion). -
Manually run the
build-testworkflow in GitHub Actions.
The palaso library follows semantic versioning. For APIs this means:
- public APIs that become deprecated will be marked as obsolete.
- The API and its obsolete tag will remain through the beta versions and at least one more stable version.
- The API will be removed in one of the next stable versions.