RUN-4780: Clarify Groovy plugin hot reload requires plugin.refreshDelay

[elquimeras]

Summary

Fixes RUN-4780 ("Hot reloading groovy plugin is not working"). The docs claimed Groovy plugins hot-reload automatically after their initial load; in practice Rundeck never re-checks a loaded Groovy plugin unless plugin.refreshDelay is explicitly set (root cause: resources.groovy defaults the Spring refresh-check-delay to -1, disabling the refresh check entirely — this has been the behavior since the feature was introduced, not a regression).

• Hot reloading is now documented as opt-in via the plugin.refreshDelay JVM system property.
• Added an "Enabling Hot Reloading" subsection pointing to the canonical System Properties Configuration page for RPM/DEB setup, plus a Docker note.
• Added a caution that enabling this makes Rundeck watch every Groovy plugin in libext, not just the one being edited, and can break startup if any of them are empty or invalid.

Changes

• docs/developer/groovy-plugin-development.md — corrected the Overview bullet and rewrote the "Iterative Development" section under Development Workflow.
• .gitignore — ignore local .atl/ directory.

[Copilot]

🟡 Changes recommended

The new documentation includes ambiguous Docker guidance and a potentially unsafe RPM/DEB example that can overwrite existing RDECK_JVM_OPTS settings.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the Rundeck documentation to clarify that Groovy plugin hot reloading is not automatic after initial load, and requires explicitly enabling refresh checks via the plugin.refreshDelay JVM system property. It also adds a local ignore entry for a .atl/ directory.

Changes:

• Clarifies Groovy plugin “Hot Reloading” as an opt-in capability in the Overview section.
• Reworks the iterative development workflow to document enabling hot reload via -Dplugin.refreshDelay=..., including cautions about watching all Groovy plugins in libext.
• Updates .gitignore to ignore a local .atl/ directory.

File summaries

File	Description
docs/developer/groovy-plugin-development.md	Clarifies hot reload behavior and adds an opt-in configuration subsection + caveats for Groovy plugin development.
.gitignore	Ignores local .atl/ directory artifacts.

Review details

• Files reviewed: 1/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The documentation updates align with existing configuration guidance in the repo and introduce no apparent inconsistencies or incomplete changes.

Review details

• Files reviewed: 1/2 changed files
• Comments generated: 0 new
• Review effort level: Lite

[luismalamoc]

A few follow-ups from review (claims verified against resources.groovy in rundeck/rundeck — refresh-check-delay defaults to -1 and applies to every .groovy in libext, so the core correction in this PR is accurate):

1. Config-file alternative to JVM opts: the value is read via application.config.getProperty("plugin.refreshDelay", ...), i.e. the merged Grails config — so a plain plugin.refreshDelay=5000 line in rundeck-config.properties should work too. Worth a quick local test; if it works, documenting it as the primary method would simplify the Docker note considerably (no derived image needed).
2. Startup caveat precision: a broken or empty .groovy file in libext may fail startup even without plugin.refreshDelay set (the script beans are defined at startup either way). If you verified breakage only happens with refresh enabled, ignore this; otherwise consider softening the warning to "broken or empty .groovy files in libext can prevent startup".
3. Snyk check failing: diff is markdown-only, so this is almost certainly repo baseline rather than this PR — but it leaves the PR blocked. Worth confirming against another recent PR before merge.

[elquimeras]

@luismalamoc Thanks for the detailed review. Verified all three against rundeckapp source (local checkout of rundeck/rundeck):

1. Config-file alternative: confirmed — Application.groovy registers rundeck-config.properties as a Spring PropertySource with addFirst, so it has higher precedence than JVM system properties, and it's the config file present in every install type. Documented it as the primary method in 68cb382 (JVM opts kept as an alternative).
2. Startup caveat precision: confirmed via source, not empirical testing — resources.groovy defines the lang:groovy bean for every .groovy file in libext unconditionally, and these are eagerly-instantiated singletons (no lazy-init), so a broken/empty file can break startup regardless of plugin.refreshDelay. Softened the warning in cf0587b to not imply the risk is exclusive to enabling it.
3. Snyk check: leaving this out of scope for this PR per the team's call — will be looked at separately.

Ready for another pass whenever you have a chance.

[luismalamoc]

Verified both follow-ups are addressed:

1. rundeck-config.properties documented as the primary method (68cb382) — confirmed against Application.groovy (addFirst property source, takes precedence) and the linked Config File Reference page exists on 4.0.x.
2. Startup warning softened (cf0587b) to reflect that broken/empty .groovy files in libext are a startup risk regardless of plugin.refreshDelay.

Snyk failure is repo baseline, tracked separately per team's call. LGTM.