elisunger/libpalaso

Palaso Library: A set of .Net libraries useful for developers of Language Software.

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. You might want to install Visual Studio 2019 >= 16.8, or JetBrains Rider.

Ubuntu Linux

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

  cd $(mktemp -d) &&
  curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg &&
  sudo mv microsoft.gpg /etc/apt/trusted.gpg.d/ &&
  (source /etc/os-release && wget -q https://packages.microsoft.com/config/${ID}/${VERSION_ID}/prod.list -O prod.list) &&
  sudo mv prod.list /etc/apt/sources.list.d/microsoft-prod.list &&
  sudo chown root:root /etc/apt/trusted.gpg.d/microsoft.gpg /etc/apt/sources.list.d/microsoft-prod.list &&
  sudo chmod 644 /etc/apt/trusted.gpg.d/microsoft.gpg /etc/apt/sources.list.d/microsoft-prod.list

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

• Install package dependencies:

  sudo apt update
  sudo apt install libicu-dev dotnet-sdk-5 mono-complete

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 enviroment 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

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.

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.