Release Process

Purpose and Scope

This document describes the automated release process for LLamaSharp, including how releases are triggered, versioned, built, and distributed across multiple channels (NuGet, GitHub Pages, Hugging Face). The release system uses GitHub Actions workflows with label-based triggers to automate the entire publishing pipeline.

For information about native binary compilation that occurs independently of package releases, see Native Binary Compilation. For details about continuous integration testing, see CI/CD Pipeline.

---

Release Trigger Mechanism

LLamaSharp uses a label-based pull request workflow to initiate releases. When a PR is merged to the master branch with specific labels, it triggers the release automation.

Label Types

Label	Release Type	Workflow File
patch-release	Patch version increment (0.0.X)	.github/workflows/release-patch-trigger.yml
minor-release	Minor version increment (0.X.0)	.github/workflows/release-minor-trigger.yml

Mutual Exclusivity: The trigger workflows ensure that only one label is active. If both labels are present on a PR, neither trigger fires , .

Trigger Workflow Execution

The trigger workflows execute minimal setup actions to validate the environment:

These workflows simply set up the .NET SDK and immediately complete, causing the main release workflows to execute via the workflow_run trigger , .

Sources: ,

---

Release Workflow Architecture

Title: Release Pipeline Flow

The release system uses a two-stage workflow pattern where trigger workflows validate conditions and main workflows perform the actual release operations. This separation ensures that only successful triggers initiate the resource-intensive build and publish steps.

Sources: ,

---

Release Workflow Steps

1. Environment Setup

Both patch and minor release workflows execute on ubuntu-22.04 runners and configure the environment identically , :

• Configure Git Credentials (user: Rinne)
• Setup NuGet with API token
• Check .NET info and install dependencies

2. Project Build

Three core projects are built in Release configuration :

Project	Path
Core Library	./LLama/LLamaSharp.csproj
Semantic Kernel Integration	./LLama.SemanticKernel/LLamaSharp.SemanticKernel.csproj
Kernel Memory Integration	./LLama.KernelMemory/LLamaSharp.KernelMemory.csproj

3. Package Preparation

The prepare_release.sh script is invoked with different arguments based on release type:

Release Type	Script Arguments	Behavior
Patch	false true	Increments patch version (0.0.X)
Minor	true false	Increments minor version (0.X.0)

The script performs the following operations:

• Directory Setup: Creates a ./temp directory and copies runtimes and build props .
• Version Detection: Adds the existing LLamaSharp package to a temporary project to resolve the latest published version .
• Version Calculation: Increments the version string based on the release type (minor or patch) .
• Packing: Executes dotnet pack for the core projects with the new version and symbol settings .
• Backend Packing: Iterates through .nuspec files in the runtimes folder and packs them using nuget pack .

Sources: , ,

4. Artifact Upload

Generated packages are uploaded as workflow artifacts with name drop-ci-packages from the ./temp directory .

5. NuGet Publication

All generated LLamaSharp packages are pushed to nuget.org using the LLAMA_SHARP_NUGET_KEY_REPO secret :

Sources: ,

---

Documentation Deployment

MkDocs Material with Mike Versioning

The release workflows deploy documentation to GitHub Pages using mike for version management:

Title: Documentation Versioning Flow

The workflow installs mkdocs, mkdocs-material, and mike via pip . It then reads the version from ./temp/version.txt and updates the documentation aliases . The mkdocs.yml file defines the structure and content of the documentation, including API references and tutorials .

Sources: , ,

---

Hugging Face Distribution

Native Binary Upload

After NuGet publication and documentation deployment, the workflow uploads native binaries to Hugging Face using the repository AsakusaRinne/LLamaSharpNative.

Title: Native Binary Upload Flow

Upload Process

The upload_to_hf.py script implements the following sequence :

1. Extract llama.cpp commit hash: The workflow extracts the first 6 characters of the llama.cpp submodule commit hash .
2. Branch management: The script checks if a branch named after the hash exists; if so, it deletes it and creates a fresh one .
3. Folder upload: The contents of the LLama/runtimes folder are uploaded to the runtimes/ path in the Hugging Face repository .

Sources: ,

---

Distribution Channels Summary

Title: Multi-Channel Distribution

Channel	Purpose	Update Frequency	Access Method
nuget.org	Primary distribution for .NET developers	Every release (patch/minor)	dotnet add package LLamaSharp
GitHub Pages	Versioned documentation	Every release	https://scisharp.github.io/LLamaSharp/
Hugging Face	Historical native binaries by llama.cpp commit	Every release	Git clone or web download

Sources: ,

---

Versioning Strategy

Semantic Versioning

LLamaSharp follows semantic versioning principles via the prepare_release.sh script:

Version Component	When to Increment	Label	Logic
Major (X.0.0)	Breaking API changes	(Manual)	N/A
Minor (0.X.0)	New features, llama.cpp updates	minor-release	b=$((b + 1)); updated_version="${version%%.*}.$b.0"
Patch (0.0.X)	Bug fixes, documentation	patch-release	c=$((c + 1)); updated_version="${version%.*}.$c"

Version Calculation

The version calculation relies on dotnet list package to find the current version from NuGet and then applies regex matching to perform the increment .

Sources: ,

---

Workflow Secrets

The release workflows require the following GitHub secrets:

Secret	Usage	Referenced In
LLAMA_SHARP_NUGET_KEY_REPO	NuGet.org API key for publishing packages
HUGGINGFACE_TOKEN	Authentication for uploading to Hugging Face

Sources: ,