You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by su...@apache.org on 2026/09/13 08:28:10 UTC
(groovy) 01/01: Document unused imports, unneeded FQNs, and JIRA keys in Groovydoc.
This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch tweak-skills
in repository https://gitbox.apache.org/repos/asf/groovy.git
commit fbadb04345e2884ed051a5c3944532b03451e02d
Author: Daniel Sun <su...@apache.org>
AuthorDate: Sun Sep 13 17:00:45 2026 +0900
Document unused imports, unneeded FQNs, and JIRA keys in Groovydoc.
Canonical rule lives in CONTRIBUTING.md Documentation: drop unused
imports; prefer a simple name once the type is in scope (including
in {@link} / {@code} / {@see}); and do not cite a JIRA issue key
(`GROOVY-` plus the issue number) in Javadoc or Groovydoc except
when explaining a compatibility constraint. Naming the ticket that
introduced a change is not that exception. `// GROOVY-` markers on
tests are out of scope. AGENTS.md, ARCHITECTURE.md, and the
internals / fix-workflow / tests skills cite that home rather than
restating it.
---
.agents/skills/groovy-fix-workflow/SKILL.md | 15 ++++++++++++++-
.agents/skills/groovy-internals/SKILL.md | 13 ++++++++-----
.agents/skills/groovy-tests/SKILL.md | 14 ++++++++++++++
AGENTS.md | 5 ++++-
ARCHITECTURE.md | 4 +++-
CONTRIBUTING.md | 25 ++++++++++++++++++++++++-
6 files changed, 67 insertions(+), 9 deletions(-)
diff --git a/.agents/skills/groovy-fix-workflow/SKILL.md b/.agents/skills/groovy-fix-workflow/SKILL.md
index f244d64ba6..9d314e2fd5 100644
--- a/.agents/skills/groovy-fix-workflow/SKILL.md
+++ b/.agents/skills/groovy-fix-workflow/SKILL.md
@@ -84,6 +84,8 @@ mistakes AI tooling specifically tends to make.
restates only what AI tooling specifically needs.
- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) "Regression tests
for JIRA fixes" — companion section on test shape and placement.
+- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) "Documentation" —
+ source and Groovydoc style.
- [`AGENTS.md`](../../../AGENTS.md) — ASF licensing / provenance,
`Assisted-by:` trailer policy, the "what *not* to do" list.
@@ -179,6 +181,13 @@ implementing a fix:
vulnerability response is out of scope for this skill — see
*When to use this skill*.)
+12. **Documenting the JIRA key in Javadoc/GroovyDoc.** AI tooling
+ reaches for `/** … (GROOVY-12345) */` on the method it just
+ changed. Put the key in the commit message and the regression
+ test, not in published API docs. Naming the ticket that
+ introduced the method is not a compatibility explanation —
+ see [Documentation](../../../CONTRIBUTING.md#documentation).
+
## Procedure
When triage has produced a reproducer and pointed at an area:
@@ -268,7 +277,9 @@ Before producing the hand-back artefact:
`// GROOVY-<NNNN>` comment), correct tree.
- [ ] Working-tree diff contains only the test, the production
change, and any directly-required edit. No drive-by
- reformat, stray imports, or speculative refactor.
+ reformat, stray imports, or speculative refactor. Source
+ and Groovydoc style matches
+ [Documentation](../../../CONTRIBUTING.md#documentation).
- [ ] No new public API surface introduced unless the fix required
it; if it did,
[`COMPATIBILITY.md`](../../../COMPATIBILITY.md) was
@@ -293,6 +304,8 @@ Before producing the hand-back artefact:
the TDD ordering, scope discipline, and IDE-vs-build pitfalls.
- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) "Regression tests
for JIRA fixes" — test shape and placement.
+- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) "Documentation" —
+ source and Groovydoc style.
- [`AGENTS.md`](../../../AGENTS.md) — provenance and licensing,
trailer policy, the "what *not* to do" list.
- [`COMPATIBILITY.md`](../../../COMPATIBILITY.md) — observable API
diff --git a/.agents/skills/groovy-internals/SKILL.md b/.agents/skills/groovy-internals/SKILL.md
index b82332129f..e092ead109 100644
--- a/.agents/skills/groovy-internals/SKILL.md
+++ b/.agents/skills/groovy-internals/SKILL.md
@@ -128,9 +128,10 @@ compiler/runtime work:
needs. The phase table is in
[Compilation pipeline](../../../ARCHITECTURE.md#compilation-pipeline).
-7. **Wildcard imports.** Match the explicit-import convention
- already in the tree — see
- [Compiler and runtime conventions](../../../ARCHITECTURE.md#compiler-and-runtime-conventions).
+7. **Wildcard imports, unused imports, or unneeded FQNs.** Match
+ the explicit-import convention already in the tree — see
+ [Compiler and runtime conventions](../../../ARCHITECTURE.md#compiler-and-runtime-conventions)
+ and [Documentation](../../../CONTRIBUTING.md#documentation).
8. **Adding public API surface "for completeness".** Public API
is covenanted — see
@@ -197,7 +198,9 @@ Before declaring the change ready:
- [ ] No edits to files under `build/generated/`.
- [ ] No formatting changes outside the lines that needed to
change.
-- [ ] Imports are explicit, not wildcards.
+- [ ] Imports are explicit, not wildcards. Unused imports,
+ unneeded FQNs, and JIRA keys in Javadoc/GroovyDoc match
+ [Documentation](../../../CONTRIBUTING.md#documentation).
- [ ] AST node construction uses `ClassHelper` for known types
and `GeneralUtils` factories where applicable.
- [ ] AST transformation declares a phase, and the phase is the
@@ -229,7 +232,7 @@ Before declaring the change ready:
- [`COMPATIBILITY.md`](../../../COMPATIBILITY.md) — stability
tiers, breaking-change policy, binary-compatibility check.
- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) — build, test,
- fix workflow.
+ fix workflow, and "Documentation" (source and Groovydoc style).
- [`AGENTS.md`](../../../AGENTS.md) — AI-contributor guidance,
provenance rules.
- `src/main/java/org/codehaus/groovy/control/CompilePhase.java`
diff --git a/.agents/skills/groovy-tests/SKILL.md b/.agents/skills/groovy-tests/SKILL.md
index 031a3db99e..32261af25f 100644
--- a/.agents/skills/groovy-tests/SKILL.md
+++ b/.agents/skills/groovy-tests/SKILL.md
@@ -144,6 +144,14 @@ tests:
user-facing example* belongs in the spec test. See
[Executable AsciiDoc examples](../../../CONTRIBUTING.md#executable-asciidoc-examples).
+9. **Unused imports or unneeded FQNs in test source.** Same
+ source-style rule as production — see
+ [Documentation](../../../CONTRIBUTING.md#documentation).
+ Inline `<pre class="...groovyTestCase">` blocks are published
+ Groovydoc. A `// GROOVY-` comment above a regression-test
+ method is required, not a violation — see
+ [Regression tests for JIRA fixes](../../../CONTRIBUTING.md#regression-tests-for-jira-fixes).
+
## Procedure
When writing or modifying a test:
@@ -184,6 +192,10 @@ Before declaring the change ready:
path separators) baked into assertions — see
[Test-writing pitfalls](../../../CONTRIBUTING.md#test-writing-pitfalls).
- [ ] `git status` shows no scratch files in the working tree.
+- [ ] Test source and inline Javadoc match
+ [Documentation](../../../CONTRIBUTING.md#documentation). A
+ `// GROOVY-` comment on a regression-test method is
+ required, not a violation.
- [ ] Commit message references `GROOVY-NNNNN` where applicable.
## References
@@ -191,6 +203,8 @@ Before declaring the change ready:
- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) "Tests" — the
canonical test conventions (framework, naming, AsciiDoc
pattern, pitfalls).
+- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) "Documentation" —
+ source and Groovydoc style (including inline Javadoc tests).
- [`ARCHITECTURE.md`](../../../ARCHITECTURE.md) — overall test
layout.
- [`COMPATIBILITY.md`](../../../COMPATIBILITY.md) — what
diff --git a/AGENTS.md b/AGENTS.md
index 4d268c0a97..5067d09427 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -118,7 +118,10 @@ Follow what's already in the tree. Specifically:
requires it; public API is covenanted and hard to remove.
- Do not introduce new runtime dependencies without discussion — every new
dependency needs a license review and potentially a `NOTICE` / `LICENSE` update.
-- Remove unused imports and dead code you introduce.
+- Remove unused imports and dead code you introduce. Source and
+ Groovydoc style — unneeded fully-qualified names, and JIRA issue
+ keys in doc comments — is in "Documentation" in
+ [`CONTRIBUTING.md`](CONTRIBUTING.md).
For API/behaviour changes, add or update tests alongside the code change.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 896f1d7f3b..a41e64c3ea 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -253,7 +253,9 @@ above. Each bites contributors quickly if missed:
exposure.
- **Explicit imports, not wildcards.** The codebase uses explicit
per-class imports; new code should match. IDE-default wildcard
- imports get flagged in review.
+ imports get flagged in review. Unused imports and unneeded
+ fully-qualified names: see
+ [Documentation](CONTRIBUTING.md#documentation).
- **New code prefers `org.apache.groovy.*`.** Legacy code under
`org.codehaus.groovy.*` stays where it is for compatibility,
but new packages should follow the `org.apache.groovy.*`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 54798de109..626b86802c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -342,7 +342,9 @@ then fix**:
6. **Diff the working tree.** Anything outside the regression test
and the production change needs a reason. Drive-by reformatting
and stray imports should be reverted; they hide real changes in
- review.
+ review. Unused imports, unneeded fully-qualified names, and
+ JIRA keys in Groovydoc/Javadoc: see
+ [Documentation](#documentation).
7. **Commit with a JIRA reference.** `GROOVY-NNNNN: <short subject>`
on the first line — see
[Submitting a pull request](#submitting-a-pull-request).
@@ -544,6 +546,27 @@ contributing code, please treat documentation as part of the change:
- **Groovydoc is part of the public API.** Public classes and methods
need accurate Groovydoc/Javadoc. Match the style of existing classes
in the module you're editing.
+- **No unused imports, and no unneeded fully-qualified names.** Use
+ explicit per-class imports (not wildcards — see
+ [`ARCHITECTURE.md`](ARCHITECTURE.md#compiler-and-runtime-conventions)).
+ Drop an import that nothing in the file uses. Prefer the simple
+ name once the type is in scope (imported, same package, or packages
+ imported by default, e.g. `java.lang`) — including in Groovydoc/Javadoc
+ `{@link}`, `{@code}`, and `{@see}`.
+- **Keep JIRA keys out of Groovydoc/Javadoc.** Do not cite a JIRA
+ issue key (`GROOVY-` plus the issue number; the digit count is
+ not fixed) in a Javadoc or Groovydoc comment — including in
+ `{@link}`, `{@see}`, and parenthetical `(GROOVY-…)` — except
+ when the prose is explaining a compatibility constraint (binary
+ compatibility, a behavioural change across versions, a restored
+ ABI). Naming the ticket that introduced a method or change is
+ not that exception. Published API docs describe behaviour, not
+ the ticket. The key belongs in the commit message and in the
+ regression test — see
+ [Regression tests for JIRA fixes](#regression-tests-for-jira-fixes)
+ and [Submitting a pull request](#submitting-a-pull-request).
+ This rule is about published doc comments, not about `// GROOVY-`
+ markers on tests or in production code.
Cross-version reference documentation, the GDK, and the website itself
live in the separate [`groovy-website`](https://github.com/apache/groovy-website)