This guide was generated from real release announcement discussions on the Apache Incubator mailing list and reflects practical issues encountered when announcing podling releases.

Who This Guide Is For

This guide is intended for:

  • Podling PPMCs
  • Release managers
  • Incubator mentors
  • IPMC members

It is designed to support practical decision-making when drafting and sending a release announcement and when correcting an announcement after feedback.

Unifying Principle

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.

Purpose

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.

1. Announcements Should Link to the Project Download Page

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.

2. Use Existing ASF Announcements as Examples

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.

3. Incorrect Links Should Be Corrected Publicly

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.

4. Redirects May Be Needed After Incorrect Links Are Published

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.

5. Signature and Hash Links May Be Commented On

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.

6. Key Takeaways for PPMCs, Mentors, and the IPMC

  • Announcements should point to the download page
  • Verification links should be clear and usable
  • No labels