You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sourcelume.apache.org by an...@apache.org on 2026/09/07 18:33:56 UTC

(sourcelume-spec) 01/01: Add AGENTS.md with cross-harness conventions and AI commit-message rule

This is an automated email from the ASF dual-hosted git repository.

ANierbeck pushed a commit to branch add-agents-md
in repository https://gitbox.apache.org/repos/asf/sourcelume-spec.git

commit b15257bd10a08c72ee0e874419eb28b07af81c23
Author: anierbeck <ac...@codecentric.de>
AuthorDate: Mon Sep 7 20:33:46 2026 +0200

    Add AGENTS.md with cross-harness conventions and AI commit-message rule
    
    Central place for any coding agent (Claude Code, Cursor, Copilot,
    Junie, Codex, pi, etc.) to find this repo's conventions: Python/uv for
    validation vs Java/Maven for packaging, the versioning and immutability
    rules, the vocabulary-reuse policy, and the PR/dual-hosting notes.
    
    Most important section is the commit-message + AI attribution rule,
    so every harness produces commits that match the existing in-repo
    practice (Apache-ai: Yes / Generated-by: <tool> (<model>) / Reviewed-by:
    <human>) and the ASF rai.apache.org guidance, and knows when to use
    Generated-by vs Assisted-by.
    
    Apache-ai: Yes
    Generated-by: Claude Code (Sonnet 5)
    Reviewed-by: anierbeck
