Skip to content

Commit 2251229

Browse files
claudeclaude
committed
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
1 parent 98174fe commit 2251229

3 files changed

Lines changed: 260 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
---
9+
10+
## [Unreleased]
11+
12+
### Added
13+
- OpenSSF Best Practices badge (project 12862) added to README.
14+
- CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md to satisfy OpenSSF passing-level criteria.
15+
16+
### Changed
17+
- Upgraded llama.cpp from b9151 to b9172.
18+
- Added reasoning-budget tests (Qwen3-0.6B).
19+
20+
---
21+
22+
## [5.0.1] - 2026-05-14
23+
24+
### Added
25+
- `InferenceParameters.setContinueFinalMessage(boolean)` for vLLM-compatible prefill-assistant heuristic (llama.cpp b9134+).
26+
- Tests for `setContinueFinalMessage`.
27+
28+
### Changed
29+
- Upgraded llama.cpp from b9106 to b9145 (b9106 → b9134 → b9145 in increments).
30+
- Switched Windows MSVC runtime from dynamic (`/MD`) to static (`/MT`) to eliminate `msvcp140.dll` dependency.
31+
- Updated CI Windows runners to `windows-2025-vs2026` (Visual Studio 18 2026).
32+
- CI publish workflow: added check-snapshot/check-tag gates for correct release routing; bumped `softprops/action-gh-release` v2 → v3 (Node 24).
33+
- Removed `setCtxSizeDraft()` (CLI flag removed in llama.cpp b9106).
34+
35+
### Fixed
36+
- CI gate job name quoting to prevent YAML parse errors.
37+
- Release routing in publish workflow to correctly distinguish snapshot vs. tag pushes.
38+
39+
---
40+
41+
## [5.0.0] - 2026-05-11
42+
43+
### Added
44+
- First release under the `net.ladenthin` Maven group ID (`net.ladenthin:llama`), published to Maven Central.
45+
- Pre-built native libraries for Linux (x86-64, aarch64), macOS (x86-64, arm64), and Windows (x86-64, x86).
46+
- 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()`.
47+
- `mmproj`, reasoning-budget, sigma, and sleep-idle parameters added to `ModelParameters`.
48+
- JaCoCo code-coverage reporting integrated with Coveralls and Codecov.
49+
- CodeQL static-analysis workflow running on push, PR, and weekly schedule.
50+
- Claude Code automated code-review workflow on pull requests.
51+
- Dependabot for Maven and GitHub Actions dependency updates.
52+
- Snapshot builds published to Sonatype Central snapshot repository on every `main` push.
53+
- CUDA, Metal, and Vulkan build support via local CMake build.
54+
- Android integration documented in README.
55+
- All system properties (`net.ladenthin.llama.*`) and `LogLevel` values documented.
56+
57+
### Changed
58+
- Migrated Maven group and artifact from `de.kherud:java-llama.cpp` to `net.ladenthin:llama`.
59+
- Migrated Maven Central publishing from OSSRH (Legacy) to Sonatype Central Publisher Portal.
60+
- Unified CI into a single `publish.yml` workflow with cross-compilation, testing, coverage, and release stages.
61+
- CI GitHub Actions bumped: `actions/checkout` v4 → v6, `actions/upload-artifact` v6 → v7, `actions/download-artifact` v6 → v8, `codeql-action` v3 → v4.
62+
- Upgraded llama.cpp from b8913 through b9106 (multiple incremental upgrades).
63+
- `setDraftMax`/`setDraftMin` fixed to emit canonical `--spec-draft-n-max`/`--spec-draft-n-min` flags (b9016+ removed old aliases).
64+
65+
### Fixed
66+
- Javadoc: resolved all 69 warnings by adding missing comments.
67+
- Fixed `--cache-idle-slots` bug in slot management parameters.
68+
69+
---
70+
71+
[Unreleased]: https://github.com/bernardladenthin/java-llama.cpp/compare/v5.0.1...HEAD
72+
[5.0.1]: https://github.com/bernardladenthin/java-llama.cpp/compare/v5.0.0...v5.0.1
73+
[5.0.0]: https://github.com/bernardladenthin/java-llama.cpp/releases/tag/v5.0.0

‎CONTRIBUTING.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Contributing to java-llama.cpp
2+
3+
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.
4+
5+
## Table of Contents
6+
7+
1. [How to Build and Run](#how-to-build-and-run)
8+
2. [Filing Issues](#filing-issues)
9+
3. [Pull Request Workflow](#pull-request-workflow)
10+
4. [Coding Standards](#coding-standards)
11+
5. [Test Policy](#test-policy)
12+
6. [Communication Channels](#communication-channels)
13+
7. [License of Contributions](#license-of-contributions)
14+
15+
---
16+
17+
## How to Build and Run
18+
19+
### Prerequisites
20+
21+
- Java 11 or later
22+
- Maven 3.x
23+
- CMake 3.22 or later
24+
- A C++17-capable compiler (GCC, Clang, or MSVC)
25+
26+
### Java Layer (Maven)
27+
28+
```bash
29+
# Compile Java sources and generate JNI headers (required before CMake build)
30+
mvn compile
31+
32+
# Run all tests (requires a pre-built native library and model files in place)
33+
mvn test
34+
35+
# Run a single test
36+
mvn test -Dtest=LlamaModelTest#testGenerate
37+
38+
# Package a JAR
39+
mvn package
40+
```
41+
42+
### Native Library (CMake)
43+
44+
Run `mvn compile` first to generate the JNI headers, then:
45+
46+
```bash
47+
# CPU-only build
48+
cmake -B build
49+
cmake --build build --config Release
50+
51+
# With CUDA support (Linux)
52+
cmake -B build -DGGML_CUDA=ON
53+
cmake --build build --config Release
54+
55+
# With Metal support (macOS)
56+
cmake -B build -DLLAMA_METAL=ON
57+
cmake --build build --config Release
58+
59+
# With model-download support (libcurl)
60+
cmake -B build -DLLAMA_CURL=ON
61+
cmake --build build --config Release
62+
```
63+
64+
Built libraries are placed under `src/main/resources/net/ladenthin/llama/{OS}/{ARCH}/`.
65+
66+
### C++ Unit Tests (no JVM or model file required)
67+
68+
```bash
69+
cmake -B build -DBUILD_TESTING=ON
70+
cmake --build build --config Release -j$(nproc)
71+
ctest --test-dir build --output-on-failure
72+
```
73+
74+
### Code Formatting
75+
76+
```bash
77+
# Format C++ source files
78+
clang-format -i src/main/cpp/*.cpp src/main/cpp/*.hpp
79+
```
80+
81+
---
82+
83+
## Filing Issues
84+
85+
Please use the GitHub issue tracker:
86+
87+
- **Bug reports, feature requests, questions:** https://github.com/bernardladenthin/java-llama.cpp/issues
88+
89+
Before opening an issue, search existing issues to avoid duplicates. When reporting a bug, include:
90+
91+
- Operating system and architecture
92+
- Java version (`java -version`)
93+
- llama.cpp build tag the library was compiled against
94+
- A minimal reproduction case (model name, parameters, code snippet)
95+
- Full stack trace or error output
96+
97+
---
98+
99+
## Pull Request Workflow
100+
101+
1. **Fork** the repository on GitHub.
102+
2. Create a **feature branch** from `main`:
103+
```bash
104+
git checkout main
105+
git pull origin main
106+
git checkout -b feat/my-feature
107+
```
108+
3. Make your changes, including tests (see [Test Policy](#test-policy)).
109+
4. Push the branch to your fork and open a **Pull Request** against `bernardladenthin/java-llama.cpp:main`.
110+
5. Describe what the PR changes and why; link any related issue (`Closes #NNN`).
111+
6. Respond to review comments and push follow-up commits to the same branch.
112+
7. A maintainer will merge once the PR is approved and CI is green.
113+
114+
---
115+
116+
## Coding Standards
117+
118+
- 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.
119+
- Java code targets Java 11+.
120+
- C++ code must be compatible with C++17 and compile cleanly with the project's CMake configuration.
121+
- Format C++ files with `clang-format` before committing (see command above).
122+
- Use HTML entities in Javadoc for operators and symbols outside ASCII (see CLAUDE.md for the full table).
123+
124+
---
125+
126+
## Test Policy
127+
128+
> 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.
129+
130+
- **Java tests** live in `src/test/java/net/ladenthin/llama/` and `src/test/java/examples/`.
131+
- **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`.
132+
- Tests must pass locally before opening a PR. CI also runs them automatically on push and on pull requests.
133+
134+
---
135+
136+
## Communication Channels
137+
138+
- **GitHub Issues** — bug reports and feature requests: https://github.com/bernardladenthin/java-llama.cpp/issues
139+
- **GitHub Discussions** — general questions and ideas (if enabled on the repository).
140+
141+
---
142+
143+
## License of Contributions
144+
145+
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)).

‎SECURITY.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
Only the most recent release of the `5.x` series receives security fixes. Older major versions are not actively maintained.
6+
7+
| Version | Supported |
8+
|---------|-----------|
9+
| 5.x (latest) | Yes |
10+
| < 5.0 | No |
11+
12+
## Reporting a Vulnerability
13+
14+
**Please do not report security vulnerabilities through public GitHub issues.**
15+
16+
### Primary channel — GitHub Private Vulnerability Reporting
17+
18+
Use GitHub's built-in private vulnerability reporting:
19+
20+
https://github.com/bernardladenthin/java-llama.cpp/security/advisories/new
21+
22+
This channel is private and visible only to maintainers. It is the preferred method.
23+
24+
### Secondary channel — maintainer email
25+
26+
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.
27+
28+
## Response SLA
29+
30+
We aim to acknowledge vulnerability reports within 14 days of receipt and to provide a remediation timeline within 30 days.
31+
32+
## Disclosure Policy
33+
34+
We follow **coordinated disclosure**:
35+
36+
1. Reporter submits the vulnerability privately.
37+
2. Maintainers confirm and assess severity.
38+
3. A fix is developed and a release date is agreed with the reporter.
39+
4. The fix is released and a GitHub Security Advisory is published simultaneously.
40+
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).
41+
42+
We ask reporters to keep vulnerability details **under embargo** until a fix has been released.

0 commit comments

Comments
 (0)