# Ansible Release Management: Detailed Breakdown

---

## 1) High-level picture (one-line summary)

- **ansible-core** = the engine (core runtime & modules).
- **Ansible Community Package** = the umbrella distribution that bundles ansible-core + many Collections.
- **Execution Environments (EEs)** = container images that package an Ansible runtime (ansible-core) and collections so users can run Ansible in a consistent container.

These three are released on coordinated but distinct schedules; ansible-core drives the EE timelines, and the community package bundles a compatible ansible-core plus Collections.

---

## 2) Versioning & support rules

- **Community package (Ansible)** uses **Semantic Versioning (MAJOR.MINOR.PATCH)**.
- Major bump = incompatible changes.
- Minor = backward-compatible additions.
- Patch = bug/security fixes.
- Adopted semver starting with the 2.10+ model.

- **ansible-core** uses a different numbering (e.g., `2.11`, `2.12`).
- Middle digit = release number (not guaranteed backwards compatible).
- Patches (e.g., `2.12.1`) = bug/security fixes, released regularly.

- **Support window**:
- Maintain current + X previous majors/minors (see docs).
- ansible-core patches ~every 4 weeks.
- When a new major community package is published, older majors move toward EOL.

---

## 3) Release cadence — timeline & flow

### Development & feature merge
- New features and fixes merged to ansible-core, collections, and repos.
- Work tracked in **roadmaps and issues**.

### Cut ansible-core release
- Core team prepares new ansible-core (e.g., `2.13`).
- Happens ~twice a year.

### Maintenance window & freeze
- After new core major, collection versions freeze for community package RC.
- **ansible-build-data** updated with collection versions.

### Build community package
- Use **antsibull-build** to assemble from ansible-core + collections.
- Produces wheels/tarballs.

### Create RC(s) & run tests
- Release candidates tested with unit, integration, molecule, and packaging tests.
- Blockers fixed → iterate RCs.

### Publish final artifacts
- Upload wheels/sdist to **PyPI** via `twine`.
- Push Git tags.
- Announcements → Forum & Matrix.

### Execution Environments rebuild
- EE images (minimal & base) rebuilt with new ansible-core + collections.
- Published to **GHCR**.

### Ongoing patches & backports
- Patches every ~4 weeks for core.
- Bug/security fixes backported to supported majors.

---

## 4) Repositories & automation

- **ansible-core repo** — engine code + roadmaps/issues.
- **ansible-build-data** — metadata for collections + release dates.
- **antsibull-build** — assembles community package.
- **antsibull-changelog** — aggregates changelog fragments.
- **images repo** — builds EE images (base & minimal).

---

## 5) Tests & gating

- Unit tests in core & collections.
- Integration tests & molecule scenarios.
- End-to-end CI tests across platforms.
- Packaging checks (wheels/sdist).
- Changelog/lint checks.

Release candidates only graduate after automated + manual sign-off.

---

## 6) Execution Environments: build & release

- EE = container image with ansible-core + collections + OS pkgs.

**Flavors:**
- `community-ee-minimal`: ansible-core only.
- `community-ee-base`: ansible-core + core collections (`ansible.posix`, `ansible.utils`, `ansible.windows`).

**Build flow:**
1. Update ansible-core / collection list.
2. Use **ansible-builder** + Dockerfile templates.
3. Validate (ansible-navigator, sample playbooks).
4. Publish to GHCR with tags (e.g., `:2.18.9-1`).

---

## 7) Changelogs, release notes, and announcements

- **antsibull-changelog** aggregates changelog fragments.
- Release announcements posted on:
- **Ansible Forum** (News & Announcements).
- **Matrix** rooms.
- EE releases include image tags, digests, pull commands.

---

## 8) Roles & responsibilities

- **Core maintainers** — plan/cut ansible-core, roadmap.
- **Release engineers** — run tooling, coordinate build-data, assemble packages, publish artifacts.
- **Collections maintainers** — ensure compatibility & provide changelogs.
- **Community & Release WG** — coordinate schedules, triage blockers, communicate releases.

---

## 9) Example release timeline

| Step | Week | Action |
|------|------|--------|
| 0 | W0 | Feature freeze for ansible-core; roadmap finalized |
| 1–4 | W1–W4 | ansible-core RC builds + CI tests |
| 5 | W5 | Publish ansible-core final (e.g., `2.13`) |
| 6 | W6 | Update ansible-build-data for next community package |
| 7–8 | W7–W8 | Run antsibull-build → RC(s), CI tests |
| 9 | W9 | Publish community Ansible (e.g., `5.0.0`), push PyPI + tags |
| 10 | W10 | Rebuild/publish EE images (base/minimal) |

---

## 10) Backports, security fixes & maintenance