---
 AGENTS.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e68eaae
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,137 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and the humans running them) working in
+this repository. This is the place to record conventions any harness —
+Claude Code, Cursor, Copilot, Junie, Codex, a local `pi` setup, whatever
+comes next — is expected to follow here. When in doubt, follow the
+Apache Sourcelume project conventions over any default the harness
+suggests.
+
+## Project overview
+
+This repository, `apache/sourcelume-spec`, holds the **Apache Sourcelume**
+provenance metadata specification: the JSON-LD `@context`, the JSON Schema
+and SHACL shapes, the normative prose, and the tooling that validates
+examples against them. Sourcelume is about AI training-data
+**provenance and licensing** — signed, independently verifiable records of
+where a dataset came from and what terms it carries — not about training
+models on known data.
+
+This repo is early-stage. The `0.0.1` version directories are scaffolding
+that is being filled in; do not assume structure described in `README.md`
+already exists on disk (the README's tree is partly aspirational). Verify
+against the actual tree before referencing paths.
+
+## Build and test commands
+
+Tooling is split by language, on purpose:
+
+- **Python (via `uv`) owns spec validation and repo tooling.**
+  - `uv sync --extra dev` — install dev dependencies (`jsonschema[format]`,
+    `pyld`, `rdflib`, `pyshacl`).
+  - `uv run python tools/validate.py` — validate every `examples/*.jsonld`
+    against the corresponding version's schema (jsonschema 2020-12, with
+    format assertions enforced) and SHACL shapes (pyshacl). This is the
+    real gate: it does not just parse JSON.
+  - `uv run python -m unittest discover -s tests` — run the validator's
+    own unit tests.
+- **Java/Maven owns packaging** of the `context/` and `schema/` resources
+  into a JAR for JVM consumers (e.g. the Sourcelume Registry) and runs RAT
+  license-header enforcement.
+  - `mvn -B verify` — build the artifact and run RAT checks.
+
+Run both before opening or updating a PR. A green `validate.py` plus a
+green `mvn -B verify` is the local bar.
+
+## Versioning and immutability
+
+`context/`, `schema/`, and `spec/` describe one interlocking data model and
+share a single version number. See `VERSIONING.md` for the full rules; the
+short version an agent must internalize:
+
+- Version directories use the **bare semver** string (`0.0.1`, not `v0.0.1`),
+  uniformly under `context/`, `schema/`, and `spec/`.
+- **Released version directories are immutable.** Once a version is
+  tagged/released, do not edit files under that version dir — cut a new
+  version instead.
+- **Pre-1.0 versions are mutable** while unreleased. Fixable gaps in an
+  unreleased `0.0.1` get folded into `0.0.1`; they do not require a `0.0.2`
+  unless `0.0.1` has already been tagged.
+- `context/latest` is a human-browsing convenience pointer, **not** a
+  stable release target. Tooling and external references must pin an
+  exact version.
+- `spec/<version>/` holds only immutable normative prose for that version.
+  Research notes, stress tests, and other non-spec artifacts belong in a
+  non-versioned top-level directory (e.g. `notes/`), not under `spec/`.
+
+## Vocabulary reuse
+
+Reuse existing standard terms wherever an equivalent exists
+(`dct:`, `schema:`, `spdx:`) rather than inventing Sourcelume-native terms.
+The `sourcelume:` namespace stays minimal. This is a deliberate project
+decision; do not introduce a new `sourcelume:` term when an established
+one will do.
+
+## Commit messages and AI attribution
+
+This is the part every harness must get right. Apache Sourcelume follows
+the ASF generative-tooling guidance and the draft convention documented at
+<https://rai.apache.org/commit-messages.html>. The established, in-repo
+practice (see existing commits by `jgoodyear`) is a three-line trailer
+block at the end of the commit message body:
+
+```
+Apache-ai: Yes
+Generated-by: <tool> (<model>)
+Reviewed-by: <human>
+```
+
+For example:
+
+```
+Apache-ai: Yes
+Generated-by: Claude Code (Sonnet 5)
+Reviewed-by: anierbeck
+```
+
+Rules:
+
+- **`Generated-by:`** — required when an AI tool produced the code, even
+  if a human reviewed and edited it. Name the actual tool and model
+  (e.g. `Claude Code (Sonnet 5)`, `PyCharm AI Assistant (Claude 4.5 Sonnet)`,
+  `Webstorm Junie (Gemini 3 Flash)`), not a generic label.
+- **`Assisted-by:`** — use this instead of `Generated-by:` only when the
+  human wrote the code and the AI helped in small ways. They are not the
+  same action: *Generated* = AI produced, human reviewed; *Assisted* =
+  human produced, AI helped. Pick the one that matches what actually
+  happened.
+- **`Apache-ai: Yes`** — include alongside `Generated-by:` / `Assisted-by:`
+  when AI played a significant role, for policy transparency.
+- **`Reviewed-by:`** — the human who reviewed the change.
+- **`Co-authored-by:`** is for humans only, never for an AI tool.
+- The commit message is the committer's representation. Even when AI
+  generated the code, the committer is responsible for what's committed.
+
+Note: the `rai@apache.org` list is still discussing whether the single AI
+tag should be `Generated-by:` or `Assisted-by:` as the default, and whether
+the value should be `<model-id>` or `<agent-name>`. Until that settles,
+follow the in-repo practice above (full trailer block, tool + model in
+parentheses). If the project adopts a different rule on-list, update this
+section.
+
+## Pull requests
+
+- This repository is dual-hosted: authoritative history is on
+  `gitbox.apache.org`, mirrored to/from GitHub. Contribute via a GitHub
+  pull request against `main` (fork, branch, PR). `main` is treated as
+  protected; do not push directly to it.
+- Non-trivial or cross-cutting spec changes are normally discussed on the
+  dev list first (`dev@sourcelume.apache.org`,
+  [archives](https://lists.apache.org/list.html?dev@sourcelume.apache.org)),
+  not just via PR. When a discussion has happened on-list, reference it in
+  the PR description.
+- Apache License 2.0 applies; preserve `LICENSE` and `NOTICE`. RAT
+  license-header enforcement runs in `mvn verify`; non-code files
+  (`.jsonld`, `.json`, `.ttl`, `.md`) are RAT-excluded by rule, but code
+  files are not — add the ASF header to new code files.
+- Run `uv run python tools/validate.py` and `mvn -B verify` before pushing.


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@sourcelume.apache.org
For additional commands, e-mail: commits-help@sourcelume.apache.org