You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by pa...@apache.org on 2026/04/28 08:26:27 UTC
(groovy-website) branch asf-site updated: seed AI files
This is an automated email from the ASF dual-hosted git repository.
paulk-asert pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/groovy-website.git
The following commit(s) were added to refs/heads/asf-site by this push:
new cf0dd29 seed AI files
cf0dd29 is described below
commit cf0dd2981d60adcaefb626a503094d07d21447ab
Author: Paul King <pa...@asert.com.au>
AuthorDate: Tue Apr 28 18:26:07 2026 +1000
seed AI files
---
.agents/skills/release-notes/SKILL.md | 237 ++++++++++++++++++++++++++++++++++
.github/copilot-instructions.md | 24 ++++
AGENTS.md | 158 +++++++++++++++++++++++
RELEASE_NOTES_GUIDE.adoc | 229 ++++++++++++++++++++++++++++++++
4 files changed, 648 insertions(+)
diff --git a/.agents/skills/release-notes/SKILL.md b/.agents/skills/release-notes/SKILL.md
new file mode 100644
index 0000000..8f3571d
--- /dev/null
+++ b/.agents/skills/release-notes/SKILL.md
@@ -0,0 +1,237 @@
+<!--
+ 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.
+-->
+---
+name: release-notes
+description: Guidance for drafting or updating the per-release notes page under site/src/site/releasenotes/groovy-X.Y.adoc — structure, issue-reference conventions, gapi macro, JDK requirements section, and the JIRA changelog link. Use when adding a new release notes file, expanding an in-progress one, or polishing one ahead of a release.
+license: Apache-2.0
+compatibility: claude, codex, copilot, cursor, gemini, aider
+metadata:
+ audience: contributors to apache/groovy-website
+ scope: release-notes-authoring
+---
+
+# Release notes
+
+Use this skill when drafting or updating a release notes page at
+`site/src/site/releasenotes/groovy-X.Y.adoc`. The release notes are
+the most-read page on the website around release time and the most
+quoted in third-party coverage, so accuracy and tone matter more here
+than on most pages.
+
+## When to use this skill
+
+**Use it for:**
+
+- Creating a new `groovy-X.Y.adoc` release notes page.
+- Expanding an in-progress one (adding a section for a new feature
+ area, a behaviour change, a breaking change).
+- Polishing the page ahead of a final release (filling out the
+ highlights, tightening prose, verifying issue links).
+
+**Don't use it for:**
+
+- Blog posts or announcement pages — those follow different conventions
+ under `site/src/site/blog/` and `site/src/site/pages/`.
+- Generator or template changes (`generator/`, `site/src/main/site/`) —
+ those are generator-side concerns; this skill is content-only.
+- Updating the changelog HTML linked from the bottom of the page — that
+ is generated separately, not hand-edited.
+
+## Read first
+
+- [`RELEASE_NOTES_GUIDE.adoc`](../../../RELEASE_NOTES_GUIDE.adoc) —
+ **the editorial source of truth** for release notes structure, the
+ highlights / modules / topical / breaking-changes / JDK / addendum
+ layout, the dual-audience drafting principle (humans + AI; `gapi:`
+ on first class mention), enhanced-vs-new framing, and process tips.
+ This skill is the working surface; that document is the map.
+- [`AGENTS.md`](../../../AGENTS.md) — overall AI-contributor guidance,
+ ASF provenance rules, and content conventions.
+- [`README.adoc`](../../../README.adoc) — site structure, build, and the
+ asf-site branch warning.
+- The most recent shipped release notes file (e.g.
+ `site/src/site/releasenotes/groovy-5.0.adoc`) — copy its structure,
+ attribute block, and link style. New release notes derive from the
+ previous file, not from a blank template.
+
+## Top failure modes to avoid
+
+These are the recurring mistakes when working on release notes:
+
+1. **Hallucinating JIRA issue numbers.** Every `GROOVY-NNNN` reference
+ must resolve on <https://issues.apache.org/jira/browse/GROOVY>.
+ Verify before writing — a wrong number embarrasses publicly.
+2. **Hallucinating API symbols, methods, or behaviours.** A release-notes
+ bullet that describes a method that doesn't exist, or an option that
+ was never added, is worse than no bullet. Cross-check each claim
+ against the actual code in `apache/groovy` for the release branch.
+3. **Wrong issue-link form.** The convention is
+ `link:https://issues.apache.org/jira/browse/GROOVY-NNNN[GROOVY-NNNN]`.
+ Bare URLs and inconsistent formatting break the visual flow of the
+ page and the rendered footnotes.
+4. **Hand-coding `groovy-lang.org/gapi/...` URLs.** Use the `gapi:`
+ macro instead — it is processed by `generator/src/main/groovy/generator/LinkMacroProcessor.groovy`
+ and keeps links consistent across the site. (Same for any other
+ custom link macros the generator defines.)
+5. **Skipping the Groovydoc link on first class mention.** The *first*
+ time a class appears in the document, link it via `gapi:` so both
+ human and AI readers get the fully-qualified name. Subsequent
+ mentions can use the short name. This is the dual-audience
+ drafting rule — see [`RELEASE_NOTES_GUIDE.adoc`](../../../RELEASE_NOTES_GUIDE.adoc).
+6. **Drive-by edits to unrelated sections.** Reformatting an existing
+ section "for consistency" while adding a new one buries the real
+ change in review and is rejected. Touch only what your task asks for.
+7. **Restating the JIRA title verbatim.** A release notes bullet should
+ explain *what changed and why a user cares*, not echo the issue
+ summary. JIRA titles are written for triage; release notes are
+ written for users.
+8. **Missing or wrong "Breaking changes" coverage.** Behaviour changes
+ that can break user code must be called out, with migration guidance.
+ Don't bury them in feature sections. The canonical source list is
+ the JIRA filter `labels = breaking AND fixVersion = X.Y.Z` — start
+ there rather than `git log` or memory. Major breaking changes get
+ their own subsection; the rest are bullets with issue links.
+9. **Wrong JDK-requirements section.** Every release notes page ends
+ with a JDK requirements block; the build/runtime JDK ranges must
+ match what the release branch actually supports, not what the
+ previous release supported.
+10. **Forgetting the changelog link.** The page ends with a
+ "More information" section linking to
+ `../changelogs/changelog-X.Y.Z-unreleased.html` (or the released
+ variant). Mismatched filenames produce a deadlink at publish time.
+11. **Treating an `-alpha` / `-beta` / `-rc` page as final.** Pre-release
+ pages are iterated on; preserve `-unreleased` markers and
+ placeholder sections rather than deleting them prematurely.
+12. **Forgetting that point releases append, not replace.** When `X.0.1`
+ or later ships, its notes are added as an `Addendum for X.0.1`
+ section *at the end of the same `groovy-X.Y.adoc` page*, not given
+ their own file. Same for `X.0.2`, `X.0.3`, ...
+
+## Procedure
+
+1. **Start from the previous release.** Copy
+ `site/src/site/releasenotes/groovy-<previous>.adoc` as the
+ structural template. Adjust attribute block, version numbers, and
+ anchor IDs (`[[GroovyX.Y-...]]`) before editing content.
+2. **Source the issue list from JIRA, not from memory.** The JIRA
+ filter / changelog for the release version is the authoritative
+ list of what's in. Pull from there; don't infer from `git log`
+ alone (commits without `GROOVY-NNNN` exist; issues without commits
+ on the branch also exist).
+3. **Group by user-facing theme, not by issue number.** Bullets
+ covering the same area cluster under one section heading
+ (e.g. "Extension method additions and improvements", "AST transform
+ additions and improvements"). Order sections from most-impactful to
+ least; "Breaking changes" goes near the end.
+4. **Write each bullet in user-facing terms.** State the change, then
+ the user impact, then the issue link. Use code samples for anything
+ non-obvious — copy the existing AsciiDoc source-block style:
+
+ ```asciidoc
+ [source,groovy]
+ ----
+ def x = ...
+ assert x == ...
+ ----
+ ```
+
+5. **Use macros, not hand-coded URLs.** `gapi:` for API references;
+ `link:https://issues.apache.org/jira/browse/GROOVY-NNNN[GROOVY-NNNN]`
+ for issues. Match the form already used in the file.
+6. **Update the JDK requirements section.** State the build JDK floor,
+ the runtime JDK floor, and the tested JDK range. Match what the
+ release branch's CI actually exercises.
+7. **Update the "More information" link.** Confirm the
+ `changelog-X.Y.Z-...html` filename matches what the changelog
+ generator will produce.
+8. **Build the user site and check deadlinks.**
+
+ ```
+ ./gradlew :site-user:webzip
+ ```
+
+ Inspect `site-user/build/reports/` for deadlinks. Eyeball the
+ rendered page under `site-user/build/site/releasenotes/` for
+ broken includes, mis-rendered tables, or wrapped code blocks.
+
+## Validation checklist
+
+Before declaring the change ready:
+
+- [ ] Every `GROOVY-NNNN` reference resolves on JIRA.
+- [ ] Every API symbol, method name, or option mentioned exists in the
+ release branch of `apache/groovy`.
+- [ ] Issue links use the canonical `link:https://issues.apache.org/jira/browse/GROOVY-NNNN[GROOVY-NNNN]`
+ form; no bare URLs, no mismatched display text.
+- [ ] API references use the `gapi:` macro, not hand-coded
+ `groovy-lang.org/gapi/...` URLs.
+- [ ] Bullets describe user-facing change and impact, not raw JIRA titles.
+- [ ] Breaking / behaviour changes are in a dedicated section with
+ migration guidance, not buried under feature headings.
+- [ ] JDK requirements section reflects what this release branch
+ actually supports.
+- [ ] "More information" changelog link matches the generated filename
+ (including `-unreleased` vs released suffix as appropriate).
+- [ ] No edits to sections outside the scope of the task.
+- [ ] No generated artefacts (`build/`, `*.cache`) staged for commit.
+- [ ] `./gradlew :site-user:webzip` succeeds; deadlinks report is clean
+ for new/changed links.
+- [ ] Commit message references `GROOVY-NNNNN` where applicable; AI
+ provenance trailer added if AI tooling assisted.
+
+## Project-specific guidance
+
+The standing editorial guidance for Groovy release notes lives in
+[`RELEASE_NOTES_GUIDE.adoc`](../../../RELEASE_NOTES_GUIDE.adoc) at the
+repository root. That document is the source of truth for:
+
+- Document structure (Highlights → Modules → Topical → Breaking
+ changes → JDK requirements → More information → Addenda).
+- Highlights are written *last* even though they appear first.
+- Module changes section: maven coordinates for new modules; mention
+ removed / deprecated / status-changed modules; skip internal
+ modules.
+- Topical sections: 1–4 examples each; overflow into a list with a
+ pointer to mainstream documentation.
+- Enhanced features get a brief recap of what they build on; new
+ features get context for why they're worth adding (other languages,
+ industry trends).
+- Dual-audience drafting (humans + AI), including `gapi:` on first
+ class mention.
+- Point releases append `Addendum for X.0.N` sections to the same
+ `groovy-X.Y.adoc` file rather than getting their own file.
+
+Read that guide before drafting; this skill's failure modes and
+procedure are the AI-side guardrails on top of it.
+
+## References
+
+- [`RELEASE_NOTES_GUIDE.adoc`](../../../RELEASE_NOTES_GUIDE.adoc) —
+ editorial source of truth (structure, dual-audience drafting,
+ enhanced-vs-new framing, addendum convention).
+- [`README.adoc`](../../../README.adoc) — site structure and build.
+- [`AGENTS.md`](../../../AGENTS.md) — overall AI-contributor guidance.
+- `site/src/site/releasenotes/` — all prior release notes; the most
+ recent shipped file is the structural template for the next one.
+- `generator/src/main/groovy/generator/LinkMacroProcessor.groovy` —
+ defines `gapi:` and related link macros.
+- `generator/src/main/groovy/generator/AsciidoctorFactory.groovy` —
+ AsciiDoctor extension wiring for the site.
+- JIRA: <https://issues.apache.org/jira/browse/GROOVY>.
+- ASF [Generative Tooling guidance](https://www.apache.org/legal/generative-tooling.html).
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..d572570
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,24 @@
+<!--
+ 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.
+-->
+
+See [`../AGENTS.md`](../AGENTS.md) for project-specific guidance for AI
+coding assistants contributing to the Apache Groovy website, including
+the asf-site auto-publish branch warning, ASF licensing and provenance
+requirements, and pointers to topic-specific editorial guides such as
+[`../RELEASE_NOTES_GUIDE.adoc`](../RELEASE_NOTES_GUIDE.adoc).
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8c8e605
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,158 @@
+<!--
+ 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.
+-->
+
+# Agent Guide for the Apache Groovy website
+
+Supplemental guidance for AI coding assistants (Claude Code, Codex, Cursor,
+Copilot, Gemini, Aider, and similar tools) contributing to the Apache Groovy
+website (`apache/groovy-website`).
+
+This file **supplements** — it does not replace —
+[`README.adoc`](README.adoc), which remains the authoritative source for
+how the site is structured, generated, and published. Topic-specific
+editorial guides — currently
+[`RELEASE_NOTES_GUIDE.adoc`](RELEASE_NOTES_GUIDE.adoc) — are the source
+of truth for *what good content looks like* in their area. This file
+just layers AI-specific guidance on top.
+
+## Branch warning (read first)
+
+The `asf-site` branch is the **live** branch. Per `README.adoc`:
+
+> The website is continuously updated from the `asf-site` branch.
+> This means that *every merge on that branch is immediately published*.
+
+Implications for AI-assisted contributions:
+
+- Treat the working tree as production. Don't push speculative changes.
+- Date-sensitive content (release announcements, blog posts pegged to a
+ date) belongs on a dedicated branch and is merged into `asf-site` on
+ the day it should appear.
+- Generated artefacts (`build/`, `*.cache` files under `site/src/site/blog/`)
+ are not committed.
+
+## Licensing and provenance
+
+Apache Groovy and its website are licensed under Apache License 2.0.
+Contributions must meet the ASF's
+[Generative Tooling guidance](https://www.apache.org/legal/generative-tooling.html).
+In particular:
+
+- **Do not copy verbatim from incompatibly-licensed sources** (GPL / AGPL /
+ LGPL, proprietary, unattributed Stack Overflow / blog snippets). Reimplement
+ from specifications, standards, or Apache-compatible sources (see the
+ [ASF 3rd Party Licensing Policy](https://www.apache.org/legal/resolved.html)).
+- **Every new source file needs the ASF license header.** Copy the form from
+ any existing `.adoc`, `.groovy`, or `.gradle` file in the repository.
+- **Attribute AI assistance in commits.** When AI tooling assisted on
+ a change, consider adding an `Assisted-by:` trailer naming the tool(s):
+
+ ```
+ Assisted-by: <tool name and version>
+ ```
+
+ `Assisted-by:` is the default and reflects the ASF's stance that a
+ human contributor performs the final check on every change.
+ `Co-authored-by:` is conventionally used for human co-authors.
+ `Generated-by:` is reserved for cases where AI tooling produced a change
+ with minimal human modification. The ASF's
+ [Generative Tooling guidance](https://www.apache.org/legal/generative-tooling.html)
+ is authoritative.
+- **The contributor remains responsible for what they submit.** Review
+ generated output for licensing, correctness, and style before committing.
+
+## Build and preview
+
+Canonical instructions live in [`README.adoc`](README.adoc). The short form:
+
+```
+./gradlew :site-user:webzip # build the user site
+./gradlew :site-dev:webzip # build the developer site
+```
+
+Outputs land under `site-user/build/site/` and `site-dev/build/site/`.
+A "deadlinks" report is produced under `site-user/build/reports/`; check it
+before declaring a content change ready.
+
+Use the Gradle wrapper (`./gradlew` / `gradlew.bat`); do not invoke a
+system `gradle`.
+
+## Content conventions
+
+Follow what's already in the tree. Specifically:
+
+- AsciiDoc (`.adoc`) is the source format for pages, blog posts, and
+ release notes. Match the surrounding file's heading levels, attribute
+ block, and macro usage.
+- Issue references use the `link:https://issues.apache.org/jira/browse/GROOVY-NNNN[GROOVY-NNNN]`
+ form. Don't invent issue numbers; verify each one resolves on JIRA.
+- Cross-references to Groovy API docs use the `gapi:` macro (see
+ `generator/src/main/groovy/generator/LinkMacroProcessor.groovy`); do not
+ hard-code `groovy-lang.org/gapi/` URLs by hand.
+- Templating uses the
+ [Markup Template Engine](https://groovy-lang.org/templating.html#_the_markuptemplateengine)
+ (Groovy DSL), not Mustache / Handlebars / Jinja. Don't rewrite an
+ existing template into a different engine.
+- Match the surrounding file's style. The site uses 4-space indent for
+ Groovy / Gradle, 2-space for AsciiDoc lists.
+
+## Commits and PRs
+
+- Reference the JIRA issue in commit messages where applicable, e.g.
+ `GROOVY-12345: short description`. Project issues are tracked at
+ <https://issues.apache.org/jira/browse/GROOVY>.
+- Keep commits focused. A content update, a generator change, and a
+ formatting pass are three separate commits, not one.
+- Build the affected site target locally (`:site-user:webzip` and/or
+ `:site-dev:webzip`) before opening a PR. Check the deadlinks report.
+- Don't merge speculative or date-sensitive content directly to
+ `asf-site` — see the branch warning above.
+
+## What *not* to do
+
+- **Don't push to `asf-site` without the change being ready to go live.**
+- Don't reformat content outside the lines your change actually touches.
+ Drive-by reformatting hides the real change and is rejected.
+- Don't invent JIRA issue numbers, API symbols, version numbers, or
+ release dates; verify each before writing it into the site.
+- Don't commit generated artefacts: `build/` directories, `*.cache` files
+ under `site/src/site/blog/`, IDE files, etc.
+- Don't introduce new build-time dependencies without discussion — every
+ new dependency needs a license review.
+
+## Skills
+
+Task-specific guidance lives under [`.agents/skills/`](.agents/skills/),
+each in its own directory with a `SKILL.md` describing when to use it,
+the recurring failure modes for that area, and a validation checklist.
+Load the relevant skill *before* writing or modifying content in its
+area — the skill is more focused than this file.
+
+| Skill | Use for |
+|---|---|
+| [`release-notes`](.agents/skills/release-notes/SKILL.md) | Drafting or updating a per-release `groovy-X.Y.adoc` page under `site/src/site/releasenotes/` |
+
+Additional skills will be added as recurring tasks emerge (blog posts,
+documentation pages, generator changes, ...).
+
+## Where to ask
+
+- Developer list: <de...@groovy.apache.org>
+- Slack: the Apache Groovy channel on the ASF Slack workspace
+- Issue tracker: <https://issues.apache.org/jira/browse/GROOVY>
diff --git a/RELEASE_NOTES_GUIDE.adoc b/RELEASE_NOTES_GUIDE.adoc
new file mode 100644
index 0000000..1bb86c1
--- /dev/null
+++ b/RELEASE_NOTES_GUIDE.adoc
@@ -0,0 +1,229 @@
+//////////////////////////////////////////
+
+ 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.
+
+//////////////////////////////////////////
+
+= Writing release notes for Apache Groovy
+The Groovy development team
+:groovydoc: https://groovy-lang.org/
+:jira: https://issues.apache.org/jira/browse/GROOVY
+
+This document captures the editorial conventions for the per-release
+notes pages under `site/src/site/releasenotes/groovy-X.Y.adoc`. It is
+the source of truth for *what good release notes look like* in this
+project. AI-specific guardrails (hallucination checks, link macros,
+build steps) live alongside it in
+link:.agents/skills/release-notes/SKILL.md[`.agents/skills/release-notes/SKILL.md`]
+and reference back to this guide.
+
+The release notes are the most-read page on the website around release
+time and the most quoted in third-party coverage, so accuracy and tone
+matter more here than on most pages.
+
+== Audience
+
+Release notes are written for two audiences simultaneously:
+
+* *Humans* — Groovy users deciding whether to upgrade, what to look at
+ first, and what might break.
+* *AI assistants* — increasingly the first thing a developer asks when
+ evaluating an upgrade ("what changed in Groovy X.Y?"). The release
+ notes are training data and retrieval material for those assistants.
+
+Write so that both audiences can pick up the document cold and form an
+accurate picture of the release. In particular, the *first time a
+class is mentioned*, point to its Groovydoc using the `gapi:` macro;
+this gives the fully-qualified name and gives both readers a reliable
+reference. When summarising a feature, include enough information that
+either audience knows whether they need to dive into the mainstream
+documentation for more.
+
+== Structure
+
+A canonical release notes page has these sections, in this order:
+
+. Highlights
+. New modules / module changes (when applicable)
+. Topical sections — one per major theme of the release
+. Breaking changes
+. JDK requirements
+. More information (link to the JIRA changelog)
+. Addenda for point releases (`Addendum for X.0.1`, `Addendum for X.0.2`, …) — added at the end as point releases ship
+
+Use the most recent shipped release notes file (e.g.
+`site/src/site/releasenotes/groovy-5.0.adoc`) as the structural
+template for the next one. New release notes derive from the previous
+file, not from a blank template.
+
+== Highlights
+
+The Highlights section is shown first but *usually written last*. It
+is a summary of all the features in the release and is meant to
+capture the reader's attention. Once the topical sections have settled
+down, return to Highlights and distil them.
+
+== New modules / module changes
+
+When the release adds, removes, deprecates, or moves a module, that
+information goes in a dedicated section — typically titled "New
+modules", "Module changes", or both. List:
+
+* New modules with their full Maven coordinates (groupId, artifactId,
+ version).
+* Modules that have been removed or deprecated.
+* Modules whose status has changed — for example, a module that has
+ moved between being included in `groovy-all` and being an optional
+ dependency.
+
+Internal modules are not typically mentioned.
+
+== Topical sections
+
+Each major theme of the release gets its own section. A topical
+section consists of:
+
+* A short description of the topic.
+* Between *one and four* interesting or relevant examples.
+* If more than three or four examples are worth covering, place the
+ remainder in a list that summarises the additional changes or
+ features.
+* When more examples or detail exist in the mainstream Groovy
+ documentation for that topic, include a reference to that
+ documentation rather than reproducing it here.
+
+=== Enhanced features vs new features
+
+When a topic is about an *enhanced* feature, provide a very short
+description of the existing functionality the enhancement builds upon
+before describing the change. The reader should not need to remember
+what existed in the previous release.
+
+When a topic is about a *new* feature, provide some context for why
+the feature is considered a worthwhile addition — for example,
+availability in other languages, alignment with industry trends, or a
+recurring user request. New features land better when their motivation
+is visible.
+
+=== Code examples
+
+Examples use AsciiDoc source blocks with the `groovy` language tag and
+favour `assert` statements over `println` so the reader can see the
+expected outcome inline:
+
+[source,asciidoc]
+----
+[source,groovy]
+----
+def words = ['row'].repeat(3) + ['your', 'boat']
+assert words.join(' ') == 'row row row your boat'
+----
+----
+
+Match the style of the surrounding file.
+
+== Breaking changes
+
+Any *major* breaking change gets its own subsection with full context
+and migration guidance. *Most* breaking changes are simply listed,
+each pointing back to the related JIRA issue.
+
+The JIRA issue should have the *`breaking` label* and a release
+version that matches the release notes being prepared. The JIRA filter
+on `labels = breaking AND fixVersion = X.Y.Z` is the canonical source
+list — start there rather than from `git log` or memory.
+
+== JDK requirements
+
+Every release notes page ends with a JDK requirements block. State:
+
+* The JDK floor for *building* Groovy.
+* The JDK floor for *running* Groovy (the runtime JRE minimum).
+* The range of JDK versions on which the release has been *tested*.
+
+Match what the release branch's CI actually exercises, not what the
+previous release supported.
+
+== More information
+
+Close the page with a "More information" section linking to the
+generated JIRA changelog:
+
+[source,asciidoc]
+----
+You can browse all the link:../changelogs/changelog-X.Y.Z-unreleased.html[tickets closed for Groovy X.Y in JIRA].
+----
+
+For pre-releases, retain the `-unreleased` marker until the release
+ships; remove it as part of the release-day update.
+
+== Addenda for point releases
+
+When a point release ships after the initial `X.0.0`, its notes are
+*added as a section at the end of the same `groovy-X.Y.adoc` page*,
+not given their own file. Use a heading of the form `Addendum for
+X.0.1`, `Addendum for X.0.2`, and so on.
+
+Within an addendum, the same structural conventions apply at a smaller
+scale: a brief intro, topical bullets, breaking changes if any, and
+issue links.
+
+== Editorial conventions summary
+
+* Write for both humans and AI; on first mention of a class, link its
+ Groovydoc via `gapi:`.
+* Bullets describe user-facing change and impact, not raw JIRA titles.
+* Every `GROOVY-NNNN` reference must resolve on JIRA — verify before
+ writing.
+* Issue links use the form
+ `link:{jira}/GROOVY-NNNN[GROOVY-NNNN]`. Bare URLs and inconsistent
+ display text break the visual flow of the page.
+* Don't reformat or restructure sections outside the scope of the
+ current change.
+* Don't commit generated artefacts (`build/`, `*.cache` files, IDE
+ files).
+
+== Process tips
+
+* Source the issue list from JIRA, not from memory or `git log` alone.
+ The JIRA filter / changelog for the release version is authoritative.
+* Group bullets by user-facing theme, not by issue number, before
+ drafting prose.
+* Write topical sections first, Highlights last.
+* Build the user site locally and check the deadlinks report before
+ declaring a change ready:
++
+----
+./gradlew :site-user:webzip
+----
++
+Inspect `site-user/build/reports/` for deadlinks and eyeball the
+rendered page under `site-user/build/site/releasenotes/`.
+
+== See also
+
+* link:README.adoc[`README.adoc`] — site structure and build.
+* link:AGENTS.md[`AGENTS.md`] — overall AI-contributor guidance and
+ ASF provenance rules.
+* link:.agents/skills/release-notes/SKILL.md[`.agents/skills/release-notes/SKILL.md`]
+ — AI-specific guardrails for release notes work; references this
+ guide as its source of truth.
+* `site/src/site/releasenotes/` — all prior release notes.
+* `generator/src/main/groovy/generator/LinkMacroProcessor.groovy` —
+ defines the `gapi:` and related link macros.
+* {jira}[Apache Groovy JIRA].