diff --git a/definition.md b/definition.md index dbaf054..fc4b07d 100644 --- a/definition.md +++ b/definition.md @@ -22,6 +22,9 @@ You have access to the following template files. Follow them precisely when gene - **`discourse-post.md`**: The template for Fedora Discussion summary posts. Follow its structure, placeholder names, and formatting exactly. - **`forgejo-comment.md`**: The template for Forgejo ticket comment updates. Follow its structure, placeholder names, and content guidelines exactly. Produce one comment block per ticket discussed in the meeting. +**Golden Reference:** +- **`examples/output/2026-04-21-docs-discourse.md`**: A validated golden reference of a complete Discourse post output. Consult this example to understand the target output quality, formatting conventions, and style. When in doubt about a formatting choice, match this example. + **Parsing Rules:** Refer to `meetbot-commands.md` for the full command reference, semantic weighting, and HTML format detection rules. The key parsing principles are: @@ -88,6 +91,36 @@ Generate 2-3 engaging title options for the Discourse post. * Titles should be concise and informative, not clickbait. + +**People References:** +* In the Executive Summary, introduce key actors on first mention as `FirstName (@username)`. All subsequent mentions in the Executive Summary use `@username` only. +* In the Detailed Meeting Log, always use `@username` only. Readers at this depth have already seen the introductions in the Executive Summary. + +**Ticket References:** +* Use the `### Ticket:` prefix for all ticket-related section headers in the Detailed Meeting Log, regardless of issue tracker. +* Format section headers as: `### Ticket: [shorthand](full_url) (Optional Description)` + - Forgejo: use cross-repo shorthand `org/repo#number` — e.g., `[docs/tickets#19](https://forge.fedoraproject.org/docs/tickets/issues/19)` + - Bugzilla: `[BZ#12345](url)` + - GitHub: `[org/repo#number](url)` +* Use the same linked shorthand format when referencing tickets inline in prose (Executive Summary, Detailed Meeting Log). + +**Proper Nouns:** +* Use correct capitalization for project and tool names. Common examples: "AsciiDoc" (not "ASCIIDoc" or "Asciidoc"), "Quick Docs" (not "QuickDocs"), "Forgejo", "Pagure". + +**Fedora Organizational Naming:** +* Use "Mindshare branch" when referring to the Mindshare Committee's branch of the org chart. Do not append "& Outreach." + +**Off-Topic Tangents:** +* If a tangent does not produce a decision, action item, or follow-up, omit it entirely from the summary. +* If a tangent leads to a concrete outcome, include it but focus on the outcome, not the tangent itself. + +**Completed Action Items:** +* If an action item is "post the meeting summary on Fedora Discussion" (or equivalent), apply strikethrough formatting (`~~text~~`) since that action is completed by the act of posting the summary itself. + +**Topics Bulleted List:** +* The `{{TOPICS_BULLETED_LIST}}` must contain only substantive discussion topics — items that drove decisions, action items, or significant technical discussion. Exclude announcements, introductions, greetings, housekeeping, and minor asides. + + Render all output as **standard Markdown** directly in the chat window. Organize the output in distinct, clearly-separated sections so the user can copy each piece to the right destination. @@ -116,4 +149,48 @@ If no tickets were substantively discussed, omit this section and note that no t * **Attribution:** The AI disclaimer text in the Discourse post template uses a placeholder for the tool name. The user will fill this in with the correct AI tool and version. * **Completeness:** Every `!action` item in the log must appear in the Action Items section. Do not skip or merge action items. * **Ticket coverage:** Every ticket that received substantive discussion (more than a passing `!link`) must get its own Forgejo comment block. +* **Template fidelity:** Follow the templates in `discourse-post.md` and `forgejo-comment.md` exactly. Match the heading levels, bullet styles (`-` not `*`), Markdown link syntax, and section order. Do not substitute alternative formatting. The template is the source of truth for structure and presentation. + + +The following excerpts from a validated Docs Team meeting summary demonstrate the expected formatting conventions. +For the complete golden reference, see `examples/output/2026-04-21-docs-discourse.md`. + +**Greeting, introduction, and topics list:** + +Hey folks! :waving_hand: Here is the summary of the April 21, 2026, Fedora Docs Team meeting. + +As a core part of the Fedora Mindshare branch, the Docs Team ensures that Fedora's official documentation is accurate, accessible, and well-maintained. +Today's meeting focused on modernizing our build infrastructure on Forgejo, managing the archiving of legacy documentation, and sustaining our growing community. + +**Topics discussed in this meeting:** +- Removing GitLab and Pagure references from documentation repositories +- Container registry exploration for Antora build images +- SHA256 git repository compatibility workaround +- Establishing a `docs-archive` organization for legacy content + +--- + +**Executive Summary excerpt — note `FirstName (@username)` on first mention, `[org/repo#number](url)` for tickets:** + +A primary focus was placed on removing legacy GitLab and Pagure references across our repositories ([docs/tickets#19](https://forge.fedoraproject.org/docs/tickets/issues/19)). @korora volunteered to work on this. To address the fragmentation of the `docsbuilder.sh` scripts and the missing Containerfile, the team is exploring the use of Forgejo's native container registries to host the Antora build images. Hristo (@hricky) has volunteered to lead this investigation. + +--- + +**Action Items excerpt — note strikethrough on "post meeting summary":** + +* **@jflory7**: ~~Post a meeting summary on Fedora Discussion~~ and ticket updates for all discussed tickets in today's meeting + +--- + +**Detailed Meeting Log section header — note `### Ticket:` prefix with linked shorthand:** + +### Ticket: [docs/tickets#19](https://forge.fedoraproject.org/docs/tickets/issues/19) (Removing GitLab/Pagure References) + +**Detailed Meeting Log body — note bare `@username`, no first names:** + +@pbokoc requested help fixing the references primarily in the template repository to establish a "known good" setup before propagating the changes elsewhere. @korora took an action item to lead this effort. + +However, @cstrauf pointed out that the biggest underlying issue is the missing Containerfile, which builds the custom Fedora Antora styles. + +