- ansible-core gets patches every ~4 weeks.
- Community package & EEs follow suit.
- Fixes are backported to supported majors.
- Critical security fixes may trigger emergency releases.

---

## 11) Practical commands & scripts

**Clone tooling:**

git clone https://github.com/ansible-community/ansible-build-data.git
git clone https://github.com/ansible-community/antsibull.git
git clone https://github.com/ansible-community/antsibull-changelog.git

- **Run an antsibull build (example — actual usage requires project-specific args):**

 cd antsibull
./scripts/build-ansible --from-build-data ../ansible-build-data/ansible.in --output-dir ../build

- (Note: antsibull has more complex scripts, uses poetry/poetry-run in repo; see repo README for exact commands.)( [GitHub](https://github.com/ansible-community/antsibull) )

### **Publish to PyPI:**

python -m pip install --upgrade twine
twine upload dist/ansible-*.whl dist/ansible-*.tar.gz
git tag -a vX.Y.Z -m "Release X.Y.Z"
git push origin vX.Y.Z

- **Build an EE (example using ansible-builder):**

ansible-builder build -t ghcr.io/ansible-community/community-ee-base:2.13.0-1

podman push ghcr.io/ansible-community/community-ee-base:2.13.0-1

- **(Exact build steps use ansible-builder and images repo templates; see EE docs.) ([Ansible](https://docs.ansible.com/ansible/latest/getting_started_ee/index.html))**

## 12) Common pitfalls and troubleshooting

- Mismatched collection versions — include incompatible collection versions; guard by locking ansible-build-data and running CI scenarios. ([GitHub](https://github.com/ansible-community/ansible-build-data))

- Packaging failures on PyPI — packaging/metadata issues or binary wheel build failures; antsibull packaging checks and release engineers’ local install tests catch these. ([GitHub](https://github.com/ansible-community/antsibull))

- Broken RCs due to external dependencies — e.g., OS package versions in EE base images; add extra validation steps for EE images. ([GitHub](https://github.com/ansible-community/images))

## 13) How these pieces depend on each other (dependency map)
- ansible-core (engine) → base dependency for both the Community Package and EEs.

- ansible-build-data → lists Collections and exact versions used to compose the Community Package (reads from collections repos).

- antsibull-build → composes Community Package from ansible-core + ansible-build-data Collections.

- antsibull-changelog → aggregates changelogs from ansible-core + collections for release notes.

- images repo + ansible-builder → build EEs using a chosen ansible-core and collections.

- Flow:

code
 \→ test 
     \→ ansible-core release 
            \→ update build-data 
                \→ antsibull-build creates community package 
                    \→ publish to PyPI → rebuild EE images 
                        \→ publish EE images 
                            \-> announce. 

- ([GitHub](https://github.com/ansible-community/ansible-build-data))

## 14) Where to watch / join (communication & docs)

- Official docs: Release and Maintenance and Roadmaps pages for Ansible / ansible-core. ([Ansible](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html))

- GitHub: ansible-core, ansible-build-data, antsibull/antsibull-changelog, images (EE). ([GitHub](https://github.com/ansible-community/ansible-build-data))

- Community Forum (News & Announcements) and Matrix rooms (#release-management, #community, etc.) for release coordination and announcements. ([Ansible](https://forum.ansible.com/t/release-announcement-ansible-community-execution-environment-base-and-minimal-2-18-9-1/44478))

## 15) Suggested checklist for a release engineer (practical)

1. Confirm ansible-core final is built & all CI green.
1. Update ansible-build-data with Collections list & bump versions.
1. Run antsibull-build to produce RC.
1. Run full CI matrix (unit, integration, packaging, install tests).
1. Aggregate changelogs with antsibull-changelog.
1. Fix any blockers; iterate RC until green.
1. Publish final packages to PyPI; push tags & release notes.
1. Rebuild EE images; validate; push to GHCR.
1. Announce on Forum and Matrix; monitor for post-release issues and security reports. ([GitHub](https://github.com/ansible-community/antsibull))

## 16) Further reading (official resources)

- Release & Maintenance docs — Ansible docs. ([Ansible](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html))
- ansible-core Roadmaps — docs. ([Ansible](https://docs.ansible.com/ansible/latest/roadmap/ansible_core_roadmap_index.html))
- ansible-build-data — GitHub repo. ([GitHub](https://github.com/ansible-community/ansible-build-data))
- antsibull (antsibull-build) — GitHub repo & PyPI docs. ([GitHub](https://github.com/ansible-community/antsibull))
- Execution Environments (images repo & EE getting started) — GitHub + Ansible docs. ([GitHub](https://github.com/ansible-community/images))

✍️ [*Abhay Dandge*](https://www.linkedin.com/in/abhaydandge/)