Palaso Library

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.

Documentation

• Overview over the assemblies
• See wiki for documentation

Binaries

Every commit creates a nuget package that is available on nuget.org.

Source Code

To get the source code, you'll need Git. Then from a command line, give this command:

git clone https://github.com/sillsdev/libpalaso

Development

Dependencies

Windows

• Building libpalaso requires .NET 5 or later. You might want to install Visual Studio 2019 >= 16.8, or JetBrains Rider.

Ubuntu Linux

These libraries cannot currently be built on Linux releases later than Focal without some additional steps/dependencies (because dotnet-sdk-5.0 is no longer supported and does not have a package installer for more recent versions and ).

To build on Ubuntu 22.04 (Jammy), you have to:

• Use mono-devel from Focal
• Use dotnet-sdk-6.0
• To get unit tests to pass, you have to install libcanberra-gtk-module (libcanberra-gtk-module/jammy,now 0.30-10ubuntu1 amd64). Not sure what is the correct way to get that dependency installed.

The rest of the stuff:

• Add access to packages.microsoft.com repo for dotnet sdk:

  wget https://packages.microsoft.com/config/ubuntu/$(lsb_release -s -r)/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
  sudo dpkg -i packages-microsoft-prod.deb
  rm packages-microsoft-prod.deb

• Add access to download.mono-project.com for mono 6 by following instructions at https://www.mono-project.com/download/stable.

• To get unit tests to pass, you have to install libcanberra-gtk-module

• Install the dependencies with:

  sudo apt update
  sudo apt install libicu-dev dotnet-sdk-6.0 mono-devel msbuild libcanberra-gtk-module

Note: Newer Ubuntu versions have .NET 6+ and Mono 6 in their package repos. However, those packages are missing some required files so that building libpalaso won't succeed. Therefore it's recommended to install .NET 6+ and Mono from Microsoft's/Mono's package repos.

Develop

• Create a local topic branch:

  git fetch
  git checkout -b my-work origin/master

• Build:

  Windows

  Open Palaso.sln in Visual Studio and build.

  Linux

  Open and build Palaso.sln in JetBrains Rider. Or use the commandline. environ is not needed if you installed mono-complete version 6.

  build/build

• Verify that there were no new unit test failures:

  Windows

  build\TestBuild Debug Test

  Linux

  build/TestBuild Debug Test

• Test in client projects (as applicable):

  • Set an environment variable LOCAL_NUGET_REPO with 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:pack will pack nuget packages and publish them to LOCAL_NUGET_REPO

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

Contribute

• Commit. Push:

  $ git push origin TOPICBRANCHNAME

• Send a pull request (https://help.github.com/articles/using-pull-requests). Specify destination branch if not master.

Localization

Palaso is localized with L10NSharp. Palaso-specific documentation is in l10n/README.md.

Semantic versioning

These libraries use GitVersion. For simplicity, all library versions advance in lockstep.

• When a commit introduces a breaking change, include +semver:major at the start of the commit message.

• For API additions or other backward-compatible enhancements, use +semver:minor.

Deployment on nuget.org

Beta builds are published automatically to nuget.org by the build-test GitHub Action.

To publish an official release version:

1. Push a Git tag in the format v10.5.1 (matching the current beta version calculated by GitVersion).

2. Manually run the build-test workflow in GitHub Actions.

API Policy

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.