This guide was generated from real release announcement discussions on the Apache Incubator mailing list and reflects practical issues encountered when announcing podling releases.
This guide is intended for:
It is designed to support practical decision-making when drafting and sending a release announcement and when correcting an announcement after feedback.
A release announcement should help users find the release through the project’s normal download entry point, without creating confusion about where to obtain artifacts or how to verify them.
This guide documents what release announcement threads highlighted: what reviewers objected to, what they asked projects to change, and how projects corrected announcements.
Guidance in this document complements, but does not replace, ASF policy and legal guidance.
Release announcements should link to the project’s download page rather than directly to artifact locations.
This avoids embedding incorrect URLs in announcement emails and reduces confusion about where users should obtain official release artifacts.
Existing ASF release announcements are a useful reference for patterns and wording. A practical reference point is the archive of messages sent to the ASF announcements list.
Incorrect links are corrected by sending a follow-up message to the same mailing list. This ensures that subscribers who saw the original announcement also see the correction.
When an incorrect download URL has already been widely shared, correcting the announcement email alone may not be sufficient.
In these cases, projects sometimes add a redirect so users who follow the original link still reach the correct download location.
Announcement threads sometimes include feedback about where signatures and hashes are linked, and whether those links are correct and usable.
When this feedback is raised, projects typically address it by correcting the published links.