Publish a short, factual notice: which versions are bad, how users can check, what to do, what happened to your access, and what you changed. Put the actionable part first and the narrative second. Users need to fix their systems before they need to understand your story.
Why maintainers need a different shape
A company postmortem serves the company. A maintainer's postmortem serves thousands of unknown users who cannot call you. Many will never read it, so the first lines must stand on their own, and the notice should live where users look: the repository, the package page and any security advisory channel.
Put this at the top
- Affected versions. Exact numbers, with release dates and times in UTC.
- Fixed version. What to upgrade to.
- How to check. The command or file to inspect to see whether a bad version is installed.
- What to do if affected. Remove, upgrade, and rotate any secrets the build or runtime could read.
If the package ran install time code, say so, because that means affected machines may need cleanup beyond upgrading.
Then explain what happened
State only what you have confirmed. For example, how the publish happened, which credential or account was involved, and how long the bad versions were live. Avoid naming suspects. If you do not know the entry point, say that.
Do not shame yourself or anyone else. Google's SRE guidance describes blameless writing as assuming everyone involved had good intentions and did the right thing with the information they had. That fits volunteer maintainers well.
Describe the changes to your access
Users want to know whether it can recur. List the concrete steps you took, such as rotating publishing credentials, enabling stronger sign in on the registry account, limiting who can publish, or moving to a publish flow that does not rely on a long lived token. Only list steps you actually completed.
Coordinate with the registry
Report the incident to the registry's security contact, ask for the bad versions to be removed or marked, and request an advisory. Link the advisory in your notice so tools that read advisories can pick it up.
Keep it updated
Date every edit. If new facts change the scope, say so at the top. When the incident is closed, add a closing note and keep the page up. Removing a notice makes it harder for late discoverers to protect themselves.
A short template
| Part | Content |
|---|---|
| Status | Active, contained, closed, with date |
| Affected | Versions and window |
| Check | How to test your own install |
| Fix | Version and steps |
| What happened | Confirmed facts only |
| What changed | Completed access changes |
| Contact | Where to report concerns |
Quick check
Should I delete the bad versions myself?
Registry rules differ. Contact the registry security team first, and publish a fixed version and a clear notice.
What if I do not know how it happened?
Say so. List what you have ruled out, and update the notice if you learn more.
Sources
Last reviewed: 19 October 2026.
