flock/AGENTS.md

AGENTS.md — Flock to Fedora

This file provides guidance for AI coding agents working on this repository. It follows the AGENTS.md convention.

Project overview

This is a project management repository for Flock to Fedora, the annual contributor conference for the Fedora Project. The issue tracker on Fedora Forgejo is the primary deliverable — code artifacts (gallery pages, survey exports, scripts) are secondary.

The repository is managed by the Fedora Council and the Flock Organizing Team. Planning work spans sponsorships, speaker management, venue logistics, design, marketing, registration, travel sponsorship, and post-event follow-up.

Repository structure

README.md                                        Planning guide and reference
AGENTS.md                                        AI agent guidance (this file)
gallery/index.html                               Flock 2026 photo gallery (deployed to fedorapeople.org)
survey/2025/flock-2025-limesurvey-structure.lss   Flock 2025 post-event survey structure
survey/2026/flock-2026-limesurvey-structure.lss   Flock 2026 post-event survey structure
survey/2027/flock-2027-limesurvey-structure.lss   Flock 2027 post-event survey structure (in progress)
scripts/deploy-gallery.sh                        SCP-based gallery deployment to fedorapeople.org
LICENSE.txt                                      CC BY-SA 4.0

LimeSurvey structure files (.lss)

The .lss files under survey/ are XML exports from LimeSurvey. Never use an XML parser to read-modify-write these files — parsers reformat whitespace, reorder attributes, and strip CDATA wrapping, producing diffs that touch thousands of lines when only a few fields changed. Instead, make surgical text-level edits to the specific <row> blocks that need to change. Answer rows are interleaved across questions (sorted by answer code, not by question), so edits must target rows by their <qid> or <aid> values, not by line position. Always verify the diff before committing to ensure only the intended fields changed.

Writing conventions

When writing or editing Markdown (.md) and AsciiDoc (.adoc) files in this repository, always use the one sentence per line convention (also known as ventilated prose or semantic linefeeds). Each sentence starts on its own line. Do not wrap text at a fixed column width or break sentences across lines. This convention produces cleaner diffs, prevents paragraph reflows, and makes it easier to reorder, comment out, or review individual sentences.

In contrast, comments posted to the Forgejo issue tracker must use flowing paragraphs (see Comment authoring). Forgejo renders Markdown line breaks literally, so one-sentence-per-line in issue comments creates choppy text.

Issue tracker conventions

Issues represent planning tasks and use the Summary-Background-Details-Outcome format:

• Summary: One sentence describing the task
• Background: 2-5 sentences of context
• Details: Step-by-step checklist of what needs to be done
• Outcome: One sentence describing the expected result

Labels are split between repo-level labels and org-level labels inherited from the council organization:

