From 2251229c4d815bae15bf878690aef38c4d2ebb78 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 16 May 2026 19:39:37 +0000 Subject: [PATCH] docs: add OpenSSF Best Practices passing-level artifacts - CONTRIBUTING.md with test policy - SECURITY.md with vulnerability reporting process - CHANGELOG.md seeded from existing tags --- CHANGELOG.md | 73 ++++++++++++++++++++++++ CONTRIBUTING.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++ SECURITY.md | 42 ++++++++++++++ 3 files changed, 260 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..bd87e0d7 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,73 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +--- + +## [Unreleased] + +### Added +- OpenSSF Best Practices badge (project 12862) added to README. +- CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md to satisfy OpenSSF passing-level criteria. + +### Changed +- Upgraded llama.cpp from b9151 to b9172. +- Added reasoning-budget tests (Qwen3-0.6B). + +--- + +## [5.0.1] - 2026-05-14 + +### Added +- `InferenceParameters.setContinueFinalMessage(boolean)` for vLLM-compatible prefill-assistant heuristic (llama.cpp b9134+). +- Tests for `setContinueFinalMessage`. + +### Changed +- Upgraded llama.cpp from b9106 to b9145 (b9106 → b9134 → b9145 in increments). +- Switched Windows MSVC runtime from dynamic (`/MD`) to static (`/MT`) to eliminate `msvcp140.dll` dependency. +- Updated CI Windows runners to `windows-2025-vs2026` (Visual Studio 18 2026). +- CI publish workflow: added check-snapshot/check-tag gates for correct release routing; bumped `softprops/action-gh-release` v2 → v3 (Node 24). +- Removed `setCtxSizeDraft()` (CLI flag removed in llama.cpp b9106). + +### Fixed +- CI gate job name quoting to prevent YAML parse errors. +- Release routing in publish workflow to correctly distinguish snapshot vs. tag pushes. + +--- + +## [5.0.0] - 2026-05-11 + +### Added +- First release under the `net.ladenthin` Maven group ID (`net.ladenthin:llama`), published to Maven Central. +- Pre-built native libraries for Linux (x86-64, aarch64), macOS (x86-64, arm64), and Windows (x86-64, x86). +- Java API surface: `LlamaModel`, `ModelParameters`, `InferenceParameters`, `LlamaIterator`/`LlamaIterable` for streaming, chat completion (`chatComplete`, `generateChat`, `chatCompleteText`), embeddings, reranking, infilling, raw JSON endpoint handlers, slot management (`saveSlot`, `restoreSlot`, `eraseSlot`), and `getModelMeta()`. +- `mmproj`, reasoning-budget, sigma, and sleep-idle parameters added to `ModelParameters`. +- JaCoCo code-coverage reporting integrated with Coveralls and Codecov. +- CodeQL static-analysis workflow running on push, PR, and weekly schedule. +- Claude Code automated code-review workflow on pull requests. +- Dependabot for Maven and GitHub Actions dependency updates. +- Snapshot builds published to Sonatype Central snapshot repository on every `main` push. +- CUDA, Metal, and Vulkan build support via local CMake build. +- Android integration documented in README. +- All system properties (`net.ladenthin.llama.*`) and `LogLevel` values documented. + +### Changed +- Migrated Maven group and artifact from `de.kherud:java-llama.cpp` to `net.ladenthin:llama`. +- Migrated Maven Central publishing from OSSRH (Legacy) to Sonatype Central Publisher Portal. +- Unified CI into a single `publish.yml` workflow with cross-compilation, testing, coverage, and release stages. +- CI GitHub Actions bumped: `actions/checkout` v4 → v6, `actions/upload-artifact` v6 → v7, `actions/download-artifact` v6 → v8, `codeql-action` v3 → v4. +- Upgraded llama.cpp from b8913 through b9106 (multiple incremental upgrades). +- `setDraftMax`/`setDraftMin` fixed to emit canonical `--spec-draft-n-max`/`--spec-draft-n-min` flags (b9016+ removed old aliases). + +### Fixed +- Javadoc: resolved all 69 warnings by adding missing comments. +- Fixed `--cache-idle-slots` bug in slot management parameters. + +--- + +[Unreleased]: https://github.com/bernardladenthin/java-llama.cpp/compare/v5.0.1...HEAD +[5.0.1]: https://github.com/bernardladenthin/java-llama.cpp/compare/v5.0.0...v5.0.1 +[5.0.0]: https://github.com/bernardladenthin/java-llama.cpp/releases/tag/v5.0.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..bcaac323 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,145 @@ +# Contributing to java-llama.cpp + +Thank you for your interest in contributing! This document explains how to build the project, file issues, submit pull requests, and what we expect from contributors. + +## Table of Contents + +1. [How to Build and Run](#how-to-build-and-run) +2. [Filing Issues](#filing-issues) +3. [Pull Request Workflow](#pull-request-workflow) +4. [Coding Standards](#coding-standards) +5. [Test Policy](#test-policy) +6. [Communication Channels](#communication-channels) +7. [License of Contributions](#license-of-contributions) + +--- + +## How to Build and Run + +### Prerequisites + +- Java 11 or later +- Maven 3.x +- CMake 3.22 or later +- A C++17-capable compiler (GCC, Clang, or MSVC) + +### Java Layer (Maven) + +```bash +# Compile Java sources and generate JNI headers (required before CMake build) +mvn compile + +# Run all tests (requires a pre-built native library and model files in place) +mvn test + +# Run a single test +mvn test -Dtest=LlamaModelTest#testGenerate + +# Package a JAR +mvn package +``` + +### Native Library (CMake) + +Run `mvn compile` first to generate the JNI headers, then: + +```bash +# CPU-only build +cmake -B build +cmake --build build --config Release + +# With CUDA support (Linux) +cmake -B build -DGGML_CUDA=ON +cmake --build build --config Release + +# With Metal support (macOS) +cmake -B build -DLLAMA_METAL=ON +cmake --build build --config Release + +# With model-download support (libcurl) +cmake -B build -DLLAMA_CURL=ON +cmake --build build --config Release +``` + +Built libraries are placed under `src/main/resources/net/ladenthin/llama/{OS}/{ARCH}/`. + +### C++ Unit Tests (no JVM or model file required) + +```bash +cmake -B build -DBUILD_TESTING=ON +cmake --build build --config Release -j$(nproc) +ctest --test-dir build --output-on-failure +``` + +### Code Formatting + +```bash +# Format C++ source files +clang-format -i src/main/cpp/*.cpp src/main/cpp/*.hpp +``` + +--- + +## Filing Issues + +Please use the GitHub issue tracker: + +- **Bug reports, feature requests, questions:** https://github.com/bernardladenthin/java-llama.cpp/issues + +Before opening an issue, search existing issues to avoid duplicates. When reporting a bug, include: + +- Operating system and architecture +- Java version (`java -version`) +- llama.cpp build tag the library was compiled against +- A minimal reproduction case (model name, parameters, code snippet) +- Full stack trace or error output + +--- + +## Pull Request Workflow + +1. **Fork** the repository on GitHub. +2. Create a **feature branch** from `main`: + ```bash + git checkout main + git pull origin main + git checkout -b feat/my-feature + ``` +3. Make your changes, including tests (see [Test Policy](#test-policy)). +4. Push the branch to your fork and open a **Pull Request** against `bernardladenthin/java-llama.cpp:main`. +5. Describe what the PR changes and why; link any related issue (`Closes #NNN`). +6. Respond to review comments and push follow-up commits to the same branch. +7. A maintainer will merge once the PR is approved and CI is green. + +--- + +## Coding Standards + +- Follow the conventions documented in [CLAUDE.md](CLAUDE.md) — it describes the project architecture, include-order rules, helper-file split (`json_helpers.hpp` vs `jni_helpers.hpp`), and Javadoc HTML-entity conventions. +- Java code targets Java 11+. +- C++ code must be compatible with C++17 and compile cleanly with the project's CMake configuration. +- Format C++ files with `clang-format` before committing (see command above). +- Use HTML entities in Javadoc for operators and symbols outside ASCII (see CLAUDE.md for the full table). + +--- + +## Test Policy + +> Every new feature or behavior change MUST include automated tests. Pull requests that add or change functionality without corresponding tests will be asked to add tests before merge. Bug fixes SHOULD include a regression test. + +- **Java tests** live in `src/test/java/net/ladenthin/llama/` and `src/test/java/examples/`. +- **C++ unit tests** (no JVM required) live in `src/test/cpp/`. Add pure-data transforms to `test_json_helpers.cpp`, JNI bridge helpers to `test_jni_helpers.cpp`, and upstream result types to `test_server.cpp`. +- Tests must pass locally before opening a PR. CI also runs them automatically on push and on pull requests. + +--- + +## Communication Channels + +- **GitHub Issues** — bug reports and feature requests: https://github.com/bernardladenthin/java-llama.cpp/issues +- **GitHub Discussions** — general questions and ideas (if enabled on the repository). + +--- + +## License of Contributions + +By submitting a pull request you agree that your contribution is made available under the **MIT License** — the same license that governs this repository (see [LICENSE.md](LICENSE.md)). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..7d43748a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,42 @@ +# Security Policy + +## Supported Versions + +Only the most recent release of the `5.x` series receives security fixes. Older major versions are not actively maintained. + +| Version | Supported | +|---------|-----------| +| 5.x (latest) | Yes | +| < 5.0 | No | + +## Reporting a Vulnerability + +**Please do not report security vulnerabilities through public GitHub issues.** + +### Primary channel — GitHub Private Vulnerability Reporting + +Use GitHub's built-in private vulnerability reporting: + +https://github.com/bernardladenthin/java-llama.cpp/security/advisories/new + +This channel is private and visible only to maintainers. It is the preferred method. + +### Secondary channel — maintainer email + +If you cannot use the GitHub advisory form, you may contact the maintainer by email. The address associated with recent commits is listed in the git log (`git log --format='%ae' -1`). Note that this address is **unconfirmed** as a monitored security contact — GitHub Private Vulnerability Reporting above is preferred. + +## Response SLA + +We aim to acknowledge vulnerability reports within 14 days of receipt and to provide a remediation timeline within 30 days. + +## Disclosure Policy + +We follow **coordinated disclosure**: + +1. Reporter submits the vulnerability privately. +2. Maintainers confirm and assess severity. +3. A fix is developed and a release date is agreed with the reporter. +4. The fix is released and a GitHub Security Advisory is published simultaneously. +5. The reporter may disclose publicly after the fix is released (or after an agreed embargo period, typically 90 days from report, whichever comes first). + +We ask reporters to keep vulnerability details **under embargo** until a fix has been released.