From 829194d993fa107c9ed518580685afb5ca44beca Mon Sep 17 00:00:00 2001 From: Vincent Favre-Nicolin Date: Tue, 28 Jul 2026 13:03:51 +0200 Subject: [PATCH 1/3] docs: add AGENTS.md with contribution guidelines for AI agents Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..605dced --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,79 @@ +# AGENTS.md — Guidelines for AI agents working on pyobjcryst + +## Repository overview + +`pyobjcryst` is a Python binding (via Boost.Python) of the ObjCryst++ C++ +library. It is built and maintained with +[scikit-package](https://scikit-package.github.io/scikit-package/), which +provides the release scripts, CI workflows, and changelog tooling used here. + +The C++ bindings live under `src/extensions/`; pure-Python wrappers and +utilities are in `src/pyobjcryst/`. Tests live in `tests/`. + +## Dependency chain + +``` +vincefn/objcryst ← real upstream (C++ library, GUI, Fox) + ↓ +diffpy/libobjcryst ← repackages ObjCryst++ as a shared library for conda/pip + ↓ +diffpy/pyobjcryst ← Python bindings (this repo) +``` + +**Any C++ feature or fix must flow through the full chain before it can land +here:** + +1. Implement or fix it in [vincefn/objcryst](https://github.com/vincefn/objcryst). +2. Pick it up in [diffpy/libobjcryst](https://github.com/diffpy/libobjcryst) + (libobjcryst is a convenience repackaging — updating the vendored sources + and cutting a release is usually all that is needed). +3. Only then expose or rely on it in pyobjcryst. + +If a PR here is blocked on an upstream change, note the upstream issue/PR in +the description and news item. + +## Branching and commits + +- Always branch from `main`. +- Use [Conventional Commits](https://www.conventionalcommits.org/) prefixes: + `fix:`, `feat:`, `docs:`, `refactor:`, `test:`, `chore:`, etc. +- Keep commits focused and atomic. +- Make sure `git config user.email` is a verified address on the author's + GitHub account so commits are attributed correctly. + +## Before opening a PR + +1. **News item** — every PR that changes user-visible behaviour must add a + file `news/.rst` following `news/TEMPLATE.rst` (sections: + `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`; leave + unused sections as `* `). + The `check-news-item` CI job (provided by scikit-package release scripts) + enforces this. +2. **Do not edit `CHANGELOG.rst` directly** — it is auto-generated from the + `news/` items at release time by the scikit-package tooling. +3. Run the test suite locally before pushing if possible: `pytest tests/` + +## CI checks on PRs + +| Workflow | Trigger | What it does | +|---|---|---| +| `tests-on-pr` | every PR | Builds the C extension and runs the full test suite | +| `check-news-item` | every PR | Verifies a `news/.rst` file exists | + +Both workflows are provided by `scikit-package/release-scripts`. + +## Merge policy — human review required + +**PRs must never be auto-merged.** Every PR requires at least one human +review and approval before merging, regardless of CI status. +Do not use `gh pr merge --auto` or any equivalent automated merge on this +repository. + +## What agents should NOT do + +- Do not force-push to `main`. +- Do not bypass CI or skip the news-item requirement. +- Do not merge PRs autonomously — always leave them open for human review. +- Do not commit secrets, credentials, or large binary files. +- Do not expose a new C++ feature in pyobjcryst before it is available in a + released version of diffpy/libobjcryst. From 60dd236ea4d040890766cb32921b0a6649bf6795 Mon Sep 17 00:00:00 2001 From: Vincent Favre-Nicolin Date: Tue, 28 Jul 2026 13:04:15 +0200 Subject: [PATCH 2/3] news: add item for PR #91 (AGENTS.md) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- news/91.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 news/91.rst diff --git a/news/91.rst b/news/91.rst new file mode 100644 index 0000000..5ef0d3c --- /dev/null +++ b/news/91.rst @@ -0,0 +1,25 @@ +**Added:** + +* Add ``AGENTS.md`` documenting contribution guidelines for AI coding agents + (dependency chain, commit conventions, news-item policy, human-review + requirement). + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* From 08b2202b4380e1196d057eb2b0aed922e287f73b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 28 Jul 2026 11:04:20 +0000 Subject: [PATCH 3/3] [pre-commit.ci] auto fixes from pre-commit hooks --- AGENTS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 605dced..16dd3d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,10 +55,10 @@ the description and news item. ## CI checks on PRs -| Workflow | Trigger | What it does | -|---|---|---| -| `tests-on-pr` | every PR | Builds the C extension and runs the full test suite | -| `check-news-item` | every PR | Verifies a `news/.rst` file exists | +| Workflow | Trigger | What it does | +| ----------------- | -------- | --------------------------------------------------- | +| `tests-on-pr` | every PR | Builds the C extension and runs the full test suite | +| `check-news-item` | every PR | Verifies a `news/.rst` file exists | Both workflows are provided by `scikit-package/release-scripts`.