• area/* labels (non-exclusive) identify the workstream: CfP & Schedule, Design & Swag, Marketing & Comms, Registration, Social Events, Speakers, Sponsors, Travel & Financial Aid, Venue & Logistics, Volunteers
• priority/* labels (exclusive) indicate urgency: critical, high, medium, low

Milestones map to planning phases and are named by date range (e.g., "May 2026: Pre-Event Prep", "2026 Post-Event").

Comments on issues use a ## Status update — <date> header. Closing comments should include a "Retrospective notes for Flock [next year]" section with lessons learned. Post individual, tailored comments on each issue — never group updates across multiple issues into one shared comment. When consolidating issues, post a brief redirect comment on each closed issue pointing to the new tracking issue. Document key information frameworks abstractly so future planners can reference the issue without needing the original external artifacts.

Forgejo API

The issue tracker is hosted on Fedora's Forgejo instance, not GitHub or GitLab.

• Base URL: https://forge.fedoraproject.org/api/v1/
• Auth: Authorization: token $FEDORA_FORGE_TOKEN
• Pagination: page and limit params (max 50 per page)
• Timeouts: Use --max-time 120 with curl — the API can be slow under load

The GitLab MCP plugin is NOT compatible with this Forgejo instance (different API version, project addressing, and terminology). Use curl with the Forgejo REST API directly. curl is strongly preferred over Python urllib.request, which can hang under load or during batch requests with this server.

Key endpoints

Endpoint	Method	Purpose
/repos/council/flock/issues	GET/POST	List or create issues
/repos/council/flock/issues/{index}	PATCH	Update issue (assignees, state, due date, body)
/repos/council/flock/issues/{index}/comments	GET/POST	List or add comments
/repos/council/flock/issues/{index}/labels	POST/DELETE	Add or remove labels
/repos/council/flock/milestones	GET	List milestones
/repos/council/flock/milestones/{id}	PATCH	Update milestone (e.g., close)
/repos/council/flock/labels	GET	List repo labels
/orgs/council/labels	GET	List org-level labels
/users/{username}	GET	Look up user info

Cross-repo issue dependencies are NOT supported via the API. Use in-comment links instead.

Forgejo Projects boards have no API endpoint (feature request Codeberg #5330). Project boards must be managed manually through the web UI.

Comment authoring

When drafting comments for the issue tracker:

• Write in first-person voice — the agent speaks as whichever user is operating it and has provided an API token
• Use flowing paragraphs, NOT one-sentence-per-line — Forgejo renders Markdown line breaks literally, so one-sentence-per-line creates choppy text
• Structural Markdown (numbered lists, bold labels, headings) is fine; only prose paragraphs need to flow continuously
• Always include the issue title alongside the number when referencing issues in conversation (e.g., "#83 — Publish event photos")
• Thank and tag contributors by their Forgejo username when closing issues
• Get explicit operator approval before posting any comment, creating issues, or closing issues

Confidentiality

• Pre-event venue capacity: Do not disclose actual venue capacity publicly before a Flock event has concluded. Communicate a lower public cap so organizers retain flexibility in allocating remaining tickets (e.g., prioritizing non-Red Hat attendees, late-breaking speakers, press). Historical capacity and registration numbers may be discussed publicly once the event has concluded.
• Never reference Red Hat internal policies (including internal travel policies) in public-facing comments unless the operator explicitly approves.
• Retrospective documents may contain confidential content — check with the operator before sharing specifics publicly.
• When in doubt about whether information is public, ask the operator.

Terminology

• OSAIPO (Open Source & AI Program Office) — the Red Hat organization that oversees Fedora, CentOS, and related community work. Never use the outdated "OSPO" (Open Source Program Office).
• Fedora Operations Architect (FOA) — currently @amoloney, who also served as co-lead organizer for Flock 2026.
• Fedora Community Architect (FCA) — transitioning from Justin Wheeler (@jflory7) to Shaun McCance (@shaunm) as the next Fedora Community Architect.
• Fedora Project Leader (FPL) — currently @jspaleta.

Git conventions

Never run git commit or git push directly. Write commit messages to a temp file and present the staging and commit commands for the operator to execute.

Commit message format: <gitmoji> <component>: <summary>

Use a gitmoji prefix, a thematic component scope, and a concise summary on the subject line. The body should explain the reasoning and context behind the change. Include an Assisted-by: trailer with the AI model name, version, and context window size. Use --signoff on all commits. Use --gpg-sign if the operator has a GPG key available — prompt them to use it, but do not require it.

Follow the 50/72 rule for Git commit messages:

• 50-character subject line: The subject line of a commit message should be no more than 50 characters long. This ensures the message is concise, easy to read, and provides a brief summary of the changes made.
• 72-character body lines: Each line in the commit body should not exceed 72 characters. This maintains readability when commit messages are viewed in terminal pagers or other tools that wrap text.

Example (from this repository)

📝 docs(AGENTS): Document 50/72 Git commit rule

Add the 50/72 rule to the Git conventions section of `AGENTS.md`. This
guideline establishes that commit subjects must not exceed 50 characters
for conciseness and clarity, while commit body lines must not exceed 72
characters to maintain readability in terminal pagers and git log views.

Assisted-by: gemini-3.8-flash (1M context)
Signed-off-by: Justin Wheeler <jwheel@redhat.com>

Key platforms

Platform	URL	Purpose
Forgejo	forge.fedoraproject.org/council/flock	Issue tracker (primary)
Pretalx	cfp.fedoraproject.org	CfP and schedule
Pretix	rsvp.fedoraproject.org	Registration and attendee emails
LimeSurvey	fedoraproject.limequery.com	Post-event feedback survey
Event website	fedoraproject.org/flock	Public-facing event page
Design tickets	forge.fedoraproject.org/design/tickets	Design team issue tracker (migrated from GitLab)
Photo gallery	jflory7.fedorapeople.org/flock-2026-gallery/	Static photo gallery

Platform URLs with year-specific slugs (such as Pretalx, Pretix, and LimeSurvey) update with each planning cycle. The 2026 URLs are preserved above as references.

AI-assisted contributions

This repository follows the Fedora AI-Assisted Contributions Policy. The human contributor is always the author and is fully accountable for every contribution. Disclose AI tool usage via the Assisted-by: commit message trailer.