Skip to content

docs: make it clear that deleting apps, releases, and patches is permanent - #669

Merged
AbhishekDoshi26 merged 7 commits into
mainfrom
docs/deletion-is-permanent
Sep 17, 2026
Merged

AbhishekDoshi26 merged 7 commits into
mainfrom
docs/deletion-is-permanent

Conversation

@AbhishekDoshi26

@AbhishekDoshi26 AbhishekDoshi26 commented Sep 16, 2026

Copy link
Copy Markdown
Member

Why

Deleting an app, a release, or a patch is permanent, but the docs only spelled
that out for account deletion. Users regularly reach out asking support to
restore a deleted app or release, and there is nothing to restore.

What changed

  • New page: Delete Apps, Releases, and Patches (code-push/delete.mdx, sidebar "Delete", lands between Tracks and Uninstall). One findable place to point users at: what each deletion removes, where the confirmation dialog appears, and the reversible alternatives.
  • release.mdx - the existing danger callout said only "not reversible". Now titled "Deleting a release is permanent", states it is not restorable, notes the console confirmation dialog, and points to rollback. Added a line after the platform-selection screenshot noting that confirming is immediate and permanent.
  • patch.mdx - new "Delete a patch" section under Manage patches. There is no way to delete an individual patch, so patches are only removed along with their release or app. The docs now say that instead of implying a patch can be deleted on its own.
  • faq.mdx - new entry "Can you restore a deleted app, release, or patch?" under Use cases & limitations, since that is where people searching are likely to land.
  • account/delete-account.mdx - cross-link to the new page.

Throughout, the docs steer users toward rollback rather than deletion for a
bad patch. Rollback is genuinely reversible (the console exposes a "Roll Forward"
action), so it is the right answer for the case that usually prompts someone to
delete a release in a panic.

Notes for review

  • An earlier draft made a claim about data not being recoverable that went
    further than it should have about how things work internally. I have cut it.
    The published text now says only what is true from the user's side: no trash,
    no archive, no undo, and support will not restore an individual deleted
    resource. Ping me offline for the detail behind that change.
  • The docs say devices stop receiving patches for a deleted release version.
    I deliberately did not claim either way whether a device that already
    installed a patch keeps running it, since I could not confirm the device-side
    behavior. If you know the answer, it is worth stating explicitly.
  • The app-deletion sentence about installed apps continuing to work is taken
    from the delete-app confirmation dialog's own copy.
  • Follow-up PR documents the "Roll Forward" action, which rollback.mdx
    currently does not mention at all.

Verification

prettier, cspell, and vale clean; astro build passes with "All internal
links are valid".

…anent

Deleting an app, release, or patch is a hard delete on the backend, but the
docs only spelled out "permanent and cannot be undone" for account deletion.
Users regularly ask support to restore deleted apps and releases.

- Add a Delete Apps, Releases, and Patches page covering what each deletion
  removes, where the confirmation dialog appears, and reversible alternatives
  (rollback, staging tracks, transfer ownership).
- Strengthen the danger callout on "Delete releases" and note the console
  confirmation dialog.
- Document that individual patches cannot be deleted, only removed with their
  release or app.
- Add an FAQ entry answering "Can you restore a deleted app, release, or
  patch?" and cross-link from the account deletion page.
The release delete dialog's platform choice changes what actually happens:
"All" deletes the release row and its patches, while picking a single
platform deletes only that platform's release and patch binaries and leaves
the release in place. The page described the two as one operation.
@AbhishekDoshi26

Copy link
Copy Markdown
Member Author

Self-review

Re-read this with fresh eyes against the console and backend source. One real accuracy bug found and fixed in ba1b463; the rest is context for review.

Fixed: the page described two different release deletions as one

The platform picker in the delete dialog is not just a scope filter, it selects a different operation:

  • All deletes the release itself along with its patches.
  • A single platform deletes only that platform's release and patch binaries. The release survives, and other platforms are untouched.

The page originally said deleting a release "deletes the release, its artifacts, and every patch published to it for the platforms you select," which is wrong for the single-platform case, and the follow-on claim that "devices will no longer receive patches for that release version" only holds for All. Both are now split out explicitly. Please sanity check that split against what you know of the intended behavior, since it is the one thing here I would most expect to have gotten subtly wrong.

Verified

  • The hard-delete claim. App and release deletion are unconditional DELETE statements with no soft-delete column, and per-platform deletion removes the objects from the release and patch artifact buckets. Nothing here is recoverable by the user.
  • "Patches cannot be deleted on their own." There is no patch delete route, console component, or CLI command. Patches go away only with their release or app.
  • Every deletion described does show a confirmation dialog, account deletion included.
  • "A rollback can be undone" holds wherever rollback is offered at all, which is the same condition under which the console offers Rollback rather than Deactivate. docs: document the Roll Forward patch action #670 documents that.
  • The app-deletion sentence about installed apps continuing to work is the delete-app dialog's own copy.

Still open for you

  • I did not claim whether a device that already installed a patch keeps running it after its release is deleted. The server stops advertising the patch, but the uninstall signal is the rolled-back-patch list, which would be empty for a deleted release, and the updater is in another repo so I could not confirm the device half. This is probably the single most common thing a user will want to know, so worth stating outright if you know it.
  • An earlier draft asserted something stronger than it should have about internal recovery mechanisms. That wording is gone; the text now speaks only to what the user can and cannot do. Ping me offline for the detail.
  • order: 8 ties with uninstall.mdx. It resolves to Tracks, Delete, Uninstall, which reads fine, but say the word if you want an explicit order.

prettier, cspell, vale clean; astro build reports all internal links valid.

AbhishekDoshi26 and others added 3 commits September 16, 2026 15:56
Keep a single, plain statement that deletions can't be restored, but drop
the alarmist framing (danger asides, bold "not restorable", "point of no
return", "support cannot help afterwards") and lead with what users can do
instead: roll back a patch, use a staging track, or transfer ownership.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

@dawn-ducky dawn-ducky left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please make changes for improved clarity.

Comment thread src/content/docs/code-push/delete.mdx Outdated
Comment thread src/content/docs/code-push/delete.mdx Outdated
Comment thread src/content/docs/code-push/delete.mdx Outdated
Comment thread src/content/docs/code-push/delete.mdx Outdated
Comment thread src/content/docs/code-push/delete.mdx Outdated
Comment thread src/content/docs/code-push/delete.mdx Outdated
- Use a plain permanence note without the pointer to alternatives
- Move Before you delete to the top and lead with rollback
- Remove the summary table in favor of the per-type sections
- Explain that releases are deleted per platform
- Put app deletion consequences before the steps
- Clarify that Transfer Ownership moves an app to another organization
@AbhishekDoshi26
AbhishekDoshi26 merged commit c81c48f into main Sep 17, 2026
3 checks passed
@AbhishekDoshi26
AbhishekDoshi26 deleted the docs/deletion-is-permanent branch September 17, 2026 08:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants