diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b7fc732 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,134 @@ +# AGENTS.md + +This file provides guidance to AI coding agents working in the Fedora Mindshare Committee tickets repository. +It establishes boundaries, workflows, and expectations for AI-assisted contributions to this project. + +> **This is a living document.** +> The Fedora Mindshare Committee is actively discussing what AI governance should look like for our community. +> This file is a starting point for that conversation, not a final policy. + + +## Fedora AI-Assisted Contributions Policy + +All AI-assisted contributions to this repository must comply with the [Fedora AI-Assisted Contributions Policy](https://docs.fedoraproject.org/en-US/council/policy/ai-contribution-policy/). +Key requirements: + +- **Accountability:** The human contributor is always the author and is fully accountable for every contribution. + AI assistance does not transfer ownership or responsibility. +- **Transparency:** Disclose AI tool usage when a significant part of the contribution is generated by a tool without changes. +- **Disclosure:** For git-tracked work, use the `Assisted-by:` commit message trailer. + For content posted via the Forgejo API (issue comments, PR descriptions), append a disclosure line at the end of the body. +- **Human judgment:** AI must not be used as the sole or final arbiter for substantive or subjective judgments on contributions, nor for evaluating a person's community standing. + + +## Repository overview + +This repository (`mindshare/tickets`) is the issue tracker and project management tool for the Fedora Mindshare Committee. +It is hosted on [Fedora Forge](https://forge.fedoraproject.org/mindshare/tickets) (Forgejo). +Issues here track event funding requests, swag requests, governance decisions, and committee process work. + +The companion documentation repository is [`mindshare/docs`](https://forge.fedoraproject.org/mindshare/docs). + + +## Forgejo API + +The Forgejo REST API base URL is `https://forge.fedoraproject.org/api/v1/`. + +- **Authentication:** Use `Authorization: token ` header format, not `Bearer`. +- **Pagination:** `page` (1-based) and `limit` (max 50, default 30). +- **Content-Type:** Always include `Content-Type: application/json` for POST/PATCH requests. +- **Markdown rendering:** Forgejo renders each newline as a visible `
`. + Write each paragraph as a single continuous line. + Do not use sentence-per-line formatting in API-posted content. + + +## Issue templates + +Issue templates are defined in `.forgejo/issue_template/` as YAML form templates: + +| Template | Purpose | +|----------|---------| +| `small-events.yml` | Small Events (up to $150 USD) | +| `medium-large-events.yml` | Medium and Large Events | +| `release-party.yml` | Release parties | +| `swag-only.yml` | Swag-only requests (no budget) | +| `limesurvey.yml` | LimeSurvey instance requests | + +When creating issues programmatically, use the web URL format: +`https://forge.fedoraproject.org/mindshare/tickets/issues/new?template=.forgejo%2fissue_template%2f.yml` + + +## Label schema + +Labels are defined at the organization level (`mindshare` org) and inherited by all repositories. +Labels sharing a prefix are exclusive (only one per group). + +| Prefix | Purpose | Example | +|--------|---------|---------| +| `charter/` | Charter area of focus | `charter/events`, `charter/recognition`, `charter/ambassadorship` | +| `needs/` | What the issue is waiting on | `needs/vote`, `needs/event report`, `needs/reporter feedback` | +| `scope/` | Nature of the request | `scope/new`, `scope/improvement`, `scope/bug` | +| `state/` | Current status | `state/approved`, `state/blocked`, `state/wontfix` | +| `team/` | Relevant Fedora team | `team/mindshare`, `team/ambassadors`, `team/marketing` | +| _(none)_ | Non-exclusive | `good first issue`, `help wanted` | + +Use numeric label IDs (not names) when adding labels via the API. +Refer to the [Issue & PR Labels](https://docs.fedoraproject.org/en-US/mindshare-committee/procedures/labels/) documentation for the full schema. + + +## Decision-making process + +The Fedora Mindshare Committee makes decisions in two ways: + +- **Lazy approval:** Silence within 3–7 days equals consent. + Used for decisions with short-term effects that can be easily reversed. +- **Full consensus:** Requires +3 votes and no -1 vetoes. + Used for important decisions like event funding approval. + +Only committee members' votes count in final decisions. +AI agents must never cast votes, express approval or disapproval of proposals, or otherwise participate in governance decisions. + + +## Rules for AI agents + +### Do + +- **Read issues and comments** to understand context before acting. +- **Draft content for human review** before any write operation. +- **Disclose AI involvement** in every piece of content posted. +- **Use issue templates** when creating issues programmatically. +- **Apply labels consistently** according to the label schema. +- **Respect the committee's decision-making process** by providing information, not opinions on governance matters. +- **Cite sources** when referencing Fedora documentation, policies, or prior decisions. + +### Do not + +- **Do not post comments, create issues, or modify labels** without explicit human approval. + Every write operation to the Forgejo API requires a human in the loop. +- **Do not cast votes or express opinions** on funding proposals, governance decisions, or contributor standing. +- **Do not disclose confidential information.** Some issues are marked confidential. + Treat confidential context as private and never surface it in public comments or other issues. +- **Do not impersonate committee members.** Content posted via a member's API token must be written in first-person voice and clearly reflect the member's intent. +- **Do not make budget commitments.** Only the committee can approve funding. +- **Do not close or reopen issues** without explicit human instruction. +- **Do not edit or delete other people's comments.** +- **Do not use grandiose or performative language** ("fantastic idea", "amazing work"). + Use a concise, governance-appropriate tone. + + +## Commit conventions + +Subject line format: ` : ` + +- Use actual Unicode emoji characters from [gitmoji](https://gitmoji.dev/), not text shortcodes. +- Component scope names the area of the project affected (e.g., `templates`, `ci`, `docs`). +- Body: Explain the reasoning and "why" behind the change. +- Trailer: `Assisted-by: ()` per Fedora policy. +- Flags: `--signoff` is always required; `--gpg-sign` is encouraged. + + +## Communication channels + +- **Discourse:** [discussion.fedoraproject.org/tags/c/project/7/mindshare/292](https://discussion.fedoraproject.org/tags/c/project/7/mindshare/292) +- **Matrix:** [#mindshare:fedoraproject.org](https://matrix.to/#/#mindshare:fedoraproject.org) +- **Documentation:** [docs.fedoraproject.org/en-US/mindshare-committee/](https://docs.fedoraproject.org/en-US/mindshare-committee/)