update-collection

Update an existing Ansible collection. Always shows a diff and waits for confirmation before writing.

---

Required Inputs

1. collection identification — namespace.name or path (resolved from discovery)
2. change_description — What to change (e.g., "bump version to 1.1.0", "add a new filter plugin", "update the description in galaxy.yml")

---

Behavior

Step 1 — Discovery

Locate the collection via discovery (references/discovery.md).

Step 2 — Load Target Files

Read only the files relevant to the requested change.

Step 3 — Apply Change

Apply the requested change:

• Preserve all existing fields and structure
• Use templates from references/collection.md for new files
• All new module/plugin code follows the complete skeleton format

Step 4 — Show Unified Diff (per file)

For each modified or created file, show the diff:

--- collections/ansible_collections/myorg/infra/galaxy.yml (original)
+++ collections/ansible_collections/myorg/infra/galaxy.yml (proposed)
@@ -3,7 +3,7 @@
 namespace: myorg
 name: infra
-version: 1.0.0
+version: 1.1.0
 readme: README.md

Then ask: "Apply these changes? (yes/no)"

Step 5 — Write on Confirmation

• If yes: write all modified/created files.
• If no: ask what to change and loop back.

Step 6 — Final Output

Show updated file tree:

find <collection_path> -type f | sort

Suggest next step:

Next step: Run `ansible-galaxy collection build` to test the collection build
           and `ansible-galaxy collection install <tarball> --force` to test locally.

---

Change Types Supported

Change requested	Files to modify	How to handle
Bump version	galaxy.yml, CHANGELOG.md	Update version field; add CHANGELOG entry with date
Update description	galaxy.yml	Update description field
Add dependency	galaxy.yml	Append to dependencies dict with version range
Add role	roles/	Create role dir using new-role logic; update galaxy.yml tags if needed
Add module	plugins/modules/.py	Create complete module skeleton from references/collection.md
Add filter plugin	plugins/filter/.py	Create FilterModule skeleton
Add lookup plugin	plugins/lookup/.py	Create LookupBase skeleton
Update README	README.md	Apply requested textual change
Update meta/runtime.yml	meta/runtime.yml	Update requires_ansible or plugin_routing
Add CHANGELOG entry	CHANGELOG.md	Prepend new version entry

---

Version Bump Rules

• PATCH bump (1.0.x → 1.0.x+1): bug fixes, no behavior changes
• MINOR bump (1.x → 1.x+1.0): new features, backward-compatible
• MAJOR bump (x → x+1.0.0): breaking changes — warn the user that this affects consumers

When bumping version, always add a CHANGELOG entry:

## [1.1.0] - 2026-03-31

### Added
- <description of what was added>

### Changed
- <description of what was changed>