[M] Change in asterixdb[trinity]: [NO ISSUE][MISC] += CLAUDE.md

[AsterixDB Code Review <do...@asterix-gerrit.ics.uci.edu>]

From Michael Blow <mb...@apache.org>:

Michael Blow has uploaded this change for review. ( https://asterix-gerrit.ics.uci.edu/c/asterixdb/+/21575?usp=email )


Change subject: [NO ISSUE][MISC] += CLAUDE.md
......................................................................

[NO ISSUE][MISC] += CLAUDE.md

Ported from master, which is the only branch that carried it, so the
"See asterixdb/CLAUDE.md" pointer in the cbas-core CLAUDE.md no longer
dangles here. Corrected for this branch: the agent/tool guidance was
self-contradictory about CLAUDE_CODE_UI vs CLAUDE_CODE_CLI, and the
cited in-tree examples (S3Utils, S3TrustManagerProvider) are either
unannotated or absent on trinity.

Adds a Commit Messages section for the Co-Authored-By trailer, covering
the two ways its footer gets split and a fresh Change-Id minted -- a
blank line before Change-Id, and ending the message with the (cherry
picked from ...) line of a backport.

Ext-ref: MB-68099

Co-Authored-By: Claude Opus 5 <no...@anthropic.com>
Change-Id: I8f0e6aa72fee0cbb695aa1aabd0eeadd39ce7d33
---
A CLAUDE.md
1 file changed, 166 insertions(+), 0 deletions(-)



  git pull ssh://asterix-gerrit.ics.uci.edu:29418/asterixdb refs/changes/75/21575/1

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..596435c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,166 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements.  See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership.  The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License.  You may obtain a copy of the License at
+ !
+ !   http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied.  See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+# AsterixDB
+
+Apache AsterixDB — the BDMS query engine, storage layer, and Hyracks distributed runtime. See
+`README.md` for an overview.
+
+The tree has two roots:
+- `asterixdb/` — the AsterixDB engine (SQL++ compiler, external data, storage).
+- `hyracks-fullstack/` — the Hyracks runtime and shared utilities (`hyracks-util` etc.).
+
+Files here carry the **Apache license header** (see `README.md`). Preserve it when editing or
+creating files.
+
+This branch is `trinity`, consumed by the Couchbase Server analytics service; the surrounding
+Couchbase conventions (topics across two Gerrit servers, landing order, the `refresh-asterixdb-fork`
+step) live in `../CLAUDE.md`, which is **not** auto-loaded from this directory — read it before
+coordinating a change with `cbas-core`.
+
+## Code Review
+
+Changes go through **Gerrit** (`asterix-gerrit.ics.uci.edu`), not GitHub pull requests. The `gerrit`
+remote points at `ssh://<user>@asterix-gerrit.ics.uci.edu:29418/asterixdb`. If it is missing:
+
+```bash
+git remote add gerrit ssh://<user>@asterix-gerrit.ics.uci.edu:29418/asterixdb
+```
+
+Push a change (or a new patchset) for review:
+
+```bash
+git push gerrit HEAD:refs/for/trinity
+```
+
+Subject convention is `[NO ISSUE][COMP]` (or `[ASTERIXDB-nnnn][COMP]`) with the MB in an `Ext-ref:`
+footer. A backport carries an extra `[BP]` tag — `[ASTERIXDB-3765][COMP][BP] ...` — reuses the
+original commit's `Change-Id`, and keeps a `(cherry picked from commit <sha>)` line. Gerrit warns on
+subjects over **72** characters here (`cbas-core` warns at 50). Documentation-only and tooling
+changes go under `Ext-ref: MB-68099`.
+
+### Topics: at most one open change per project per topic
+
+A topic (`-o topic=<topic>`) groups the changes of one coordinated change spanning several
+repositories. **The tooling that applies a topic across projects fails when a project has more than
+one open change carrying the same topic.** So when the work in *this* repo is a stack of several
+commits, do not put the shared topic on every commit. Instead:
+
+- Put the topic only on the **leaf** (final) commit of the stack, and leave the preparatory commits
+  topic-less; or
+- If the stack contains discrete sets of cross-project changes that can be submitted independently,
+  give each set its **own intermediate topic**.
+
+Unrelated follow-up work (e.g. a docs tweak noticed along the way) should be pushed as its own
+change with **no topic**, or a different one — not added to the coordinated change's topic.
+
+## Commit Messages
+
+**Every commit message must end with the trailer:**
+
+```
+Co-Authored-By: Claude Opus 5 <no...@anthropic.com>
+```
+
+(naming whichever model actually did the work). This has repeatedly been missed and caught only
+after the change was pushed for review, which costs a message-only patchset.
+
+**Write it at commit time, not as a follow-up amend.** The footer must be one contiguous run of
+trailers, with the `Co-Authored-By` line adjacent to `Change-Id`:
+
+```
+<body>
+                                                        <- exactly one blank line
+Ext-ref: MB-nnnnn
+
+Co-Authored-By: Claude Opus 5 <no...@anthropic.com>
+Change-Id: I...
+```
+
+Two ways the footer gets destroyed, both of which make the `commit-msg` hook mint a **second**
+`Change-Id` and silently orphan the change:
+
+- **A blank line between `Change-Id:` and `Co-Authored-By:`** splits the footer, so the last
+  paragraph is read as body text.
+- **Ending the message with a non-trailer line** — most often
+  `(cherry picked from commit <sha>)` on a backport. Put that line in its own paragraph *above* the
+  trailer block so the message still ends with a trailer.
+
+If the trailer must be added after the fact, rebuild the whole message rather than appending a line:
+capture the `Change-Id` first, strip every `Change-Id:`/`Co-Authored-By:` line, then re-append both
+contiguously. Verify before pushing — this must print exactly `1`, matching the original:
+
+```bash
+git log -1 --format=%B | grep -c '^Change-Id:'
+```
+
+## AI Provenance Annotation
+
+**When you (an AI agent) generate or assist with Java code in this tree, annotate it with
+`@AiProvenance`.** This records which model and tool produced the code so the contribution is
+auditable. The annotation is defined *here*, in this repository.
+
+- **Annotation**: `org.apache.hyracks.util.annotations.AiProvenance` — source at
+  `hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/annotations/AiProvenance.java`.
+  It is on the classpath of every module that depends on `hyracks-util` (effectively all of them).
+- **`@Retention(SOURCE)`** — documentation only; stripped at compile time, so no runtime or bytecode
+  cost. The repeatable container `@AiProvenances` is `RUNTIME`-retained for tools that scan class
+  files.
+- **Applies to**: types, methods, constructors, fields, and local variables.
+
+### Attributes
+
+| Attribute | Required | Values |
+|-----------|----------|--------|
+| `agent` | yes | `AiProvenance.Agent` — the model that did the work (e.g. `CLAUDE_OPUS_5`, `CLAUDE_SONNET_4_6`) |
+| `tool` | yes | `AiProvenance.Tool` — the invocation surface (e.g. `CLAUDE_CODE_CLI`, `CLAUDE_CODE_UI`, `GITHUB_COPILOT`) |
+| `contributionKind` | no (default `GENERATED`) | `GENERATED`, `ASSISTED`, `REFACTORED`, `TEST_GENERATED`, `DOC_GENERATED` |
+| `notes` | no | free-text, e.g. what changed or why |
+
+### How to inject it
+
+1. **Pick the narrowest element** that captures the AI contribution: annotate the **type** only when
+   the **whole class** is AI-authored. When AI adds or rewrites individual **methods** (or a
+   **field**/**constructor**) within an otherwise human-authored class, annotate each of those
+   **methods** — do **not** promote the annotation to the type level.
+2. **Match `agent` to the model actually used**, and `tool` to the surface: the `claude` CLI and the
+   Claude Code desktop/IDE integrations are `CLAUDE_CODE_CLI`; the Code tab in the Claude web app is
+   `CLAUDE_CODE_UI`; Copilot-in-IDE is `GITHUB_COPILOT`.
+3. **Choose `contributionKind`** honestly: `GENERATED` (from scratch), `ASSISTED` (human-led,
+   AI-suggested), `REFACTORED` (rewriting existing code), `TEST_GENERATED`, `DOC_GENERATED`.
+4. **Stack annotations** (it is `@Repeatable`) to record history — e.g. generated by one model then
+   refactored by another.
+5. **Import style**: either static-import the constants for brevity, or import the type and qualify
+   (`AiProvenance.Agent.X`). Both are used in-tree.
+
+If a model you used is missing from the `Agent`/`Tool`/`Provider` enums, **add it to
+`AiProvenance.java`** rather than falling back to `OTHER`.
+
+### Example
+
+In-tree usages on this branch include `hyracks-fullstack/hyracks/hyracks-util/.../Span.java`
+(type-level, `REFACTORED`), `hyracks-fullstack/hyracks/hyracks-util/.../SpanTest.java`, and
+`asterixdb/asterix-external-data/.../evaluators/StringJsonParseEval.java`.
+
+```java
+import org.apache.hyracks.util.annotations.AiProvenance;
+
+@AiProvenance(agent = AiProvenance.Agent.CLAUDE_OPUS_5, tool = AiProvenance.Tool.CLAUDE_CODE_CLI,
+        contributionKind = AiProvenance.ContributionKind.GENERATED, notes = "Initial implementation")
+public final class ExampleHelper { ... }
+```

-- 
To view, visit https://asterix-gerrit.ics.uci.edu/c/asterixdb/+/21575?usp=email
To unsubscribe, or for help writing mail filters, visit https://asterix-gerrit.ics.uci.edu/settings?usp=email

Gerrit-MessageType: newchange
Gerrit-Project: asterixdb
Gerrit-Branch: trinity
Gerrit-Change-Id: I8f0e6aa72fee0cbb695aa1aabd0eeadd39ce7d33
Gerrit-Change-Number: 21575
Gerrit-PatchSet: 1
Gerrit-Owner: Michael Blow <mb...@apache.org>