From 00185ae1a323506d8e551b3e550c1a9f8fce83cc Mon Sep 17 00:00:00 2001 From: abetlen Date: Sat, 23 May 2026 23:18:43 -0700 Subject: [PATCH 1/6] docs: add contributing guide --- CONTRIBUTING.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..b6f06fb06 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,74 @@ +# Contributing + +## Contribution Workflow + +Before opening a pull request, search existing issues and PRs to avoid duplicate work. +Keep each PR focused on one feature, bug fix, or vendor update. +Avoid mixing unrelated Python changes, generated binding updates, documentation edits, and `vendor/llama.cpp` changes unless they are required for the same fix. + +Describe what changed, why it changed, and how it was tested. +Link relevant issues, include any required build flags or hardware assumptions, and add a `CHANGELOG.md` entry for user-visible fixes or features (see `CHANGELOG.md` for examples). + +BREAKING CHANGES WILL ALMOST CERTAINLY BE REJECTED OR REFACTORED. + +## PR Titles and Changelog Entries + +Use PR titles in the form `: `, with an optional scope when it adds clarity: `feat: add X`, `fix(server): handle Y`, `fix(ci): repair Z`, or `chore: bump version to N`. +Prefer tags already used in the project history, such as `feat`, `fix`, `chore`, `ci`, `docs`, and `refactor`. + +Add changelog entries under `## [Unreleased]` using the same prefix style as well as the contributor and PR number + +```md +- feat(server): Add support for X by @contributor in #1234 +- fix(ci): Repair Y wheel builds by @contributor in #1234 +``` + +## Local Development + +Prerequisites: Python 3.8+, CMake 3.21+, a C/C++ compiler, and Git submodules. +From a fresh checkout of the repository, initialize submodules and create a virtual environment: + +```bash +git submodule update --init --recursive +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +make deps +make build +``` + +Run tests and lint checks before submitting changes: + +```bash +make test +make lint +``` + +Use backend-specific build targets when validating native acceleration or backend-specific fixes, for example `make build.openblas`, `make build.cuda`, `make build.metal`, or `make build.vulkan`. + +## Testing Expectations + +Add or update tests for behavior changes or fixing regressions. +The test suite uses pytest and lives under `tests/`; name files `test_*.py` and test functions `test_*`. + +For changes involving native backends, model behavior, performance, or platform compatibility, document the environment used for validation in the PR. +If a change cannot be covered by automated tests, include a short manual validation recipe instead. + +## Code Style + +Python code is formatted with Ruff using an 88-character line length. +Run `make format` to apply automatic fixes and `make lint` to check formatting and lint rules. + +Use 4-space indentation, `snake_case` for functions and variables, `PascalCase` for classes, and `UPPER_CASE` for constants. +Follow existing patterns when touching ctypes bindings or server APIs, and avoid adding dependencies unless they are necessary for the feature or fix. + +## Documentation Style + +Write Markdown with one sentence or core idea per physical line to keep diffs focused and easier to review. +Do not manually wrap lines at a fixed column width. + +## Project Layout + +The Python package lives in `llama_cpp/`, with tests in `tests/` and examples in `examples/`. +Documentation lives in `docs/` and is built with `mkdocs.yml`. +The `vendor/llama.cpp/` directory is a Git submodule containing the upstream llama.cpp sources used by the bindings. From 34990959c8edc8123215d4d9fdb9ec44a0d10fd3 Mon Sep 17 00:00:00 2001 From: abetlen <abetlen@gmail.com> Date: Sat, 23 May 2026 23:34:02 -0700 Subject: [PATCH 2/6] docs: reference contributing guide --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 69a0f8234..a785cbb03 100644 --- a/README.md +++ b/README.md @@ -743,6 +743,7 @@ If you find any issues with the documentation, please open an issue or submit a ## Development This package is under active development and I welcome any contributions. +See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow, PR title, changelog, testing, and style guidelines. To get started, clone the repository and install the package in editable / development mode: From 819f21f66aac8bd4818d6cdea769fa0d2217f814 Mon Sep 17 00:00:00 2001 From: abetlen <abetlen@gmail.com> Date: Sat, 23 May 2026 23:39:25 -0700 Subject: [PATCH 3/6] docs: update contributing guide notes --- CHANGELOG.md | 1 + CONTRIBUTING.md | 3 +++ 2 files changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 61ebc1613..fd8d14e26 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] - feat: Update llama.cpp to ggml-org/llama.cpp@c0c7e147e +- docs: Add contributing guide and link it from README.md - chore: Migrate llama.cpp submodule URL to ggml-org/llama.cpp by @shalinib-ibm in #2034 - fix: Enable unified KV cache for embedding contexts to preserve full per-sequence context in batch embedding calls by @SanjanaB123 in #2217 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b6f06fb06..e77897c4f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing +Hello human and AI contributors, this document exists to help you understand the project and set some rules for contributions. + ## Contribution Workflow Before opening a pull request, search existing issues and PRs to avoid duplicate work. @@ -66,6 +68,7 @@ Follow existing patterns when touching ctypes bindings or server APIs, and avoid Write Markdown with one sentence or core idea per physical line to keep diffs focused and easier to review. Do not manually wrap lines at a fixed column width. +Keep `README.md` focused on user-facing setup and usage; link to this guide for contribution workflow details rather than duplicating them. ## Project Layout From 52e56a89acdb0a68eb67a9c61edc59c331225163 Mon Sep 17 00:00:00 2001 From: abetlen <abetlen@gmail.com> Date: Sat, 23 May 2026 23:51:09 -0700 Subject: [PATCH 4/6] docs: follow changelog entry format --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fd8d14e26..cfec06e3f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] - feat: Update llama.cpp to ggml-org/llama.cpp@c0c7e147e -- docs: Add contributing guide and link it from README.md +- docs: Add contributing guide and link it from README.md by @abetlen in #2229 - chore: Migrate llama.cpp submodule URL to ggml-org/llama.cpp by @shalinib-ibm in #2034 - fix: Enable unified KV cache for embedding contexts to preserve full per-sequence context in batch embedding calls by @SanjanaB123 in #2217 From f64de24f3a6d6bda16cd01cc4f49bbf6555087aa Mon Sep 17 00:00:00 2001 From: abetlen <abetlen@gmail.com> Date: Sat, 23 May 2026 23:56:09 -0700 Subject: [PATCH 5/6] docs: align changelog entry with PR title --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cfec06e3f..6228d09f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] - feat: Update llama.cpp to ggml-org/llama.cpp@c0c7e147e -- docs: Add contributing guide and link it from README.md by @abetlen in #2229 +- docs: add contributing guide by @abetlen in #2229 - chore: Migrate llama.cpp submodule URL to ggml-org/llama.cpp by @shalinib-ibm in #2034 - fix: Enable unified KV cache for embedding contexts to preserve full per-sequence context in batch embedding calls by @SanjanaB123 in #2217 From 6583db1f75e2d529eea4b484b4794060516b7f6b Mon Sep 17 00:00:00 2001 From: abetlen <abetlen@gmail.com> Date: Sun, 24 May 2026 00:20:30 -0700 Subject: [PATCH 6/6] docs: clarify changelog entry format --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e77897c4f..1d8f9e398 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,11 +18,11 @@ BREAKING CHANGES WILL ALMOST CERTAINLY BE REJECTED OR REFACTORED. Use PR titles in the form `<tag>: <title>`, with an optional scope when it adds clarity: `feat: add X`, `fix(server): handle Y`, `fix(ci): repair Z`, or `chore: bump version to N`. Prefer tags already used in the project history, such as `feat`, `fix`, `chore`, `ci`, `docs`, and `refactor`. -Add changelog entries under `## [Unreleased]` using the same prefix style as well as the contributor and PR number +Add changelog entries under `## [Unreleased]` using the PR title followed by `by @contributor in #1234`. ```md -- feat(server): Add support for X by @contributor in #1234 -- fix(ci): Repair Y wheel builds by @contributor in #1234 +- feat(server): add support for X by @contributor in #1234 +- fix(ci): repair Y wheel builds by @contributor in #1234 ``` ## Local Development