## Summary Document how contribution work is attributed to people within the AI Marketing Initiative and its issues on drupalcode.org — how credit flows, where it is recorded, and what contributors need to do (or not do) to ensure accurate attribution. **Then make that workflow agent-invokable**: an AI assistant should be able to prepare or submit attributions for a single ticket or an entire milestone on request, and quickly report which tickets in a set likely already have credit recorded. drupalcode.org posts a **"Attribute your contribution"** link in every issue via the auto-generated `drupalbot` "Issue tools" comment. The link follows the pattern `https://new.drupal.org/contribution-record?source_link=<ISSUE_URL>` and is a **self-service** credit entry point. Today the workflow is fully manual. This ticket turns it into (a) a documented per-task procedure and (b) a semi-automated agent workflow. ## Acceptance Criteria ### Documentation — the human workflow - [x] Add a top-level `CONTRIBUTING.md` to this repo with: - A clear, short step-by-step **"end of task" procedure** (under-a-minute checklist) for self-attribution. - The contributor-vs-maintainer **split of responsibility** note (contributor self-attributes; maintainer takes no per-issue credit action). - The **"attributions can be edited later"** note via the same link. - [x] Link `CONTRIBUTING.md` from `README.md` so the file is discoverable from the repo landing page in addition to GitLab's automatic surfacing on new-MR / new-issue forms. ### Agent / CLI tooling — semi-automated workflow The same workflow should be invocable via an AI agent so contributors can ask *"credit this ticket"* or *"credit this milestone"* instead of clicking through the form every time. - [x] **Per-issue credit-prep**: given an issue URL, an agent produces - the `https://new.drupal.org/contribution-record?source_link=<ISSUE_URL>` URL to open, and - a **ranked list of likely contributors** (by commits / MR participation / substantive comments) with their drupal.org usernames, so the user can paste names into the form quickly. *Implemented in `skills/contribution-credit/SKILL.md` ("Per-issue: what to credit"); exercised by Tests A & B.* - [x] **Milestone-wide credit-prep**: given a milestone URL (e.g. `https://git.drupalcode.org/project/ai_initiative/-/milestones/1`), the agent produces the same per-issue output for every issue in the milestone, batched. *Implemented in `skills/contribution-credit/SKILL.md` ("Milestone-wide: who needs crediting?"); reporting format and "default scope = recent past + current, max 2" rule codified there. Exercised against Sprint 1 + Sprint 2 on 2026-05-04.* - [x] **Completion detection**: the agent can quickly report which issues in a given set (single ticket, list of tickets, or whole milestone) likely **already have credit recorded** vs. still pending. Mechanism: `field_credit_this_contributor` on each contributor paragraph (`true` = credited, `false` = candidate). Documented in skill's "Completion detection signal", along with the JSON:API cache-lag gotcha and the `System Message` pseudo-contributor that must be filtered out. - ~~**Fully automated submission (stretch)**: if drupal.org exposes a write API for contribution records, allow the agent to submit attributions directly, with explicit per-call user confirmation.~~ — **Cannot do**: drupal.org does not expose a write API for contribution records (verified 2026-05-04). The fallback in the original criterion applies — the limitation is documented in `skills/contribution-credit/SKILL.md` ("Why no full automation (yet)"). Re-open if a write API appears later. ### Concrete first tests Two closed Sprint 1 tickets exercise the two distinct paths the agent must handle. State below verified against `new.drupal.org` JSON:API on 2026-04-30. #### Test A — non-detected contributor: [#3586381](https://git.drupalcode.org/project/ai_initiative/-/work_items/3586381) > *"Complete the migration of AI Marketing Initiative Users from Drupal.org issues to Drupalcode Gitlab issues"* Current state: - ✓ `jjchinquist` is already credited (org: drunomics). - Kristen Pol (drupal.org username **`kristen pol`**, git username `kepol`) helped on this ticket but is **not auto-detected** by the contribution-record system because her contribution was outside drupalcode.org commits / MRs / comments. Given the instruction *"credit Kristen Pol on #3586381"*, the agent should: - [x] Resolve "Kristen Pol" → drupal.org user via the public JSON:API (`filter[name]=kristen pol`) and confirm the matched account back to the human before any write. - [x] **Semi-automated**: produce the `https://new.drupal.org/contribution-record?source_link=…` URL pointing at #3586381 with explicit instructions ("search for `kristen pol`, tick the credit box, save"). - ~~**Fully automated** (if/when a write surface becomes usable): submit the credit directly with explicit per-call user confirmation.~~ — **Cannot do**: see main acceptance criterion above. - [x] After the write, the agent re-queries the JSON:API and confirms `kristen pol` now has `field_credit_this_contributor: true` on this record. This test exercises the gaps the simpler flow does not: name → username resolution, adding a non-detected contributor, and post-hoc verification. #### Test B — auto-detected commenters not yet credited: [#3581782](https://git.drupalcode.org/project/ai_initiative/-/work_items/3581782) > *"Create templates for management of AI Initiative Marketing Issues on Gitlab"* Current state — four candidates already detected by drupal.org from issue activity, **none credited yet**: | User (drupal.org) | git username | Org options on record | |---|---|---| | `jjchinquist` | `jjchinquist` | drunomics, Drupal Austria | | `kristen pol` | `kepol` | Itty Bitty Byte, Salsa Digital | | `pritam-osl` | `pritamprasun` | OpenSense Labs, DrupalFit | | `dunx` | `dunx` | Zoocha | Given the instruction *"credit everyone who participated on #3581782"*, the agent should: - [x] Pull the contributor list directly from the JSON:API (no name-resolution step needed — they are auto-detected). - [x] Surface each candidate with their org options for context. Org choice itself stays with the human at click time — see the "Org selection stays with the human" note in `CONTRIBUTING.md`. The agent does not pre-collect org preferences for multi-org contributors. - [x] Produce the credit-form URL with instructions to tick all four boxes. - ~~**Fully automated** (if/when a write surface becomes usable): submit the four credits with one explicit confirmation.~~ — **Cannot do**: see main acceptance criterion above. - [x] Verify post-hoc that all four contributors now have `field_credit_this_contributor: true`. *Verified 2026-05-04.* This test exercises the bulk-credit path on a single ticket. The original "multi-org disambiguation" step turned out to be unnecessary in the semi-automated flow — since the human clicks Save anyway, the per-row org dropdown is the natural disambiguation point. #### Test C — agent guides a full milestone walk-through: AI Marketing Initiative Sprint 1 > The end-user-facing combination of Milestone-wide credit-prep, Completion detection, and the per-issue Test-B flow into a single *"credit this whole sprint"* experience. Given the instruction *"walk me through crediting Sprint 1"*, the agent should: - [x] Produce the milestone audit grouped by ✓ / ◐ / ✗ / — using the format codified in `skills/contribution-credit/SKILL.md` ("Reporting format"). Exercised on Sprint 1 on 2026-05-04: 5 fully credited, 6 partially credited, 8 with no credit, 0 with no record. - [x] For each issue in **Partially credited** and **No credit yet**, fall back to the per-issue Test-B flow: surface the credit-form URL plus candidate list with org options for context, while the human ticks the right boxes and Saves on the form. - [x] After each save, verify post-hoc using the direct-UUID JSON:API path with `Cache-Control: no-cache` (per the cache-lag note) and report which contributor paragraphs flipped to `field_credit_this_contributor: true`. Mechanism reused from Test B. - [x] At the end, re-run the milestone audit and report the new ✓ / ◐ / ✗ / — bucket sizes so the human sees the delta. This test passes by composition: the milestone-audit primitive is exercised by the audit run above, and the per-issue iteration is exercised by Test B. Test C records that combining them into a single guided walk-through is the intended end-user workflow. ## Notes - First-draft scope. The agent/CLI portions may split into follow-up issues once the drupal.org-side API surface is known — prefer landing the documentation + initial research notes in one MR and spinning off implementation tickets as findings dictate. - Out of scope: issue-fork / MR-level authorship on drupalcode.org — that is a GitLab-native credit surface, distinct from the drupal.org contribution-record flow this ticket is about. > Split out of [#3582480](https://git.drupalcode.org/project/ai_initiative/-/work_items/3582480) as a focused attribution/credit concern. --- *Drafted with the assistance of AI (Claude Code / Opus 4.7).*